docs: add an AI agents tab for flox agent

ai-agents/guides/audit-a-plugin.mdx

@@ -0,0 +1,96 @@
+---
+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](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
+
+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 `@<version>` to audit a specific version, for example `agent-stacks/agent-plugin-caveman@4.0.1`.
+
+## Audit what is already installed
+
+Pass a file path instead of a package name.
+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 and component gets its own score, and the plugin scores its worst.
+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 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
+
+`--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 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

ai-agents/guides/launch-in-a-sandbox.mdx

@@ -0,0 +1,112 @@
+---
+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`.
+
+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`.
+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)

ai-agents/guides/package-a-skill-repository.mdx

@@ -0,0 +1,125 @@
+---
+title: "Package a skill repository"
+sidebarTitle: "Package a skill repository"
+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 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).
+- 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
+git init
+```
+
+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:
+
+```bash
+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 3dc497a7f858 (22 skills)
+  written to .flox/pkgs/agent-plugin-caveman
+```
+
+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.
+
+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.
+
+### Choose what gets imported
+
+Most repositories need no flags.
+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 |
+| ---- | --------- |
+| `--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
+
+Track the new files, then build the plugin:
+
+```bash
+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-agent-plugin-caveman/share/agent-plugins/caveman
+```
+
+Scan it for security issues:
+
+```bash
+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
+
+Publish the package to your catalog, then install it from there:
+
+```bash
+flox publish agent-plugin-caveman
+flox install <your-handle>/agent-plugin-caveman
+```
+
+`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
+
+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 --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.
+
+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
+
+- [`flox agent import`](/ai-agents/reference/flox-agent-import) reference
+- [`flox agent check-plugin`](/ai-agents/reference/flox-agent-check-plugin) reference