From 64a613d0c9e096848f2a750d9ace46e705102a94 Mon Sep 17 00:00:00 2001 From: alator-fd Date: Wed, 21 Oct 2026 11:38:48 -0400 Subject: [PATCH 1/8] docs(ai-agents): add AI coding agent overview, quickstart, guides and command reference Pages for running an AI coding agent from a Flox environment with flox agent: the harness, agent plugins and sandboxes, a quickstart with Claude Code and the frontend-design plugin, guides for packaging a skill repository, auditing a plugin and launching in a sandbox, and reference pages for list, launch, import, audit and check-plugin. Navigation is added separately. --- ai-agents/guides/audit-a-plugin.mdx | 97 ++++++++++++++ ai-agents/guides/launch-in-a-sandbox.mdx | 103 +++++++++++++++ .../guides/package-a-skill-repository.mdx | 115 ++++++++++++++++ ai-agents/overview.mdx | 81 ++++++++++++ ai-agents/quickstart.mdx | 104 +++++++++++++++ ai-agents/reference/flox-agent-audit.mdx | 123 ++++++++++++++++++ .../reference/flox-agent-check-plugin.mdx | 70 ++++++++++ ai-agents/reference/flox-agent-import.mdx | 102 +++++++++++++++ ai-agents/reference/flox-agent-launch.mdx | 104 +++++++++++++++ ai-agents/reference/flox-agent-list.mdx | 63 +++++++++ styles/config/vocabularies/Flox/accept.txt | 9 ++ 11 files changed, 971 insertions(+) create mode 100644 ai-agents/guides/audit-a-plugin.mdx create mode 100644 ai-agents/guides/launch-in-a-sandbox.mdx create mode 100644 ai-agents/guides/package-a-skill-repository.mdx create mode 100644 ai-agents/overview.mdx create mode 100644 ai-agents/quickstart.mdx create mode 100644 ai-agents/reference/flox-agent-audit.mdx create mode 100644 ai-agents/reference/flox-agent-check-plugin.mdx create mode 100644 ai-agents/reference/flox-agent-import.mdx create mode 100644 ai-agents/reference/flox-agent-launch.mdx create mode 100644 ai-agents/reference/flox-agent-list.mdx diff --git a/ai-agents/guides/audit-a-plugin.mdx b/ai-agents/guides/audit-a-plugin.mdx new file mode 100644 index 0000000..c622814 --- /dev/null +++ b/ai-agents/guides/audit-a-plugin.mdx @@ -0,0 +1,97 @@ +--- +title: "Audit an agent plugin" +sidebarTitle: "Audit a plugin" +description: "Scan an agent plugin for security issues with SkillSpector before or after you install it." +--- + +A plugin's skills are instructions your agent follows. +Before you install one, you can scan it for prompt injection, credential access, and other risky patterns. +`flox agent audit` runs NVIDIA SkillSpector over each skill and scores the plugin from 0 to 100, where higher is better. + +## Install the scanner + +The audit needs the `skillspector` program and network access to `api.osv.dev`, which it uses for live vulnerability data. +Install SkillSpector into your environment: + +```bash +flox install agent-stacks/skillspector +``` + +## Audit a package before installing it + +Name the catalog package. +Flox fetches it into a temporary environment, audits it, and deletes the temporary environment afterwards: + +```console +$ flox agent audit agent-stacks/agent-plugin-frontend-design +agent-stacks/agent-plugin-frontend-design → /nix/store/44fwh49l…-agent-plugin-frontend-design-0.0.0-unstable.2026-10-19.ga0b04d9 +skillspector 2.12.0 · static · osv live 2026-10-21T15:34Z + +Checking + skills/frontend-design (1 skill) +Validated only + plugin.json + + skills/frontend-design 87 safe 1 finding + + HIGH AR2 Anti-Refusal Statement skills/frontend-design/SKILL.md:69 + +score 87 · safe (worst: skills/frontend-design) +1 finding: 1 high +``` + +Add `@` to audit a specific version, for example `agent-stacks/agent-plugin-caveman@4.0.1`. + +## Audit what is already installed + +Pass a path instead of a package name. +A path starts with `./`, `../`, `/`, or `~/`. +To audit one installed plugin: + +```bash +flox agent audit "$FLOX_ENV/share/agent-plugins/frontend-design" +``` + +To audit every plugin in the active environment and get one overall score: + +```bash +flox agent audit "$FLOX_ENV" +``` + +A bare word is always read as a package, so `flox agent audit frontend-design` looks in the catalog, not in your environment. + +## Read the result + +Each skill gets its own score, and the plugin scores its worst skill. +The bands are SkillSpector's: + +| Score | Status | +| ----- | ------ | +| 80–100 | `safe` | +| 50–79 | `caution` | +| 0–49 | `do not install` | + +Findings are listed with their severity, rule, and the file and line that matched. +HIGH and CRITICAL findings move the score most. +For a `caution` score, read each finding and decide whether the skill's text justifies it. + +The audit also says what it did **not** check. +It scans skills only. +MCP server configuration, hooks, `bin/`, and files outside the plugin layout are listed under "Not checked", and the score says nothing about them. +Nothing is executed, and no language model reads the plugin. + +## Gate on a score in CI + +`--threshold` makes the audit exit with status 1 when the score is below the number you give: + +```bash +flox agent audit "$FLOX_ENV" --threshold 80 +``` + +A threshold of 80 fails on anything that is not `safe`. +On a slow runner, give each skill's scan more time with `--scan-timeout`, for example `--scan-timeout 15m`. + +## Related + +- [`flox agent audit`](/ai-agents/reference/flox-agent-audit) reference, including the JSON output and exit codes +- [`flox agent check-plugin`](/ai-agents/reference/flox-agent-check-plugin), which checks that a plugin follows the specification rather than whether it is safe diff --git a/ai-agents/guides/launch-in-a-sandbox.mdx b/ai-agents/guides/launch-in-a-sandbox.mdx new file mode 100644 index 0000000..06300b1 --- /dev/null +++ b/ai-agents/guides/launch-in-a-sandbox.mdx @@ -0,0 +1,103 @@ +--- +title: "Launch an agent in a sandbox" +sidebarTitle: "Launch in a sandbox" +description: "Run an AI coding agent inside a sandbox package that limits the files and hosts it can reach." +--- + +Installing a harness and its plugins in an environment decides what the agent brings with it. +A sandbox decides what the agent can reach once it runs. +This guide runs Claude Code inside a sandbox from the same environment. + +You need an environment set up as in the [quickstart](/ai-agents/quickstart). + +## Choose a sandbox + +Each sandbox is a package. +Two are available: + +| Sandbox | Package | macOS | Linux | +| ------- | ------- | ----- | ----- | +| `srt` | `agent-stacks/agent-sandbox-srt` | Seatbelt | bubblewrap and seccomp | +| `nono` | `agent-stacks/agent-sandbox-nono` | Seatbelt | Landlock | + +`srt` runs the agent inside Anthropic's sandbox-runtime. +Network access is limited to the hosts it allows. +`nono` leaves the network open until you list allowed hosts, and needs no administrator setup on Linux. + +Install the one you want: + +```bash +flox install agent-stacks/agent-sandbox-srt +``` + +## Launch the agent in the sandbox + +Pass `--sandbox` between `launch` and the harness name: + +```bash +flox agent launch --sandbox srt claude +``` + +The sandbox prints a line saying it is running the agent, then Claude Code starts as usual. +If the sandbox package is not installed, the launch stops before starting anything and names the package to install. + +Start the agent from your project folder. +The project folder is writable inside the sandbox, so both sandboxes refuse to start in `/` or in your home folder. + +## What the sandbox allows + +Both sandboxes start from these defaults: + +- The project folder is writable, along with `/tmp` and Claude's own state (`~/.claude` and `~/.claude.json`). +- `~/.ssh` cannot be read. +- Claude's API hosts are reachable, as is every host named by an MCP server of the installed plugins. + +With `srt`, no other host is reachable. +With `nono`, the network stays open until you pass `allowedDomains`. + +## Pass options to the sandbox + +Pass options as one JSON object with `--sandbox-options`. +Both sandboxes accept the same three keys, and each value is a list of strings that is added to the defaults: + +| Key | Adds | +| --- | ---- | +| `allowedDomains` | Hosts the agent can reach | +| `allowWrite` | Paths the agent can write | +| `denyRead` | Paths the agent cannot read | + +For example, to let the agent reach GitHub: + +```bash +flox agent launch --sandbox srt --sandbox-options '{"allowedDomains": ["github.com"]}' claude +``` + +`flox agent launch` checks only that the value is a JSON object. +The sandbox checks the keys, and reports an unknown key or a value that is not a list of strings without starting the agent. + +To see the settings `srt` would apply without starting the agent, set `AGENT_SANDBOX_SRT_DRY_RUN=1`. +For `nono`, the variable is `AGENT_SANDBOX_NONO_DRY_RUN=1`. + +```bash +AGENT_SANDBOX_SRT_DRY_RUN=1 flox agent launch --sandbox srt claude +``` + +## Flags for the agent + +Flags for `flox agent launch` go before the harness name. +Everything after the harness name belongs to the harness: + +```bash +flox agent launch --sandbox srt claude -- --continue +``` + +## Ubuntu 24.04 and later + +Ubuntu 24.04 restricts unprivileged user namespaces, which `srt` needs on Linux. +When that restriction is on, `agent-sandbox-srt` stops and prints the one-time administrator step that allows it. +`nono` does not need this step. + +## Related + +- [`flox agent launch`](/ai-agents/reference/flox-agent-launch) reference +- [AI coding agents](/ai-agents/overview) diff --git a/ai-agents/guides/package-a-skill-repository.mdx b/ai-agents/guides/package-a-skill-repository.mdx new file mode 100644 index 0000000..8825a1b --- /dev/null +++ b/ai-agents/guides/package-a-skill-repository.mdx @@ -0,0 +1,115 @@ +--- +title: "Package a skill repository" +sidebarTitle: "Package a skill repository" +description: "Turn a GitHub repository of agent skills into a pinned agent plugin package and install it into a Flox environment." +--- + +Many skill collections live in GitHub repositories rather than in the catalog. +`flox agent import` reads such a repository, finds its plugins and skills, and writes a package definition pinned to one commit. +This guide imports a repository, builds the package, checks it, and installs it into an environment. + +The agent plugin packages in the `agent-stacks` catalog are generated this way, in the [agent-pkgs](https://github.com/agent-stacks/agent-pkgs) repository. +The steps below build in a checkout of that repository, which provides the builder the generated package needs. + +## Prerequisites + +- An environment with `flox/flox-agent` installed, as in the [quickstart](/ai-agents/quickstart). +- Nix, to build the package. +- A clone of agent-pkgs: + +```bash +git clone https://github.com/agent-stacks/agent-pkgs.git && cd agent-pkgs +``` + +Run the commands below in a shell where your environment is active, so `flox agent` is available. + +## Import the repository + +Pass the repository as `owner/repo`, a GitHub URL, or a local clone whose `origin` is on GitHub. +Write the package into the `pkgs` folder: + +```bash +flox agent import juliusbrussee/caveman --out pkgs +``` + +Import pins the current commit, finds every plugin in the repository, and validates each one. +It prints a warning for anything it packages with a deviation and for anything it leaves out, then a summary per plugin: + +```console +caveman: new plugin at bad48a0e1df5 (22 skills) + written to pkgs/agent-plugin-caveman +``` + +Each plugin becomes a folder holding two files: + +- `source.json` records the pinned source, the skills, and the import that produced them, including its warnings. +- `default.nix` reads `source.json` and is the same in every package. + +Import only reads from GitHub. +Repositories hosted elsewhere are rejected. + +### Choose what gets imported + +Most repositories need no flags. +When discovery finds the wrong thing, these flags adjust it, and import records them in `source.json` so a later re-import repeats them: + +| Flag | Use it to | +| ---- | --------- | +| `--plugin PATH[=NAME]` | Treat a folder as a plugin, and optionally name it | +| `--path-ignore GLOB` | Skip matching paths, such as test fixtures | +| `--no-auto-discovery` | Import only the `--plugin` folders | +| `--dependency ATTR` | Name a Nixpkgs package a script's interpreter comes from | + +See the [`flox agent import`](/ai-agents/reference/flox-agent-import) reference for how discovery works. + +## Build and check the package + +The build fetches only tracked files, so add the new folder to git first: + +```bash +git add pkgs/agent-plugin-caveman && nix build .#agent-plugin-caveman +``` + +Check the built plugin against the Agent Plugins specification: + +```bash +flox agent check-plugin result/share/agent-plugins/caveman +``` + +Scan it for security issues: + +```bash +flox agent audit ./result +``` + +See [Audit an agent plugin](/ai-agents/guides/audit-a-plugin) for how to read the score. + +## Install it into your environment + +From your project's environment, install the package from the agent-pkgs checkout: + +```bash +flox install "git+file://$HOME/agent-pkgs#agent-plugin-caveman" +``` + +Replace `$HOME/agent-pkgs` with the path to your clone. +`flox agent list` now shows the plugin, and the next `flox agent launch` loads it. + +## Update the package + +Run the same import again to move to the repository's latest commit. +To repeat the flags recorded the first time, use `--replay`: + +```bash +flox agent import juliusbrussee/caveman --out pkgs --replay +``` + +The summary says `unchanged`, `regenerated`, or the old and new commit, with the skills added and removed. + +To have the plugin published in the `agent-stacks` catalog, open a pull request to agent-pkgs with the generated folder. +Packages there are re-imported automatically when their upstream moves. + +## Related + +- [`flox agent import`](/ai-agents/reference/flox-agent-import) reference +- [`flox agent check-plugin`](/ai-agents/reference/flox-agent-check-plugin) reference diff --git a/ai-agents/overview.mdx b/ai-agents/overview.mdx new file mode 100644 index 0000000..403dc97 --- /dev/null +++ b/ai-agents/overview.mdx @@ -0,0 +1,81 @@ +--- +title: "AI coding agents" +description: "Put an AI coding agent, its plugins, and a sandbox in a Flox environment, and launch the agent with exactly that set." +--- + +An AI coding agent is only as predictable as the things it loads. +Claude Code picks up skills, MCP servers, and hooks from your home directory, from marketplaces, and from whatever someone installed last week. +Two developers running "the same" agent are rarely running the same thing. + +Flox lets you declare the agent setup the way you declare any other toolchain: as packages in an environment. +You install three kinds of package, and `flox agent` launches the agent with exactly what the environment holds. + +## Harness, plugins, sandboxes + +**The harness** is the agent program itself, such as Claude Code. +It comes from the `agent-stacks` catalog on FloxHub as an ordinary package, so its version is pinned in the lockfile like everything else. + +| Harness | Package | Launch name | +| ------- | ------- | ----------- | +| Claude Code | `agent-stacks/claude-code` | `claude` | +| OpenAI Codex | `agent-stacks/codex` | `codex` | +| opencode | `agent-stacks/opencode` | `opencode` | +| pi | `agent-stacks/pi` | `pi` | +| Agent Deck | `agent-stacks/agent-deck` | `agent-deck` | + +**Agent plugins** carry what the agent can use: skills, MCP servers, and, for Claude Code, hooks, agents, and commands. +Each plugin is a package named `agent-stacks/agent-plugin-`, built from a pinned commit of its upstream repository. +An installed plugin lands in the environment under `share/agent-plugins//`. +Claude Code receives whole plugins. +Codex, opencode, and pi receive the plugins' skills only. + +**A sandbox** limits what the agent can reach once it runs: which files it can write, which files it can read, and which hosts it can contact. +Each sandbox is a package named `agent-stacks/agent-sandbox-`, and you choose one when you launch. + + + Agent plugins are packages an AI agent loads. + They are unrelated to the `[plugins]` section of the manifest, which is described in [Plugins](/concepts/plugins). + + +## What `flox agent launch` does + +When you run `flox agent launch claude`, Flox: + +1. Finds the harness on the environment's `PATH`. +2. Reads every agent plugin installed in the environment. +3. Stages those plugins in the environment's cache, under `.flox/cache/agent-stacks/`. +4. Starts the harness with the staged plugins, through a sandbox if you asked for one. + +Your own agent configuration is left alone. +The plugins apply to that one agent process, so `~/.claude` and your login are not changed, and a `claude` started outside the environment does not see them. + +## Why a Flox environment + +- **Reproducible.** The harness and every plugin are pinned in `manifest.lock`. A teammate who activates the same environment launches the same agent with the same skills. +- **Shareable.** Push the environment to FloxHub and the whole setup travels with it. See [Sharing environments](/tutorials/sharing-environments). +- **Reviewable.** Changing the agent's skills is a change to the manifest, so it shows up in a diff and in the environment's [generations](/concepts/generations). +- **Auditable.** You can scan a plugin for security issues before you install it. See [Audit an agent plugin](/ai-agents/guides/audit-a-plugin). + +## Requirements + +`flox agent` is a Flox extension provided by the `flox/flox-agent` package. +Extensions are a beta feature, so enable beta features once: + +```bash +flox config --set features.beta true +``` + +Alternatively, set `FLOX_FEATURES_BETA=true` in your shell. + +## Usage data + +`flox agent` follows the same consent and opt-out as the Flox CLI. +It can send crash reports and usage events: the command that ran, the operating system, the release, counts of plugins and skills, and whether the command succeeded. +It never sends names, paths, file contents, or arguments. +`flox config --set disable_metrics true`, `FLOX_DISABLE_METRICS=true`, or `DO_NOT_TRACK=1` turns both off. + +## Next steps + +- [Quickstart](/ai-agents/quickstart): launch Claude Code with a plugin in a few minutes. +- [Launch an agent in a sandbox](/ai-agents/guides/launch-in-a-sandbox) +- [Package a skill repository](/ai-agents/guides/package-a-skill-repository) diff --git a/ai-agents/quickstart.mdx b/ai-agents/quickstart.mdx new file mode 100644 index 0000000..456b2db --- /dev/null +++ b/ai-agents/quickstart.mdx @@ -0,0 +1,104 @@ +--- +title: "AI agent quickstart" +sidebarTitle: "Quickstart" +description: "Install Claude Code and an agent plugin into a Flox environment, then launch the agent with that plugin." +--- + +In this guide you create an environment holding Claude Code and the `frontend-design` plugin, check what the agent will get, and launch it. +You need [Flox installed](/install-flox/install) and a Claude account. + +## Enable the extension + +`flox agent` is a beta Flox extension. +Turn on beta features once: + +```bash +flox config --set features.beta true +``` + +## Create the environment + +Make a folder for your project and create an environment in it: + +```bash +mkdir my-agent && cd my-agent && flox init +``` + +Install the harness, a plugin, and the `flox agent` extension: + +```bash +flox install agent-stacks/claude-code agent-stacks/agent-plugin-frontend-design flox/flox-agent +``` + +- `agent-stacks/claude-code` is the harness: the Claude Code program. +- `agent-stacks/agent-plugin-frontend-design` is an agent plugin with a skill for building polished web interfaces. +- `flox/flox-agent` provides the `flox agent` command. + +## See what the agent gets + +Activate the environment: + +```bash +flox activate +``` + +Then list the stack: + +```console +$ flox agent list +Agent stack +1 harness · 1 plugin · 1 skill · 0 MCP servers + +Harnesses + ✔ claude claude-code 2.1.304 · skills, MCP, hooks + +Plugins + ✔ frontend-design agent-plugin-frontend-design 0.0.0-unstable.2026-10-19.ga0b04d9 · 1 skill + +--long shows each plugin's skills and MCP servers. +Shows what launch gives each harness; agent-stacks writes nothing to a harness's own config. +``` + +Each row names the package and version it came from. +Run `flox agent list --long` to see the skills each plugin provides. + +## Launch the agent + +```bash +flox agent launch claude +``` + +Claude Code starts with the `frontend-design` skill loaded. +Ask it to build a page, and it uses the skill. + +To pass flags to Claude Code, put them after `--`: + +```bash +flox agent launch claude -- --continue +``` + +## Add or remove plugins + +Plugins are packages, so you manage them with the usual commands. +Browse the available plugins with [`flox search`](/man/flox-search): + +```bash +flox search agent-plugin +``` + +Install another one with [`flox install`](/man/flox-install), or remove one with [`flox uninstall`](/man/flox-uninstall). +The next `flox agent launch` picks up the change. + +## If something is missing + +`flox agent doctor` reports the plugins it found, each harness's readiness, and the package to install for a harness that is missing: + +```bash +flox agent doctor +``` + +## Next steps + +- [Launch an agent in a sandbox](/ai-agents/guides/launch-in-a-sandbox) +- [Audit an agent plugin](/ai-agents/guides/audit-a-plugin) before you install it +- [`flox agent launch`](/ai-agents/reference/flox-agent-launch) reference diff --git a/ai-agents/reference/flox-agent-audit.mdx b/ai-agents/reference/flox-agent-audit.mdx new file mode 100644 index 0000000..a340a05 --- /dev/null +++ b/ai-agents/reference/flox-agent-audit.mdx @@ -0,0 +1,123 @@ +--- +title: "flox agent audit" +description: "Security-audit an agent plugin, by path or by catalog package, with NVIDIA SkillSpector." +--- + +## Synopsis + +```text +flox agent audit [--json] [--threshold N] [--raw] [--scan-timeout D] +``` + +## Description + +Finds the plugin `` names, validates it, lists what it will and will not look at, scans each skill with SkillSpector, and scores the plugin from 0 to 100 by its worst skill. +Higher is better. + +`audit` measures security only. +Whether a plugin follows the specification is [`flox agent check-plugin`](/ai-agents/reference/flox-agent-check-plugin)'s job. + +SkillSpector always runs statically, as `skillspector scan --no-llm --format json`. +Nothing in the plugin is executed. + +## The target + +A target is a path or a package, decided by how it is written. + +A **path** is `.`, `..`, or anything starting with `./`, `../`, `/`, or `~/`. +If the path holds `plugin.json`, it is the plugin. +Otherwise every plugin under its `share/agent-plugins/` is audited, so `$FLOX_ENV` and a `./result` from a build both work. + +Anything else is a **catalog package**, with `@` allowed. +`audit` installs it into a temporary environment, audits it, and deletes the environment when it finishes or is interrupted. +A flake reference, which holds `:` or `#`, is refused. + +There is no shorthand for an installed plugin. +`flox agent audit caveman` audits the catalog package `caveman`; audit an installed plugin by its path, such as `"$FLOX_ENV/share/agent-plugins/caveman"`. + +## Options + +Options can go on either side of ``. + +| Option | Effect | +| ------ | ------ | +| `--json` | Print the result as JSON instead of the summary | +| `--threshold N` | Exit with status 1 when the score is below `N` | +| `--raw` | Include SkillSpector's own report for each skill | +| `--scan-timeout D` | Stop a skill's scan after `D`, such as `90s` or `15m` (default `5m`) | + +## What is checked + +| Entry | Treatment | +| ----- | --------- | +| Each `skills/` with a `SKILL.md` | Scanned | +| `plugin.json` | Validated only | +| `mcp.json` | Not checked | +| `bin/` | Not checked | +| Client folders such as `com.anthropic.claude-code/`, which hold hooks, agents, and commands | Not checked | +| Anything else | Not checked | + +The summary lists every entry under one of these headings. +The score says nothing about the entries that were not checked. + +## Score + +Each skill scores `100 - risk`, using SkillSpector's risk model. +The plugin scores its worst skill, and several plugins score their worst plugin. + +| Score | Status | +| ----- | ------ | +| 80–100 | `safe` | +| 50–79 | `caution` | +| 0–49 | `do not install` | + +A scan SkillSpector reports as partial is still scored and marked `partial`. +When a partial scan covered less than 100% of a skill, the skill is `incomplete` rather than `safe`, and the result fails any `--threshold`. + +## Exit status + +| Status | Meaning | +| ------ | ------- | +| `0` | Scored, and met `--threshold` if one was given | +| `1` | Scored below `--threshold`, or a skill is incomplete under `--threshold`; the result is still printed | +| `2` | Usage error | +| `3` | Could not audit, such as a target that does not resolve or a missing prerequisite; nothing is printed on standard output | +| `130` | Interrupted | + +## Requirements + +- `skillspector` on `PATH`, from the `agent-stacks/skillspector` package. +- Network access to `api.osv.dev`, for live vulnerability data. + +`flox agent doctor` shows the SkillSpector version `audit` will use. + +## Examples + +Audit a catalog package before installing it: + +```bash +flox agent audit agent-stacks/agent-plugin-frontend-design +``` + +Audit a specific version: + +```bash +flox agent audit agent-stacks/agent-plugin-caveman@4.0.1 +``` + +Audit every plugin in the active environment: + +```bash +flox agent audit "$FLOX_ENV" +``` + +Fail a CI job on anything below `safe`: + +```bash +flox agent audit "$FLOX_ENV" --threshold 80 +``` + +## See also + +- [Audit an agent plugin](/ai-agents/guides/audit-a-plugin) +- [`flox agent check-plugin`](/ai-agents/reference/flox-agent-check-plugin) diff --git a/ai-agents/reference/flox-agent-check-plugin.mdx b/ai-agents/reference/flox-agent-check-plugin.mdx new file mode 100644 index 0000000..41214a3 --- /dev/null +++ b/ai-agents/reference/flox-agent-check-plugin.mdx @@ -0,0 +1,70 @@ +--- +title: "flox agent check-plugin" +description: "Validate an agent plugin folder against the Agent Plugins and Agent Skills specifications." +--- + +## Synopsis + +```text +flox agent check-plugin [--json] [--strict] +``` + +## Description + +Validates a plugin folder against the [Agent Plugins specification](https://agent-plugins.org), and each of its skills against the [Agent Skills specification](https://agentskills.io). +It reports problems and never changes the folder. + +The same check runs when `flox agent import` writes a package and when that package is built. + +`` is a plugin folder: + +```text +/ +├── plugin.json # required manifest +├── skills/ # required, one folder per skill +│ └── /SKILL.md +└── mcp.json # optional MCP server configuration +``` + +## Options + +| Option | Effect | +| ------ | ------ | +| `--json` | Print the result as JSON: `valid`, `specVersion`, `errors`, and `warnings`, each issue with a `path` and a `message` | +| `--strict` | Treat warnings as errors | + +## What is checked + +- `plugin.json` exists, is valid JSON, and matches the schema its `$schema` names. +- The folder's name matches the manifest's `name`. +- `skills/` holds at least one skill: a folder directly under it with a file named exactly `SKILL.md`. Symbolic links are not followed. +- Each `SKILL.md` has frontmatter with a `name` and a `description` that follow the Agent Skills rules. +- `mcp.json`, when present, matches the MCP schema for the same specification version as `plugin.json`. +- Each local MCP server's `command` is a bare program name or a `./` path inside the plugin. + +## Warnings and errors + +A deviation that agents load anyway is a warning, and the plugin stays valid. +Common warnings are unknown frontmatter fields, such as `version:`, a skill `name` that does not match its folder, and a missing `description`. +Claude Code components such as `agents/` or `hooks/hooks.json` at the plugin root also warn, because packages keep them under `com.anthropic.claude-code/`. + +Everything else is an error, including any schema violation and a symbolic link under `skills/`. + +## Exit status + +| Status | Meaning | +| ------ | ------- | +| `0` | Valid; warnings are allowed unless `--strict` is given | +| `1` | Invalid: one or more errors, or warnings under `--strict` | +| `2` | Usage error, or the path is missing or unreadable | + +## Example + +```bash +flox agent check-plugin "$FLOX_ENV/share/agent-plugins/frontend-design" +``` + +## See also + +- [`flox agent audit`](/ai-agents/reference/flox-agent-audit), which checks a plugin for security issues +- [Package a skill repository](/ai-agents/guides/package-a-skill-repository) diff --git a/ai-agents/reference/flox-agent-import.mdx b/ai-agents/reference/flox-agent-import.mdx new file mode 100644 index 0000000..9c54cc8 --- /dev/null +++ b/ai-agents/reference/flox-agent-import.mdx @@ -0,0 +1,102 @@ +--- +title: "flox agent import" +description: "Generate a pinned agent plugin package from a GitHub repository of skills." +--- + +## Synopsis + +```text +flox agent import [--out ] [--plugin ]... + [--path-ignore ]... [--dependency ]... + [--no-auto-discovery] +flox agent import [--out ] --replay +``` + +## Description + +Reads a skill repository, finds the plugins in it, and writes one package definition per plugin, pinned to a single commit. + +`` is an `owner/repo` shorthand, a GitHub URL, or a local git clone. +Only GitHub is supported. +A local clone is imported at its committed `HEAD`, and its `origin` remote must point at GitHub; uncommitted changes are never imported. + +Import: + +1. Clones the repository and pins the commit. +2. Finds every plugin and its skills. +3. Computes the hash of the source the build will fetch. +4. Validates each plugin with the [`check-plugin`](/ai-agents/reference/flox-agent-check-plugin) rules. A plugin with errors is not written; the others are. +5. Writes `agent-plugin-/source.json` and `agent-plugin-/default.nix` under the output folder, and prints a summary. + +The summary is `new plugin` on a first import. +On a re-import it is `unchanged at `, `regenerated at `, or ` -> ` with the skills added and removed. +There is no separate update command; re-importing is how a package moves to a newer commit. + +`source.json` records the source, the skills, the flags given, and every warning. +`default.nix` is the same in every package, apart from a block between its `BEGIN custom` and `END custom` markers that a re-import keeps. + +## Finding plugins + +Import tries these in order, and the first that matches declares the repository's plugins: + +1. Agent Plugins manifests (`plugin.json`). +2. A marketplace listing, such as `.claude-plugin/marketplace.json`. +3. Claude plugin manifests (`.claude-plugin/plugin.json`). +4. The whole repository as one plugin. + +The later cases still run for folders nothing has claimed, and a plugin they find there is added beside the declared ones. +The last case runs only when nothing else matched. +Within each plugin, import searches for `SKILL.md` files and records anything it does not package as a warning. + +## Options + +| Option | Repeatable | Effect | +| ------ | ---------- | ------ | +| `--out ` | No | Where to write packages. Default `.flox/pkgs/` | +| `--plugin ` | Yes | Treat `` as a plugin, named `` or after its folder | +| `--path-ignore ` | Yes | Never read or package anything matching `` | +| `--dependency ` | Yes | A Nixpkgs package the build may link a script's interpreter from, such as `R` for `Rscript` | +| `--no-auto-discovery` | No | Import only the `--plugin` folders | +| `--replay` | No | Repeat the flags recorded in the existing packages for this repository | + +Every option except `--out` and `--replay` is recorded in `source.json`. +`--replay` can be combined only with `--out`. + +A default output under `.flox` needs that `.flox` to be a Flox environment. +Run `flox init` first, or pass `--out` with a folder outside `.flox`. + +A package folder belongs to the repository that wrote it. +Import refuses to overwrite a package recorded from a different repository. + +## Exit status + +| Status | Meaning | +| ------ | ------- | +| `0` | Every plugin was imported | +| `1` | A plugin failed, or the clone or a write failed; the other plugins are still written | +| `2` | Usage error, including `--replay` with a flag other than `--out` | + +## Examples + +Import a repository into an agent-pkgs checkout: + +```bash +flox agent import juliusbrussee/caveman --out pkgs +``` + +Import a folder of skills that discovery misses, under a chosen name: + +```bash +flox agent import owner/repo --out pkgs --plugin skills=my-skills +``` + +Update a package, repeating the flags it was first imported with: + +```bash +flox agent import juliusbrussee/caveman --out pkgs --replay +``` + +## See also + +- [Package a skill repository](/ai-agents/guides/package-a-skill-repository) +- [`flox agent check-plugin`](/ai-agents/reference/flox-agent-check-plugin) diff --git a/ai-agents/reference/flox-agent-launch.mdx b/ai-agents/reference/flox-agent-launch.mdx new file mode 100644 index 0000000..100cf2a --- /dev/null +++ b/ai-agents/reference/flox-agent-launch.mdx @@ -0,0 +1,104 @@ +--- +title: "flox agent launch" +description: "Run an AI coding agent with the environment's agent plugins, optionally inside a sandbox." +--- + +## Synopsis + +```text +flox agent launch [--sandbox [--sandbox-options '']] [-- ...] +``` + +## Description + +Runs `` with every agent plugin installed in the active environment, then gets out of the way. +The agent replaces the `flox agent` process, so its exit status and terminal are yours. + +`` is one of: + +| Agent | Harness package | What it receives | +| ----- | --------------- | ---------------- | +| `claude` | `agent-stacks/claude-code` | Whole plugins: skills, MCP servers, hooks, agents, and commands | +| `codex` | `agent-stacks/codex` | Skills | +| `opencode` | `agent-stacks/opencode` | Skills | +| `pi` | `agent-stacks/pi` | Skills | +| `agent-deck` | `agent-stacks/agent-deck` | Nothing directly; every Claude Code session it starts runs through `flox agent launch claude` | + +The agent is found on `PATH`, so the environment's harness wins over one installed elsewhere. +When the agent comes from outside the Nix store, such as a copy installed with npm or Homebrew, launch warns and runs it anyway. + +Each launch stages the plugins in its own folder under `.flox/cache/agent-stacks/launch/` and hands that to the agent. +Staged files are links into the installed packages, so nothing is copied. +Your own agent configuration, such as `~/.claude` and your login, is not changed. + +Launch prints a `note:` line for each hook a plugin runs and each setting it applies, and a warning for anything it leaves out. + +## Options + +Options for `launch` go between `launch` and ``. + +| Option | Effect | +| ------ | ------ | +| `--sandbox ` | Run the agent through the sandbox program `agent-sandbox-`, found on `PATH`. If it is missing, launch stops and names the package to install. | +| `--sandbox-options ''` | Pass options to the sandbox. The value must be a JSON object; anything else stops the launch before it starts. The sandbox checks the keys. | + +## Arguments for the agent + +Everything after `` goes to the agent unchanged. +A single leading `--` is removed: + +```bash +flox agent launch claude -- --continue +``` + +## Global options + +Global options go before `launch`: `flox agent --config-dir ./cfg launch claude`. + +| Option | Default | Effect | +| ------ | ------- | ------ | +| `--dir ` | `$FLOX_ENV/share` | Read plugins from `/agent-plugins` | +| `--config-dir ` | `$FLOX_ENV_PROJECT/.flox/cache/agent-stacks` | Where launches are staged | + +## Sandboxes + +With `--sandbox`, launch builds the agent's command and environment exactly as it does without one, then runs: + +```text +agent-sandbox- [--options ''] -- [args] +``` + +The sandbox validates its options, sets itself up, and runs the agent. +Its error messages and exit status reach you unchanged. + +| Sandbox | Package | Options | +| ------- | ------- | ------- | +| `srt` | `agent-stacks/agent-sandbox-srt` | `allowedDomains`, `allowWrite`, `denyRead` | +| `nono` | `agent-stacks/agent-sandbox-nono` | `allowedDomains`, `allowWrite`, `denyRead` | + +See [Launch an agent in a sandbox](/ai-agents/guides/launch-in-a-sandbox) for what each sandbox allows. + +## Examples + +```bash +flox agent launch claude +``` + +```bash +flox agent launch codex +``` + +```bash +flox agent launch --sandbox srt --sandbox-options '{"allowedDomains": ["github.com"]}' claude +``` + +## Requirements + +Claude Code 2.1.280 or later. +The `agent-stacks/claude-code` package meets this. +Codex must be the `agent-stacks/codex` build, which accepts skills from Flox; another build launches without them, and `flox agent doctor` reports it as degraded. + +## See also + +- [`flox agent list`](/ai-agents/reference/flox-agent-list) +- [Launch an agent in a sandbox](/ai-agents/guides/launch-in-a-sandbox) diff --git a/ai-agents/reference/flox-agent-list.mdx b/ai-agents/reference/flox-agent-list.mdx new file mode 100644 index 0000000..0b2ecde --- /dev/null +++ b/ai-agents/reference/flox-agent-list.mdx @@ -0,0 +1,63 @@ +--- +title: "flox agent list" +description: "Show the harnesses and agent plugins an environment gives its AI agent." +--- + +## Synopsis + +```text +flox agent list [--long | --longer] +``` + +## Description + +Prints what the environment gives its agent: the harnesses installed and the agent plugins they receive, each with the package and version it came from. +`flox agent list` changes nothing and never runs a build. + +It reads the same plugin folder `flox agent launch` reads, `$FLOX_ENV/share/agent-plugins/`, and looks for harnesses in the environment's `bin` folder. + +Each harness row says what launch hands it. +Claude Code receives whole plugins (`skills, MCP, hooks`). +Codex, opencode, and pi receive `skills only`. +A harness that would fail launch's own check shows `⚠` and the reason instead of `✔`. +Agent Deck is not listed, because the Claude Code sessions it starts get their plugins through `flox agent launch claude`. + +An environment with no harness or no plugins is not an error. +`flox agent list` says what is missing and exits with status 0. + +## Options + +| Option | Effect | +| ------ | ------ | +| `--long` | Also list each plugin's skills and MCP servers | +| `--longer` | Also list every part, with its approximate size in tokens and its store path | + +## Global options + +| Option | Effect | +| ------ | ------ | +| `--dir ` | Read plugins from `/agent-plugins` instead of `$FLOX_ENV/share/agent-plugins` | + +Global options go before the command name: `flox agent --dir ./share list`. + +## Example + +```console +$ flox agent list --long +Agent stack +1 harness · 1 plugin · 1 skill · 0 MCP servers + +Harnesses + ✔ claude claude-code 2.1.304 · skills, MCP, hooks + +Plugins + ✔ frontend-design agent-plugin-frontend-design 0.0.0-unstable.2026-10-19.ga0b04d9 + skills frontend-design + +Shows what launch gives each harness; agent-stacks writes nothing to a harness's own config. +``` + +## See also + +- [`flox agent launch`](/ai-agents/reference/flox-agent-launch) +- [AI agent quickstart](/ai-agents/quickstart) diff --git a/styles/config/vocabularies/Flox/accept.txt b/styles/config/vocabularies/Flox/accept.txt index dcf4c4c..1d07003 100644 --- a/styles/config/vocabularies/Flox/accept.txt +++ b/styles/config/vocabularies/Flox/accept.txt @@ -22,6 +22,15 @@ sourceRoot substituters vendorHash +# === AI agents === +Anthropic +bubblewrap +frontmatter +Landlock +opencode +seccomp +SkillSpector + # === Other technical vocabulary === allowlist auditable From fb53c70abf6e70675eea60fe9116f23da7d9d62a Mon Sep 17 00:00:00 2001 From: alator-fd Date: Wed, 21 Oct 2026 11:39:22 -0400 Subject: [PATCH 2/8] docs(nav): add an AI agents tab beside the CLI reference Option B for placing the AI agent pages: a fourth top-level tab, before Changelog, grouped as Get started, Guides and Command reference. llms.txt regenerated from the new navigation. --- docs.json | 30 ++++++++++++++++++++++++++++++ llms.txt | 19 +++++++++++++++++++ 2 files changed, 49 insertions(+) diff --git a/docs.json b/docs.json index 972ba13..fa702ba 100644 --- a/docs.json +++ b/docs.json @@ -251,6 +251,36 @@ } ] }, + { + "tab": "AI agents", + "groups": [ + { + "group": "Get started", + "pages": [ + "ai-agents/overview", + "ai-agents/quickstart" + ] + }, + { + "group": "Guides", + "pages": [ + "ai-agents/guides/package-a-skill-repository", + "ai-agents/guides/audit-a-plugin", + "ai-agents/guides/launch-in-a-sandbox" + ] + }, + { + "group": "Command reference", + "pages": [ + "ai-agents/reference/flox-agent-list", + "ai-agents/reference/flox-agent-launch", + "ai-agents/reference/flox-agent-import", + "ai-agents/reference/flox-agent-audit", + "ai-agents/reference/flox-agent-check-plugin" + ] + } + ] + }, { "tab": "Changelog", "pages": [ diff --git a/llms.txt b/llms.txt index 619ab27..1b7a367 100644 --- a/llms.txt +++ b/llms.txt @@ -228,6 +228,25 @@ Key terms: - [flox gc](https://flox.dev/docs/man/flox-gc.md): Garbage collection. - [flox include upgrade](https://flox.dev/docs/man/flox-include-upgrade.md): Upgrade an environment with latest changes to its included environments. +## AI agents: Get started + +- [AI coding agents](https://flox.dev/docs/ai-agents/overview.md): Put an AI coding agent, its plugins, and a sandbox in a Flox environment, and launch the agent with exactly that set. +- [AI agent quickstart](https://flox.dev/docs/ai-agents/quickstart.md): Install Claude Code and an agent plugin into a Flox environment, then launch the agent with that plugin. + +## AI agents: Guides + +- [Package a skill repository](https://flox.dev/docs/ai-agents/guides/package-a-skill-repository.md): Turn a GitHub repository of agent skills into a pinned agent plugin package and install it into a Flox environment. +- [Audit an agent plugin](https://flox.dev/docs/ai-agents/guides/audit-a-plugin.md): Scan an agent plugin for security issues with SkillSpector before or after you install it. +- [Launch an agent in a sandbox](https://flox.dev/docs/ai-agents/guides/launch-in-a-sandbox.md): Run an AI coding agent inside a sandbox package that limits the files and hosts it can reach. + +## AI agents: Command reference + +- [flox agent list](https://flox.dev/docs/ai-agents/reference/flox-agent-list.md): Show the harnesses and agent plugins an environment gives its AI agent. +- [flox agent launch](https://flox.dev/docs/ai-agents/reference/flox-agent-launch.md): Run an AI coding agent with the environment's agent plugins, optionally inside a sandbox. +- [flox agent import](https://flox.dev/docs/ai-agents/reference/flox-agent-import.md): Generate a pinned agent plugin package from a GitHub repository of skills. +- [flox agent audit](https://flox.dev/docs/ai-agents/reference/flox-agent-audit.md): Security-audit an agent plugin, by path or by catalog package, with NVIDIA SkillSpector. +- [flox agent check-plugin](https://flox.dev/docs/ai-agents/reference/flox-agent-check-plugin.md): Validate an agent plugin folder against the Agent Plugins and Agent Skills specifications. + ## Changelog - [2026](https://flox.dev/docs/changelog.md): What's new across the Flox CLI, FloxHub, and extensions From 18ff45e078529c8b9341de10840a4eb684bb412e Mon Sep 17 00:00:00 2001 From: alator-fd Date: Tue, 27 Oct 2026 09:53:23 -0400 Subject: [PATCH 3/8] docs(ai-agents): lead with the quickstart and explain each step From Daniel's review: the quickstart opens the AI agents tab and says what each command does and why, SkillSpector links to its project, and the audit guide just says to pass a file path. --- ai-agents/guides/audit-a-plugin.mdx | 5 ++--- ai-agents/quickstart.mdx | 12 +++++++++--- ai-agents/reference/flox-agent-audit.mdx | 2 +- docs.json | 4 ++-- llms.txt | 2 +- 5 files changed, 15 insertions(+), 10 deletions(-) diff --git a/ai-agents/guides/audit-a-plugin.mdx b/ai-agents/guides/audit-a-plugin.mdx index c622814..b1c82c7 100644 --- a/ai-agents/guides/audit-a-plugin.mdx +++ b/ai-agents/guides/audit-a-plugin.mdx @@ -6,7 +6,7 @@ description: "Scan an agent plugin for security issues with SkillSpector before A plugin's skills are instructions your agent follows. Before you install one, you can scan it for prompt injection, credential access, and other risky patterns. -`flox agent audit` runs NVIDIA SkillSpector over each skill and scores the plugin from 0 to 100, where higher is better. +`flox agent audit` runs NVIDIA [SkillSpector](https://github.com/nvidia/skillspector) over each skill and scores the plugin from 0 to 100, where higher is better. ## Install the scanner @@ -44,8 +44,7 @@ Add `@` to audit a specific version, for example `agent-stacks/agent-pl ## Audit what is already installed -Pass a path instead of a package name. -A path starts with `./`, `../`, `/`, or `~/`. +Pass a file path instead of a package name. To audit one installed plugin: ```bash diff --git a/ai-agents/quickstart.mdx b/ai-agents/quickstart.mdx index 456b2db..7f828a5 100644 --- a/ai-agents/quickstart.mdx +++ b/ai-agents/quickstart.mdx @@ -6,10 +6,11 @@ description: "Install Claude Code and an agent plugin into a Flox environment, t In this guide you create an environment holding Claude Code and the `frontend-design` plugin, check what the agent will get, and launch it. You need [Flox installed](/install-flox/install) and a Claude account. +For the ideas behind it (harnesses, plugins and sandboxes), see [AI coding agents](/ai-agents/overview). ## Enable the extension -`flox agent` is a beta Flox extension. +`flox agent` is a beta Flox extension, and Flox only runs beta commands once you opt in. Turn on beta features once: ```bash @@ -18,6 +19,8 @@ flox config --set features.beta true ## Create the environment +The environment holds everything the agent gets. +Whatever you install into it is pinned in its lockfile, so anyone who activates the same environment gets the same agent and plugins. Make a folder for your project and create an environment in it: ```bash @@ -36,13 +39,14 @@ flox install agent-stacks/claude-code agent-stacks/agent-plugin-frontend-design ## See what the agent gets -Activate the environment: +Activating the environment puts its packages, including `flox agent`, on your `PATH`: ```bash flox activate ``` -Then list the stack: +Then list the stack. +`flox agent list` reads what is installed and shows what a launch would hand each harness, without starting anything: ```console $ flox agent list @@ -68,6 +72,8 @@ Run `flox agent list --long` to see the skills each plugin provides. flox agent launch claude ``` +`flox agent launch` starts Claude Code with the environment's plugins. +It stages them inside the environment, so your own Claude Code settings in your home directory are left as they are. Claude Code starts with the `frontend-design` skill loaded. Ask it to build a page, and it uses the skill. diff --git a/ai-agents/reference/flox-agent-audit.mdx b/ai-agents/reference/flox-agent-audit.mdx index a340a05..c89c4f2 100644 --- a/ai-agents/reference/flox-agent-audit.mdx +++ b/ai-agents/reference/flox-agent-audit.mdx @@ -11,7 +11,7 @@ flox agent audit [--json] [--threshold N] [--raw] [--scan-timeout D] ## Description -Finds the plugin `` names, validates it, lists what it will and will not look at, scans each skill with SkillSpector, and scores the plugin from 0 to 100 by its worst skill. +Finds the plugin `` names, validates it, lists what it will and will not look at, scans each skill with [SkillSpector](https://github.com/nvidia/skillspector), and scores the plugin from 0 to 100 by its worst skill. Higher is better. `audit` measures security only. diff --git a/docs.json b/docs.json index fa702ba..b369a5f 100644 --- a/docs.json +++ b/docs.json @@ -257,8 +257,8 @@ { "group": "Get started", "pages": [ - "ai-agents/overview", - "ai-agents/quickstart" + "ai-agents/quickstart", + "ai-agents/overview" ] }, { diff --git a/llms.txt b/llms.txt index 1b7a367..15f7f07 100644 --- a/llms.txt +++ b/llms.txt @@ -230,8 +230,8 @@ Key terms: ## AI agents: Get started -- [AI coding agents](https://flox.dev/docs/ai-agents/overview.md): Put an AI coding agent, its plugins, and a sandbox in a Flox environment, and launch the agent with exactly that set. - [AI agent quickstart](https://flox.dev/docs/ai-agents/quickstart.md): Install Claude Code and an agent plugin into a Flox environment, then launch the agent with that plugin. +- [AI coding agents](https://flox.dev/docs/ai-agents/overview.md): Put an AI coding agent, its plugins, and a sandbox in a Flox environment, and launch the agent with exactly that set. ## AI agents: Guides From 214c347e80217df93bbd6099a6cd44bab2538818 Mon Sep 17 00:00:00 2001 From: alator-fd Date: Tue, 27 Oct 2026 09:55:45 -0400 Subject: [PATCH 4/8] docs(ai-agents): get nix from the catalog in the packaging guide From Daniel's review: the only prerequisite is Flox. The guide installs nix into the environment and passes the experimental-features flag the catalog's nix needs for a flake build. Tested with nix 2.34.9 from the catalog and no user Nix config: import, build and check-plugin all pass. --- ai-agents/guides/package-a-skill-repository.mdx | 16 +++++++++++----- 1 file changed, 11 insertions(+), 5 deletions(-) diff --git a/ai-agents/guides/package-a-skill-repository.mdx b/ai-agents/guides/package-a-skill-repository.mdx index 8825a1b..76eb20f 100644 --- a/ai-agents/guides/package-a-skill-repository.mdx +++ b/ai-agents/guides/package-a-skill-repository.mdx @@ -13,15 +13,19 @@ The steps below build in a checkout of that repository, which provides the build ## Prerequisites -- An environment with `flox/flox-agent` installed, as in the [quickstart](/ai-agents/quickstart). -- Nix, to build the package. +- An environment with `flox/flox-agent` installed, as in the [quickstart](/ai-agents/quickstart), plus `nix` from the catalog to build the package: + +```bash +flox install nix +``` + - A clone of agent-pkgs: ```bash git clone https://github.com/agent-stacks/agent-pkgs.git && cd agent-pkgs ``` -Run the commands below in a shell where your environment is active, so `flox agent` is available. +Run the commands below in a shell where your environment is active, so `flox agent` and `nix` are available. ## Import the repository @@ -64,10 +68,12 @@ See the [`flox agent import`](/ai-agents/reference/flox-agent-import) reference ## Build and check the package -The build fetches only tracked files, so add the new folder to git first: +The build fetches only tracked files, so add the new folder to git first. +The flag turns on the Nix features a flake build needs: ```bash -git add pkgs/agent-plugin-caveman && nix build .#agent-plugin-caveman +git add pkgs/agent-plugin-caveman +nix --extra-experimental-features 'nix-command flakes' build .#agent-plugin-caveman ``` Check the built plugin against the Agent Plugins specification: From 533294564372900cabc7a5a9b34a2dfea2144f15 Mon Sep 17 00:00:00 2001 From: alator-fd Date: Mon, 9 Nov 2026 14:46:35 -0500 Subject: [PATCH 5/8] docs(ai-agents): build imported packages with flox build, and use --pkgs-dir Import now writes everything a package needs to build into the environment, so the packaging guide no longer goes through an agent-pkgs checkout. --out was removed in favour of --pkgs-dir, and the call file is default.json. --- .../guides/package-a-skill-repository.mdx | 73 ++++++++++--------- ai-agents/reference/flox-agent-import.mdx | 45 ++++++++---- 2 files changed, 67 insertions(+), 51 deletions(-) diff --git a/ai-agents/guides/package-a-skill-repository.mdx b/ai-agents/guides/package-a-skill-repository.mdx index 76eb20f..bd481c1 100644 --- a/ai-agents/guides/package-a-skill-repository.mdx +++ b/ai-agents/guides/package-a-skill-repository.mdx @@ -1,53 +1,46 @@ --- title: "Package a skill repository" sidebarTitle: "Package a skill repository" -description: "Turn a GitHub repository of agent skills into a pinned agent plugin package and install it into a Flox environment." +description: "Turn a GitHub repository of agent skills into a pinned agent plugin package, build it with Flox, and install it into an environment." --- Many skill collections live in GitHub repositories rather than in the catalog. -`flox agent import` reads such a repository, finds its plugins and skills, and writes a package definition pinned to one commit. -This guide imports a repository, builds the package, checks it, and installs it into an environment. - -The agent plugin packages in the `agent-stacks` catalog are generated this way, in the [agent-pkgs](https://github.com/agent-stacks/agent-pkgs) repository. -The steps below build in a checkout of that repository, which provides the builder the generated package needs. +`flox agent import` reads such a repository, finds its plugins and skills, and writes a package pinned to one commit into your environment. +This guide imports a repository, builds the package with `flox build`, checks it, and installs it. ## Prerequisites -- An environment with `flox/flox-agent` installed, as in the [quickstart](/ai-agents/quickstart), plus `nix` from the catalog to build the package: - -```bash -flox install nix -``` - -- A clone of agent-pkgs: +- An environment with `flox/flox-agent` installed, as in the [quickstart](/ai-agents/quickstart). +- The environment's folder is a git repository, because `flox build` reads only files git tracks: ```bash -git clone https://github.com/agent-stacks/agent-pkgs.git && cd agent-pkgs +git init ``` -Run the commands below in a shell where your environment is active, so `flox agent` and `nix` are available. +Run the commands below in a shell where your environment is active, so `flox agent` is available. ## Import the repository -Pass the repository as `owner/repo`, a GitHub URL, or a local clone whose `origin` is on GitHub. -Write the package into the `pkgs` folder: +Pass the repository as `owner/repo`, a GitHub URL, or a local clone whose `origin` is on GitHub: ```bash -flox agent import juliusbrussee/caveman --out pkgs +flox agent import juliusbrussee/caveman ``` Import pins the current commit, finds every plugin in the repository, and validates each one. It prints a warning for anything it packages with a deviation and for anything it leaves out, then a summary per plugin: ```console -caveman: new plugin at bad48a0e1df5 (22 skills) - written to pkgs/agent-plugin-caveman +caveman: new plugin at 3dc497a7f858 (22 skills) + written to .flox/pkgs/agent-plugin-caveman ``` -Each plugin becomes a folder holding two files: +Each plugin becomes a folder under `.flox/pkgs` holding two files: + +- `default.json` records the pinned source, the skills, and the import that produced them, including its warnings. +- `default.nix` reads `default.json` and is the same in every package. -- `source.json` records the pinned source, the skills, and the import that produced them, including its warnings. -- `default.nix` reads `source.json` and is the same in every package. +Import also writes what the packages need to build: the builder in `.flox/agent-lib/` and the `flox-agent` that ran the import in `.flox/pkgs/flox-agent/`. Import only reads from GitHub. Repositories hosted elsewhere are rejected. @@ -55,7 +48,7 @@ Repositories hosted elsewhere are rejected. ### Choose what gets imported Most repositories need no flags. -When discovery finds the wrong thing, these flags adjust it, and import records them in `source.json` so a later re-import repeats them: +When discovery finds the wrong thing, these flags adjust it, and import records them in `default.json` so a later re-import repeats them: | Flag | Use it to | | ---- | --------- | @@ -68,37 +61,45 @@ See the [`flox agent import`](/ai-agents/reference/flox-agent-import) reference ## Build and check the package -The build fetches only tracked files, so add the new folder to git first. -The flag turns on the Nix features a flake build needs: +Track the new files, then build the plugin: ```bash -git add pkgs/agent-plugin-caveman -nix --extra-experimental-features 'nix-command flakes' build .#agent-plugin-caveman +git add .flox +flox build agent-plugin-caveman +``` + +The build checks the plugin as it assembles it and ends with: + +```console +⚡︎ Built output: ./result-agent-plugin-caveman ``` Check the built plugin against the Agent Plugins specification: ```bash -flox agent check-plugin result/share/agent-plugins/caveman +flox agent check-plugin result-agent-plugin-caveman/share/agent-plugins/caveman ``` Scan it for security issues: ```bash -flox agent audit ./result +flox agent audit ./result-agent-plugin-caveman ``` See [Audit an agent plugin](/ai-agents/guides/audit-a-plugin) for how to read the score. ## Install it into your environment -From your project's environment, install the package from the agent-pkgs checkout: +Publish the package to your catalog, then install it from there: ```bash -flox install "git+file://$HOME/agent-pkgs#agent-plugin-caveman" +flox publish agent-plugin-caveman +flox install /agent-plugin-caveman ``` -Replace `$HOME/agent-pkgs` with the path to your clone. +`flox publish` needs the repository pushed to a remote, with the commit you publish on its branch. +See [`flox publish`](/man/flox-publish) for what it checks. + `flox agent list` now shows the plugin, and the next `flox agent launch` loads it. ## Update the package @@ -107,12 +108,14 @@ Run the same import again to move to the repository's latest commit. To repeat the flags recorded the first time, use `--replay`: ```bash -flox agent import juliusbrussee/caveman --out pkgs --replay +flox agent import juliusbrussee/caveman --replay ``` The summary says `unchanged`, `regenerated`, or the old and new commit, with the skills added and removed. +Build and publish again to ship the new version. -To have the plugin published in the `agent-stacks` catalog, open a pull request to agent-pkgs with the generated folder. +The agent plugin packages in the `agent-stacks` catalog are made the same way, in the [agent-pkgs](https://github.com/agent-stacks/agent-pkgs) repository. +To have a plugin published there, open a pull request to agent-pkgs with the generated folder. Packages there are re-imported automatically when their upstream moves. ## Related diff --git a/ai-agents/reference/flox-agent-import.mdx b/ai-agents/reference/flox-agent-import.mdx index 9c54cc8..d253479 100644 --- a/ai-agents/reference/flox-agent-import.mdx +++ b/ai-agents/reference/flox-agent-import.mdx @@ -6,10 +6,10 @@ description: "Generate a pinned agent plugin package from a GitHub repository of ## Synopsis ```text -flox agent import [--out ] [--plugin ]... - [--path-ignore ]... [--dependency ]... - [--no-auto-discovery] -flox agent import [--out ] --replay +flox agent import [--pkgs-dir ] [--lib-dir ] [--yes] + [--plugin ]... [--path-ignore ]... + [--dependency ]... [--no-auto-discovery] +flox agent import [--pkgs-dir ] [--yes] --replay ``` ## Description @@ -26,14 +26,16 @@ Import: 2. Finds every plugin and its skills. 3. Computes the hash of the source the build will fetch. 4. Validates each plugin with the [`check-plugin`](/ai-agents/reference/flox-agent-check-plugin) rules. A plugin with errors is not written; the others are. -5. Writes `agent-plugin-/source.json` and `agent-plugin-/default.nix` under the output folder, and prints a summary. +5. Writes `agent-plugin-/default.json` and `agent-plugin-/default.nix` under the packages folder, and prints a summary. +6. Writes what the packages need to build beside them: the builder in the lib folder, and the `flox-agent` that ran the import as its own package. The summary is `new plugin` on a first import. On a re-import it is `unchanged at `, `regenerated at `, or ` -> ` with the skills added and removed. There is no separate update command; re-importing is how a package moves to a newer commit. -`source.json` records the source, the skills, the flags given, and every warning. +`default.json` records the source, the skills, the flags given, and every warning. `default.nix` is the same in every package, apart from a block between its `BEGIN custom` and `END custom` markers that a re-import keeps. +A package written before `default.json` holds `source.json` instead; import still reads it, and moves it to `default.json` on its next write. ## Finding plugins @@ -52,18 +54,23 @@ Within each plugin, import searches for `SKILL.md` files and records anything it | Option | Repeatable | Effect | | ------ | ---------- | ------ | -| `--out ` | No | Where to write packages. Default `.flox/pkgs/` | +| `--pkgs-dir ` | No | Where to write packages. Default `.flox/pkgs/` | +| `--lib-dir ` | No | Where to write the builder, inside the same root. Default `.flox/agent-lib/` in a Flox environment, else `lib/` beside the packages folder | +| `--yes` | No | Create the Flox environment or `flake.nix` the packages folder needs, without asking | | `--plugin ` | Yes | Treat `` as a plugin, named `` or after its folder | | `--path-ignore ` | Yes | Never read or package anything matching `` | | `--dependency ` | Yes | A Nixpkgs package the build may link a script's interpreter from, such as `R` for `Rscript` | | `--no-auto-discovery` | No | Import only the `--plugin` folders | | `--replay` | No | Repeat the flags recorded in the existing packages for this repository | -Every option except `--out` and `--replay` is recorded in `source.json`. -`--replay` can be combined only with `--out`. +Every option except `--yes` and `--replay` is recorded in `default.json`. +`--pkgs-dir` and `--lib-dir` are recorded only when given, relative to the root. +`--replay` can be combined only with `--pkgs-dir` and `--yes`. -A default output under `.flox` needs that `.flox` to be a Flox environment. -Run `flox init` first, or pass `--out` with a folder outside `.flox`. +A packages folder under `.flox` needs that `.flox` to be a Flox environment, and one anywhere else needs a `flake.nix` beside it. +When it is missing, import offers to create it; `--yes` creates it without asking, and a run without a terminal fails instead. + +`--out` was removed. Passing it is a usage error that names `--pkgs-dir` instead. A package folder belongs to the repository that wrote it. Import refuses to overwrite a package recorded from a different repository. @@ -74,26 +81,32 @@ Import refuses to overwrite a package recorded from a different repository. | ------ | ------- | | `0` | Every plugin was imported | | `1` | A plugin failed, or the clone or a write failed; the other plugins are still written | -| `2` | Usage error, including `--replay` with a flag other than `--out` | +| `2` | Usage error, including `--out` and `--replay` with a flag other than `--pkgs-dir` or `--yes` | ## Examples -Import a repository into an agent-pkgs checkout: +Import a repository into the current environment: ```bash -flox agent import juliusbrussee/caveman --out pkgs +flox agent import juliusbrussee/caveman ``` Import a folder of skills that discovery misses, under a chosen name: ```bash -flox agent import owner/repo --out pkgs --plugin skills=my-skills +flox agent import owner/repo --plugin skills=my-skills ``` Update a package, repeating the flags it was first imported with: ```bash -flox agent import juliusbrussee/caveman --out pkgs --replay +flox agent import juliusbrussee/caveman --replay +``` + +Import into an agent-pkgs checkout: + +```bash +flox agent import juliusbrussee/caveman --pkgs-dir pkgs ``` ## See also From 62bfc67bac490fa8ba0f24a5b27b983faed05dec Mon Sep 17 00:00:00 2001 From: alator-fd Date: Mon, 9 Nov 2026 15:02:55 -0500 Subject: [PATCH 6/8] docs(llms): regenerate for the packaging guide's new description --- llms.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/llms.txt b/llms.txt index 15f7f07..f15e05a 100644 --- a/llms.txt +++ b/llms.txt @@ -235,7 +235,7 @@ Key terms: ## AI agents: Guides -- [Package a skill repository](https://flox.dev/docs/ai-agents/guides/package-a-skill-repository.md): Turn a GitHub repository of agent skills into a pinned agent plugin package and install it into a Flox environment. +- [Package a skill repository](https://flox.dev/docs/ai-agents/guides/package-a-skill-repository.md): Turn a GitHub repository of agent skills into a pinned agent plugin package, build it with Flox, and install it into an environment. - [Audit an agent plugin](https://flox.dev/docs/ai-agents/guides/audit-a-plugin.md): Scan an agent plugin for security issues with SkillSpector before or after you install it. - [Launch an agent in a sandbox](https://flox.dev/docs/ai-agents/guides/launch-in-a-sandbox.md): Run an AI coding agent inside a sandbox package that limits the files and hosts it can reach. From 5be74c0b775da0cf61bd81e962fa6f802aaaf085 Mon Sep 17 00:00:00 2001 From: alator-fd Date: Mon, 9 Nov 2026 15:41:42 -0500 Subject: [PATCH 7/8] docs(ai-agents): log in to FloxHub before installing Installing from the Flox Catalog needs a FloxHub login since 20 Oct, and the quickstart's first flox install failed without one. --- ai-agents/guides/package-a-skill-repository.mdx | 1 + ai-agents/quickstart.mdx | 11 +++++++++-- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/ai-agents/guides/package-a-skill-repository.mdx b/ai-agents/guides/package-a-skill-repository.mdx index bd481c1..a49d6db 100644 --- a/ai-agents/guides/package-a-skill-repository.mdx +++ b/ai-agents/guides/package-a-skill-repository.mdx @@ -11,6 +11,7 @@ This guide imports a repository, builds the package with `flox build`, checks it ## Prerequisites - An environment with `flox/flox-agent` installed, as in the [quickstart](/ai-agents/quickstart). +- Logged in to FloxHub with `flox auth login`, which installing and publishing need. - The environment's folder is a git repository, because `flox build` reads only files git tracks: ```bash diff --git a/ai-agents/quickstart.mdx b/ai-agents/quickstart.mdx index 7f828a5..c942871 100644 --- a/ai-agents/quickstart.mdx +++ b/ai-agents/quickstart.mdx @@ -5,10 +5,17 @@ description: "Install Claude Code and an agent plugin into a Flox environment, t --- In this guide you create an environment holding Claude Code and the `frontend-design` plugin, check what the agent will get, and launch it. -You need [Flox installed](/install-flox/install) and a Claude account. +You need [Flox installed](/install-flox/install), a free FloxHub account, and a Claude account. For the ideas behind it (harnesses, plugins and sandboxes), see [AI coding agents](/ai-agents/overview). -## Enable the extension +## Log in and enable the extension + +Installing packages from the Flox Catalog needs you to be logged in to FloxHub. +Log in once per machine: + +```bash +flox auth login +``` `flox agent` is a beta Flox extension, and Flox only runs beta commands once you opt in. Turn on beta features once: From 108e1750bb5d6e8a7ac05339bd30ef0870a36267 Mon Sep 17 00:00:00 2001 From: alator-fd Date: Mon, 9 Nov 2026 15:43:52 -0500 Subject: [PATCH 8/8] docs(ai-agents): audit scans more than skills, and srt reads the home folder Since ADR 0087 audit also scans hooks, agents, commands, bin/ and other folders. srt hides only ~/.ssh, so the sandbox guide says so and shows denyRead for credentials such as ~/.aws. --- ai-agents/guides/audit-a-plugin.mdx | 10 +++++----- ai-agents/guides/launch-in-a-sandbox.mdx | 9 +++++++++ ai-agents/reference/flox-agent-audit.mdx | 20 +++++++++++--------- 3 files changed, 25 insertions(+), 14 deletions(-) diff --git a/ai-agents/guides/audit-a-plugin.mdx b/ai-agents/guides/audit-a-plugin.mdx index b1c82c7..5539c33 100644 --- a/ai-agents/guides/audit-a-plugin.mdx +++ b/ai-agents/guides/audit-a-plugin.mdx @@ -6,7 +6,7 @@ description: "Scan an agent plugin for security issues with SkillSpector before A plugin's skills are instructions your agent follows. Before you install one, you can scan it for prompt injection, credential access, and other risky patterns. -`flox agent audit` runs NVIDIA [SkillSpector](https://github.com/nvidia/skillspector) over each skill and scores the plugin from 0 to 100, where higher is better. +`flox agent audit` runs NVIDIA [SkillSpector](https://github.com/nvidia/skillspector) over each skill and the rest of what the plugin carries, and scores it from 0 to 100, where higher is better. ## Install the scanner @@ -61,7 +61,7 @@ A bare word is always read as a package, so `flox agent audit frontend-design` l ## Read the result -Each skill gets its own score, and the plugin scores its worst skill. +Each skill and component gets its own score, and the plugin scores its worst. The bands are SkillSpector's: | Score | Status | @@ -75,8 +75,8 @@ HIGH and CRITICAL findings move the score most. For a `caution` score, read each finding and decide whether the skill's text justifies it. The audit also says what it did **not** check. -It scans skills only. -MCP server configuration, hooks, `bin/`, and files outside the plugin layout are listed under "Not checked", and the score says nothing about them. +It scans the plugin's skills, its hooks, agents and commands, a `bin/` with programs of its own, and other folders such as `scripts/` and `src/`. +MCP server configuration and files outside the plugin layout, such as `README.md`, are listed under "Not checked", and the score says nothing about them. Nothing is executed, and no language model reads the plugin. ## Gate on a score in CI @@ -88,7 +88,7 @@ flox agent audit "$FLOX_ENV" --threshold 80 ``` A threshold of 80 fails on anything that is not `safe`. -On a slow runner, give each skill's scan more time with `--scan-timeout`, for example `--scan-timeout 15m`. +On a slow runner, give each scan more time with `--scan-timeout`, for example `--scan-timeout 15m`. ## Related diff --git a/ai-agents/guides/launch-in-a-sandbox.mdx b/ai-agents/guides/launch-in-a-sandbox.mdx index 06300b1..8eee201 100644 --- a/ai-agents/guides/launch-in-a-sandbox.mdx +++ b/ai-agents/guides/launch-in-a-sandbox.mdx @@ -55,6 +55,15 @@ Both sandboxes start from these defaults: With `srt`, no other host is reachable. With `nono`, the network stays open until you pass `allowedDomains`. +The two also differ in what the agent can read. +`nono`'s default profile hides `~/.ssh` and other credential folders. +`srt` hides only `~/.ssh`: the agent can read the rest of your home folder, including credentials such as `~/.aws`. +With `srt`, hide them with `denyRead`: + +```bash +flox agent launch --sandbox srt --sandbox-options '{"denyRead": ["~/.aws", "~/.config/gcloud", "~/.kube"]}' claude +``` + ## Pass options to the sandbox Pass options as one JSON object with `--sandbox-options`. diff --git a/ai-agents/reference/flox-agent-audit.mdx b/ai-agents/reference/flox-agent-audit.mdx index c89c4f2..9b50f2b 100644 --- a/ai-agents/reference/flox-agent-audit.mdx +++ b/ai-agents/reference/flox-agent-audit.mdx @@ -11,7 +11,7 @@ flox agent audit [--json] [--threshold N] [--raw] [--scan-timeout D] ## Description -Finds the plugin `` names, validates it, lists what it will and will not look at, scans each skill with [SkillSpector](https://github.com/nvidia/skillspector), and scores the plugin from 0 to 100 by its worst skill. +Finds the plugin `` names, validates it, lists what it will and will not look at, scans each component with [SkillSpector](https://github.com/nvidia/skillspector), and scores the plugin from 0 to 100 by its worst component. Higher is better. `audit` measures security only. @@ -43,27 +43,29 @@ Options can go on either side of ``. | ------ | ------ | | `--json` | Print the result as JSON instead of the summary | | `--threshold N` | Exit with status 1 when the score is below `N` | -| `--raw` | Include SkillSpector's own report for each skill | -| `--scan-timeout D` | Stop a skill's scan after `D`, such as `90s` or `15m` (default `5m`) | +| `--raw` | Include SkillSpector's own report for each component | +| `--scan-timeout D` | Stop a component's scan after `D`, such as `90s` or `15m` (default `5m`) | ## What is checked | Entry | Treatment | | ----- | --------- | -| Each `skills/` with a `SKILL.md` | Scanned | +| Each `skills/` with a `SKILL.md` | Scanned, one scan per skill | | `plugin.json` | Validated only | | `mcp.json` | Not checked | -| `bin/` | Not checked | -| Client folders such as `com.anthropic.claude-code/`, which hold hooks, agents, and commands | Not checked | -| Anything else | Not checked | +| `bin/` with programs of its own | Scanned | +| `bin/` holding only links to interpreters | Not checked | +| Each entry of a client folder such as `com.anthropic.claude-code/`, which holds hooks, agents, and commands | Scanned, one scan per entry | +| Any other folder, such as `scripts/` or `src/` | Scanned | +| Anything else, such as `README.md` or `.github/` | Not checked | The summary lists every entry under one of these headings. The score says nothing about the entries that were not checked. ## Score -Each skill scores `100 - risk`, using SkillSpector's risk model. -The plugin scores its worst skill, and several plugins score their worst plugin. +Each scanned component scores `100 - risk`, using SkillSpector's risk model. +The plugin scores its worst component, and several plugins score their worst plugin. | Score | Status | | ----- | ------ |