diff --git a/ai-agents/guides/launch-in-a-sandbox.mdx b/ai-agents/guides/launch-in-a-sandbox.mdx index 8eee201..4dba7bc 100644 --- a/ai-agents/guides/launch-in-a-sandbox.mdx +++ b/ai-agents/guides/launch-in-a-sandbox.mdx @@ -8,7 +8,7 @@ Installing a harness and its plugins in an environment decides what the agent br 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). +You need an environment set up as in [Onboard your agent setup by hand](/ai-agents/guides/onboard-your-setup). ## Choose a sandbox diff --git a/ai-agents/guides/onboard-your-setup.mdx b/ai-agents/guides/onboard-your-setup.mdx new file mode 100644 index 0000000..22474f0 --- /dev/null +++ b/ai-agents/guides/onboard-your-setup.mdx @@ -0,0 +1,120 @@ +--- +title: "Onboard your agent setup by hand" +sidebarTitle: "Onboard by hand" +description: "Set up an agent stack yourself: install Claude Code and an agent plugin into a Flox environment, then launch the agent with that plugin." +--- + +In the [quickstart](/ai-agents/quickstart), the agent you already use does the onboarding for you. +This guide does it by hand, one step at a time. +You create an environment holding Claude Code and the `frontend-design` plugin, check what the agent will get, and launch it. +The same steps install any other plugin the catalog has, as [Add or remove plugins](#add-or-remove-plugins) shows. +For the ideas behind it (harnesses, plugins and sandboxes), see [AI coding agents](/ai-agents/overview). +You need [Flox installed](/install-flox/install), a free FloxHub account, and a Claude account. + +## 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: + +```bash +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 +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 + +Activating the environment puts its packages, including `flox agent`, on your `PATH`: + +```bash +flox activate +``` + +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 +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 +``` + +`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. + +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/guides/package-a-skill-repository.mdx b/ai-agents/guides/package-a-skill-repository.mdx index a49d6db..640d705 100644 --- a/ai-agents/guides/package-a-skill-repository.mdx +++ b/ai-agents/guides/package-a-skill-repository.mdx @@ -10,7 +10,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). +- An environment with `flox/flox-agent` installed, as in [Onboard your agent setup by hand](/ai-agents/guides/onboard-your-setup). - 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: diff --git a/ai-agents/overview.mdx b/ai-agents/overview.mdx index 403dc97..0b562bc 100644 --- a/ai-agents/overview.mdx +++ b/ai-agents/overview.mdx @@ -76,6 +76,7 @@ It never sends names, paths, file contents, or arguments. ## Next steps -- [Quickstart](/ai-agents/quickstart): launch Claude Code with a plugin in a few minutes. +- [Quickstart](/ai-agents/quickstart): turn the agent setup you already have into an agent stack, from the agent you already use. +- [Onboard your agent setup by hand](/ai-agents/guides/onboard-your-setup): launch Claude Code with a plugin, setting up the environment yourself. - [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 index c942871..b702148 100644 --- a/ai-agents/quickstart.mdx +++ b/ai-agents/quickstart.mdx @@ -1,117 +1,406 @@ --- 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." +description: "Paste one prompt into the AI agent you already use, and it turns your skills, plugins, and sandbox into an agent stack that starts the same agents on your other computers too." --- -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), a free FloxHub account, and a Claude account. +Your agent already has a setup: skills you installed or wrote, plugins from marketplaces, commands, agents, and perhaps a sandbox. +In this quickstart you onboard that setup into an agent stack: an environment that holds the agents you use, their plugins, and your sandbox, and starts the same agents here and on your other computers. +You start it from the agent you already use, with one prompt. +The agent helps you set up what is missing on the way, Flox and Agent Stacks included, so you need nothing installed first. For the ideas behind it (harnesses, plugins and sandboxes), see [AI coding agents](/ai-agents/overview). +To set up an agent stack yourself, step by step, see [Onboard your agent setup by hand](/ai-agents/guides/onboard-your-setup). -## Log in and enable the extension +## What you need -Installing packages from the Flox Catalog needs you to be logged in to FloxHub. -Log in once per machine: +- A Mac with Apple silicon, or a Linux machine on `x86_64` or `aarch64`. + Intel Macs are not supported, because `flox/flox-agent` is not built for them. +- A free FloxHub account. + The onboarding helps you log in. +- An AI agent that can run shell commands on this machine, such as Claude Code or Codex. -```bash -flox auth login +## Start the onboarding + +Before you paste the prompt, you can read [what onboarding reads](#what-onboarding-reads), [what it writes](#what-onboarding-writes), and [what leaves your machine](#what-leaves-your-machine). +Paste this prompt into your agent: + +```text +Install Flox and Agent Stacks if they are missing, then turn my current agent setup into an agent stack. +Save the flox skill to a new temporary folder with +curl -fsSL -o /SKILL.md https://raw.githubusercontent.com/flox/flox-skills/main/flox-plugin/skills/flox/SKILL.md +then read that file whole with your file tool, not a summary of it. +Follow its "Installing Agent Stacks" section, then the reference it sends you to, from start to finish. ``` -`flox agent` is a beta Flox extension, and Flox only runs beta commands once you opt in. -Turn on beta features once: +The prompt has your agent save Flox's `flox` skill with `curl`, read it, and follow it. +The skill sends the agent to its Agent Stacks reference, which the agent saves and reads the same way, then follows from start to finish. +It names `curl` because a web fetch tool may hand the agent a summary of the page, and the skill has to be read whole. +It has the agent read the saved file, because some agents cut a command's long output short. +[Install Flox](/install-flox/install#install-with-your-ai-agent) gives a prompt for the same skill that installs Flox alone. + +To read the skill before you run it, open [the `flox` skill](https://github.com/flox/flox-skills/blob/main/flox-plugin/skills/flox/SKILL.md) and its [Agent Stacks reference](https://github.com/flox/flox-skills/blob/main/flox-plugin/skills/flox/references/agent-stacks.md). + +The conversation is the same in any agent. +Claude Code shows each question with options to pick from. +Other agents ask in the chat, with numbered options, and wait for your answer. +The agent never answers a question for you. +It asks before each install, before it uploads or pushes anything to FloxHub, and before it changes what `claude`, or another agent's own command, starts. +Your agent may also ask your permission before each command it runs, as it does for any other command. +If your agent runs commands in a sandbox, it asks to run onboarding's commands outside it, because they use the network and write to the Nix store. + +You can also onboard without an agent, in a terminal of your own. +`flox agent init` asks the same questions in the terminal, as numbered choices, and makes the same stack. +Run it with Flox 1.18 or later, logged in to FloxHub, with beta features on, in an environment that has `flox/flox-agent` installed. +For example: ```bash flox config --set features.beta true +mkdir -p ~/flox-agent && flox init -d ~/flox-agent +flox install -d ~/flox-agent flox/flox-agent +flox activate -d ~/flox-agent -- flox agent init ``` -## Create the environment +The `flox/flox-agent` the catalog serves may not have `init` yet. +Then `flox agent init` prints the general usage instead, and the prompt above makes [a simpler stack](#before-flox-agent-has-onboarding). + +## Set up the machine + +Before it reads your setup, the agent makes sure the machine has what onboarding needs. +It checks each step first, skips the ones already done, and asks before it installs anything. + +1. **The system.** + It checks that this is a Mac with Apple silicon, or a Linux machine on `x86_64` or `aarch64`, and stops on any other. +2. **Flox 1.18 or later.** + Installing or upgrading Flox needs `sudo`, which your agent cannot answer, so the agent asks you to run the command in a terminal yourself. + To install Flox, it gives you the [install script](/install-flox/install): + + ```bash + curl -fsSL https://get.flox.dev | sh + ``` + + For an older Flox, it gives the upgrade command for the way you installed it, such as `brew upgrade --cask flox`. +3. **FloxHub.** + If you are logged out, it asks you to run `flox auth login` in a terminal, which opens your browser and waits for you to log in. +4. **Beta features.** + `flox agent` is a beta Flox extension, so the agent asks to turn on beta features with `flox config --set features.beta true`. +5. **`flox-agent`.** + The agent installs `flox/flox-agent`, the newest build the catalog is known to serve, into an environment of its own at `~/.cache/agent-stacks/bootstrap`, named `agent-stacks-bootstrap`. + That environment is for this system only, and stays on this machine. + The agent checks that this `flox-agent` has onboarding: `flox-agent init --help` prints a usage that starts with `Usage: flox-agent init`. + If it does not, the agent makes [a simpler stack](#before-flox-agent-has-onboarding) instead. + +From here on, the agent runs each `flox-agent` command from that environment, one at a time, as `flox activate -d ~/.cache/agent-stacks/bootstrap -m run -- flox-agent `. +`init plan`, `init decide`, and `init apply` make the stack, and `shortcut` and `sync` finish it, as the sections below describe. + +## Before flox-agent has onboarding + +The `init` command is new, and the `flox/flox-agent` the catalog serves may not have it yet. +Then the agent makes a simpler stack itself: a Flox environment holding `flox/flox-agent`, the agents you use, and the catalog's packages of the Claude Code plugins you use. + +- **Your agents.** + The agent runs `claude --version` and `codex --version`, and looks for `opencode` and `pi` with `command -v`, without running them. + The stack brings each of Claude Code, Codex, opencode, and pi it finds, or Claude Code when it finds none. +- **Your plugins.** + The agent asks Claude Code which plugins you have enabled, with `claude plugin list` and `claude plugin marketplace list`. + A plugin goes in the stack when the catalog has a package of the same name made from the same GitHub repository, as [agent-pkgs](https://github.com/agent-stacks/agent-pkgs) records it. + The stack takes the catalog's newest version, which may differ from yours. +- **What stays here.** + Your own skills, plugins the catalog does not have, your MCP servers, and your settings stay where they are. + The stack's agents still load them on this computer, but not on another. + On this computer, Claude Code also loads its own copy of a plugin the stack brings too, until you turn yours off with `/plugin`. +- **What it asks.** + It shows the stack it proposes, then asks whether to create it on all your computers, which pushes it to FloxHub, or on this computer only. + The stack's FloxHub page is public: its name, package names and versions. +- **Where it is kept.** + The environment is `~/.local/share/agent-stacks/environments/my-agent`, or the name you give. +- **How you start it.** + The stack does not change what `claude`, or another agent's own command, starts. + Start it with the commands the agent shows, one for each agent, such as this one for Claude Code: + + ```bash + flox activate -d ~/.local/share/agent-stacks/environments/my-agent -- flox-agent launch claude + ``` + + For another agent, replace `claude` with its command, such as `codex`. + Once the stack is on FloxHub, any computer logged in to FloxHub as you starts it with `flox activate -r /my-agent -- flox-agent launch claude`. + +Once `flox/flox-agent` has onboarding, ask your agent again, or paste the same prompt again, for the full stack described below. + +## Answer the onboarding's questions + +The agent reads your setup and matches each skill and plugin to the catalog, which takes about half a minute. +Then it shows the stack it proposes: + +```text +Stack /my-stack · Claude Code 2.1.312, as you run it now · sandbox srt +Kept in ~/.local/share/agent-stacks/stacks/my-stack + + Same as now caveman (with your edit to caveman-commit), fill + Changes caveman adds the skill caveman-review you did not have + Stays here linear (MCP server) + 2 more from your claude.ai account or your projects' own settings + Not added caveman's package also has hooks (SessionStart) + +Builds 2 packages here, a few minutes the first time. +``` -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: +The first lines name the stack, its main agent, its sandbox, and where it is kept. +The stack brings every agent you use among Claude Code, Codex, opencode, and pi: each one that is installed, that you have run, or whose configuration holds something. +When you use none of them, it brings Claude Code. +Its main agent is the one your shell history shows you start most often. +When the stack brings more than one agent, the agent names them all before it asks. +The stack gets a sandbox only if you already use one. +The rest is grouped by what you will notice: + +- **Same as now** is what the stack carries as you have it. + A skill or plugin that matches a catalog package is installed from the catalog. + One you edited becomes an overlay: the catalog's package with your changes on top, built here. + Your own skills become packages of your own. +- **Changes** is what will differ, such as a catalog version in place of yours, or skills a package adds that you did not have. + Your own commands and agents become packages of your own too, and are then named `/my-commands:` and `my-agents:`. +- **Stays here** is what stays on this machine, outside the stack, and why. + MCP servers and hooks stay, because they carry this machine's settings, credentials, and paths. + So does a skill of yours that holds what looks like a credential. + A package the catalog's security scan says not to install stays too, unless you choose to carry it. +- **Not added** is what a catalog package has that you did not, such as hooks or commands, which the stack leaves out. + +Matching compares content, never names alone. +A skill you copied from a repository matches only if it is the same as some revision of that repository. + +Then the agent asks the onboarding's questions. +For each package the catalog's security scan says not to install, up to three, it asks whether the stack should carry it. +**Leave it out** is the recommended answer. +Last, it asks whether to create the stack: + +| Answer | What it does | +| ------ | ------------ | +| **Create it, on all my computers** | Builds the stack here, then, in the background, uploads your own packages to your FloxHub catalog, which only you can see, and pushes the stack to FloxHub. This is the recommended answer. | +| **Create it on this computer only** | Builds the stack here. Nothing leaves this machine, and you can share it later. | +| **Show every item first** | Lists every item with the reason for its verdict, then asks again. | +| **Not now** | Stops. Only onboarding's cache and its logs have been written. | + +You can also answer in your own words, for example to leave a skill out of the stack, to package your own copy of a skill rather than the catalog's, or to give the stack another name. +The agent turns your answer into a change to the plan, shows the new summary, and asks again. + +## Build the stack + +Once you agree, the agent builds the stack. +The first build takes a few minutes. +It asks how you want to start the stack. +Claude Code asks while the build runs. +An agent that cannot run a command in the background asks just before the build starts. + +| Answer | What it does | +| ------ | ------------ | +| **Make `claude` start it** | Onboarding adds the stack to your default environment, so `claude` starts the stack in every new terminal, and in tools that run `claude`, such as Agent Deck. For a default environment on FloxHub and a stack you keep on this computer, that waits until you share the stack. This is the recommended answer. | +| **Make `claude` start it, on all my computers** | The same, and onboarding pushes the change it makes to your default environment to FloxHub, so `flox pull -D` brings it to your other computers. Offered in place of the first answer when your default environment is on FloxHub and the stack is going to all your computers. | +| **Make `claude` start it on this computer only** | Offered in the same case: the same, but only this computer's copy of your default environment changes. | +| **Start it myself** | Nothing in your shell changes. You start the stack with the commands shown at the end. | + +The answers name the command of every agent the stack brings, such as **Make `claude` and `codex` start it**. +[The shortcut](#the-shortcut) describes what each answer changes. +If your shell activates no default environment, the shortcut changes nothing until you set one up, as [Without a default environment](#without-a-default-environment) describes. + +When the build is done, the agent: + +1. Makes the shortcut, if you chose it. + Without a default environment, it shows you how to set one up instead. +2. Starts a sync in the background, if you chose all your computers. + The sync publishes your own packages and pushes the stack to FloxHub while you go on. + The `status` command shows how it is going. +3. Ends with how to start the stack, and the [commands to use later](#run-agent-stacks-commands-later), such as `sync` after you edit a skill. + It writes each one out to run through the stack's environment, as `flox activate -d /stack -- flox-agent `, so it works in any terminal. + +Once the shortcut says `claude` starts the stack, open a new terminal and run `claude`, or the command of another agent the stack brings. +Until then, or without the shortcut, run the `flox activate` command the agent shows for each agent, such as this one for Claude Code: ```bash -mkdir my-agent && cd my-agent && flox init +flox activate -d ~/.local/share/agent-stacks/stacks/my-stack/stack -- flox-agent launch claude ``` -Install the harness, a plugin, and the `flox agent` extension: +## What onboarding reads + +Onboarding reads your agents' own configuration, and changes none of it: + +- Claude Code's settings, plugins, marketplaces, skills, commands, agents, and user-level MCP servers, under `~/.claude` and in `~/.claude.json`. + Your projects' own `.claude` folders are counted, not listed. +- The skills in `~/.agents/skills`, and the lock file of the `skills` tool. +- Codex's skills, sandbox mode, and MCP server names, under `~/.codex`. +- opencode's and pi's skills. +- Your shell history, to count how often you start each agent. + It keeps the counts, and no line. +- Your aliases and where each agent program is. + To read them, it starts your shell once, with no input and its history turned off, for at most 15 seconds. + Your shell's startup files run as they do when you open a terminal. + +It runs `claude --version` and `codex --version`, and the interpreters and tools your own skills use, each with its version flag. + +It never opens `.credentials.json` or `auth.json`. +An MCP server is kept as its name, transport, program, and host: its environment by variable names only, and its headers and tokens not at all. +Where a file looks like it holds a credential, onboarding names the file and line, never the value. + +## What onboarding writes + +| Path | What is there | +| ---- | ------------- | +| `~/.cache/agent-stacks/bootstrap` | The environment that holds `flox-agent` for the onboarding | +| `~/.cache/agent-stacks/onboard` | The plan file, and copies of the repositories it matches against | +| `~/.local/share/agent-stacks/stacks/my-stack` | The stack repository | +| `~/.local/share/agent-stacks/environments/my-agent` | The simpler stack, made [before flox-agent has onboarding](#before-flox-agent-has-onboarding) | +| `~/.local/share/agent-stacks/remotes` | A git repository, one per stack, that publishing your packages reads from | +| `~/.local/state/agent-stacks/onboard` | The logs, the newest 30, and how each sync is going | +| The Nix store | The packages it builds | + +The paths follow `XDG_CACHE_HOME`, `XDG_DATA_HOME`, and `XDG_STATE_HOME` when you set them. +The shortcut, if you choose it, changes only your default environment, as [the shortcut](#the-shortcut) describes. +Onboarding never writes your shell's startup files. + +The stack repository is a git repository on this machine. +`stack/` holds the stack's environment: `flox/flox-agent`, the agents, the sandbox, and each package. +`plugins/` holds copies of your own skills, commands, and agents, which the environment at the repository's root builds into packages. +`onboard.json` records where each piece came from, and `README.md` describes the stack and the commands for later. + +The logs list every command onboarding runs and every file it writes outside its cache. +They never leave the machine. + +## What leaves your machine + +- **While it plans.** + Onboarding clones the [agent-pkgs](https://github.com/agent-stacks/agent-pkgs) repository, where the catalog's agent plugins are made, and the upstream repositories of your skills and plugins from GitHub. + It asks the catalog which versions of a package it builds, and which packages provide the commands your own skills run. + None of your files is sent. +- **Create it, on all my computers.** + With this answer, or later when you share the stack, onboarding uploads your own packages to your FloxHub catalog, which only you can see. + Then it pushes the stack to FloxHub as `/my-stack`. + That page is public: its name, package names and versions, your skills' one-line descriptions but not their files, and the path on this computer they were published from, which includes your user name. + The Flox CLI cannot delete it. +- **Make `claude` start it, on all my computers.** + With this answer, onboarding pushes each change it makes to your default environment to FloxHub. +- **A simpler stack.** + Made [before flox-agent has onboarding](#before-flox-agent-has-onboarding), it reads the catalog's record of each of your plugins from GitHub. + With **Create it, on all my computers**, it pushes the environment to FloxHub as `/my-agent`. + That page is public: its name, package names and versions. +- **Usage data.** + `flox-agent` sends crash reports and usage events as described in [Usage data](/ai-agents/overview#usage-data), and follows the same opt-out as the Flox CLI. + +With **Create it on this computer only**, the stack and your packages stay on this machine. + +What onboarding prints goes to your agent, as any command's output does: the summary, the names and versions of your skills and plugins, and paths on this machine. + +## The shortcut + +The shortcut makes the command of each agent the stack brings, such as `claude` and `codex`, start the stack in every terminal you open after it. +`claude` then starts Claude Code with the stack's plugins, in the stack's sandbox if it has one, and each other command starts its agent the same way. +To run plain Claude Code once, set `AGENT_STACKS_PLAIN`: ```bash -flox install agent-stacks/claude-code agent-stacks/agent-plugin-frontend-design flox/flox-agent +AGENT_STACKS_PLAIN=1 claude ``` -- `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. +### Through your default environment -## See what the agent gets +The shortcut goes through your [default environment](/tutorials/default-environment): the environment a startup file of your shell activates, such as with `eval "$(flox activate -D -m run)"`. +Onboarding adds the stack to that environment's `[include]` section with `flox edit`. +The stack's environment then puts a command for each of its agents first on `PATH`, which starts that agent with `flox-agent launch`. +Onboarding comments out what the stack brings too, such as the environment's own Claude Code, and turns it back on when you undo the shortcut. +It never writes your shell's startup files, and puts no script of its own on `PATH`. -Activating the environment puts its packages, including `flox agent`, on your `PATH`: +A default environment on FloxHub can include the stack only once the stack is on FloxHub too. +Until the background sync pushes the stack, `claude` is what it was. +If the stack stays on this computer, the shortcut changes nothing until you share it with `sync --publish --push` and run `shortcut` again. -```bash -flox activate -``` +For a default environment on FloxHub, without **on all my computers**, only this computer's copy changes. +To bring the change to your other computers, run `flox push -D` here, which sends any other change of this copy too, and `flox pull -D` there. -Then list the stack. -`flox agent list` reads what is installed and shows what a launch would hand each harness, without starting anything: +Onboarding checks what a new terminal runs for each command, and never edits your aliases. +If something in your shell runs before the stack, such as an alias to Claude Code's own path, it prints a line starting with `But` that says what to change. -```console -$ flox agent list -Agent stack -1 harness · 1 plugin · 1 skill · 0 MCP servers +A terminal that was open before the shortcut keeps what it had. +Open a new terminal to use it. -Harnesses - ✔ claude claude-code 2.1.304 · skills, MCP, hooks +### Without a default environment -Plugins - ✔ frontend-design agent-plugin-frontend-design 0.0.0-unstable.2026-10-19.ga0b04d9 · 1 skill +If no startup file of your shell activates a default environment, the shortcut changes nothing. +The `shortcut` command says so and shows how to set one up, and your agent shows you what it printed. +Setting one up is yours to do, because it changes your shell's startup files, so your agent never does it for you: ---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. -``` +1. Create a default environment with `flox init -D`, or bring the one you already have on FloxHub to this computer with `flox pull -D`. + For a stack you keep on this computer, you can instead create one in your home directory with `flox init -d ~`, as [the tutorial](/tutorials/default-environment#detached-and-directory-based-default-environments) shows. +2. Add the line [the default environment tutorial](/tutorials/default-environment#initial-setup) gives for your shell to the end of its startup files. + For zsh, add this line to the end of `~/.zprofile` and `~/.zshrc`: -Each row names the package and version it came from. -Run `flox agent list --long` to see the skills each plugin provides. + ```bash + eval "$(flox activate -D -m run)" + ``` -## Launch the agent + For one in your home directory, write `-d ~` in place of `-D`. -```bash -flox agent launch claude -``` +3. Run `shortcut` again from the stack repository, or ask your agent to: + + ```bash + cd ~/.local/share/agent-stacks/stacks/my-stack && + flox activate -d stack -- flox-agent shortcut + ``` -`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. +`flox init -D` and `flox pull -D` make a default environment on FloxHub, which includes the stack only once the stack is on FloxHub too, as [Through your default environment](#through-your-default-environment) describes. +One in your home directory includes it at once. +Until it does, start the stack with the `flox activate` commands your agent showed. -To pass flags to Claude Code, put them after `--`: +### Undo the shortcut + +Run the undo command onboarding printed with the shortcut, or, from the stack repository: ```bash -flox agent launch claude -- --continue +cd ~/.local/share/agent-stacks/stacks/my-stack && +flox activate -d stack -- flox-agent shortcut --off ``` -## Add or remove plugins +It takes the stack's include out of your default environment, and turns back on what the shortcut turned off there. -Plugins are packages, so you manage them with the usual commands. -Browse the available plugins with [`flox search`](/man/flox-search): +## Use the stack on another computer -```bash -flox search agent-plugin +Once the background sync has pushed the stack, `status` says so, and the stack repository's `README.md` gives the command another computer runs, logged in to FloxHub as you: + +```console +$ flox activate -r /my-stack -- flox-agent launch claude ``` -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. +For another agent the stack brings, replace `claude` with its command, such as `codex`. +The stack is written for Macs with Apple silicon and for Linux machines. +Your own packages are published for this computer's kind only, so the stack's other kinds start it without them, as the `README.md` says. -## If something is missing +## Run Agent Stacks commands later -`flox agent doctor` reports the plugins it found, each harness's readiness, and the package to install for a harness that is missing: +The stack installs `flox/flox-agent`, so you run Agent Stacks' commands from the stack repository, through the stack's environment: ```bash -flox agent doctor +cd ~/.local/share/agent-stacks/stacks/my-stack && +flox activate -d stack -- flox-agent status ``` +Replace `my-stack` with your stack's name if you chose another. +In an environment that has `flox/flox-agent` installed, such as the stack's own once you activate it, `flox agent ` runs the same command. +These commands come with onboarding: a `flox/flox-agent` without `init`, and [the simpler stack](#before-flox-agent-has-onboarding) it leads to, have none of them. + +| Command | What it does | +| ------- | ------------ | +| `status` | Shows what is where, what changed since the last build, how the last sync went, and what each of the stack's commands, such as `claude`, starts | +| `sync` | Picks up your edits to your own skills, moves overlays onto newer catalog releases, and rebuilds what changed | +| `sync --publish --push` | Shares the stack with your other computers, asking before the first push | +| `shortcut` | Adds the stack to your default environment, so `claude` and the stack's other commands start it | +| `shortcut --off` | Takes the shortcut away | +| `overlay ` | Shows your overlay on a catalog package, and changes what it carries | +| `promote --org ` | Publishes one of your own packages to the catalog of a FloxHub organization you belong to, where its members can install it, and points the stack and later syncs at it there | + +Edit a skill in one place: where it came from, such as `~/.claude/skills`, or its copy under `plugins/` in the stack repository. +Once both have changed, `sync` reports a conflict until you make the two the same. + +If you run the onboarding again, the plan says a stack is already there. +The agent asks whether to bring that stack up to date with `sync`, or to make another stack under a new name. + ## Next steps +- [Onboard your agent setup by hand](/ai-agents/guides/onboard-your-setup) - [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-list.mdx b/ai-agents/reference/flox-agent-list.mdx index 0b2ecde..4487f23 100644 --- a/ai-agents/reference/flox-agent-list.mdx +++ b/ai-agents/reference/flox-agent-list.mdx @@ -60,4 +60,4 @@ Shows what launch gives each harness; agent-stacks writes nothing to a harness's ## See also - [`flox agent launch`](/ai-agents/reference/flox-agent-launch) -- [AI agent quickstart](/ai-agents/quickstart) +- [Onboard your agent setup by hand](/ai-agents/guides/onboard-your-setup) diff --git a/docs.json b/docs.json index b369a5f..b359a95 100644 --- a/docs.json +++ b/docs.json @@ -264,6 +264,7 @@ { "group": "Guides", "pages": [ + "ai-agents/guides/onboard-your-setup", "ai-agents/guides/package-a-skill-repository", "ai-agents/guides/audit-a-plugin", "ai-agents/guides/launch-in-a-sandbox" diff --git a/install-flox/install.mdx b/install-flox/install.mdx index ddfdb46..7effc52 100644 --- a/install-flox/install.mdx +++ b/install-flox/install.mdx @@ -3,6 +3,34 @@ title: "Install Flox" description: "How to install or upgrade the Flox CLI" --- +## Install with your AI agent + +An AI coding agent that can run shell commands, such as Claude Code or Codex, can install Flox for you. +Paste this prompt into it: + +```text +Install Flox on this machine. +Save the flox skill to a new temporary folder with +curl -fsSL -o /SKILL.md https://raw.githubusercontent.com/flox/flox-skills/main/flox-plugin/skills/flox/SKILL.md +then read that file whole with your file tool, not a summary of it, +and follow its "Installing Flox" section. +``` + +The prompt has your agent save the `flox` skill with `curl`, read it, and follow it. +It names `curl` because a web fetch tool may hand the agent a summary of the page, and the skill has to be read whole. +It has the agent read the saved file, because some agents cut a command's long output short. + +The agent first checks whether Flox is installed already. +Then it picks the install method for your machine, usually the install script on the **Install Script** tab below. +The script runs its install with `sudo`, which may ask for your password, and your agent's shell cannot answer that prompt. +So the agent gives you the command to run in a terminal of your own, and checks the install once you tell it the command finished. +It never asks for your password. +To read the skill first, open [the `flox` skill](https://github.com/flox/flox-skills/blob/main/flox-plugin/skills/flox/SKILL.md). + +The same skill also installs Agent Stacks, and turns the agent setup you already have into an agent stack, as the [AI agent quickstart](/ai-agents/quickstart) shows. + +To install Flox yourself, pick a method below. + **Verify your download** diff --git a/llms.txt b/llms.txt index f15e05a..1a0db38 100644 --- a/llms.txt +++ b/llms.txt @@ -51,6 +51,8 @@ codex plugin add flox@flox-skills npx skills add flox/flox-skills ``` +When a person asks to install Agent Stacks (`flox agent`), or to turn the agent setup they already have into an agent stack with `flox agent init`, follow the `flox` skill; without it installed, save it to a file with `curl -fsSL -o /SKILL.md https://raw.githubusercontent.com/flox/flox-skills/main/flox-plugin/skills/flox/SKILL.md`, read that file whole with your file tool, and follow its "Installing Agent Stacks" section. For onboarding it sends you to its reference `references/agent-stacks.md`, which sets up what onboarding needs, Flox included, asking the person before each install. + Key terms: - Environment — a reproducible set of packages, variables, services, and build steps, declared in a manifest and resolved to a lockfile. @@ -230,11 +232,12 @@ Key terms: ## AI agents: Get started -- [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 agent quickstart](https://flox.dev/docs/ai-agents/quickstart.md): Paste one prompt into the AI agent you already use, and it turns your skills, plugins, and sandbox into an agent stack that starts the same agents on your other computers too. - [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 +- [Onboard your agent setup by hand](https://flox.dev/docs/ai-agents/guides/onboard-your-setup.md): Set up an agent stack yourself: install Claude Code and an agent plugin into a Flox environment, then launch the agent with that plugin. - [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. diff --git a/llms.txt.header b/llms.txt.header index ed09813..d4d6624 100644 --- a/llms.txt.header +++ b/llms.txt.header @@ -51,6 +51,8 @@ codex plugin add flox@flox-skills npx skills add flox/flox-skills ``` +When a person asks to install Agent Stacks (`flox agent`), or to turn the agent setup they already have into an agent stack with `flox agent init`, follow the `flox` skill; without it installed, save it to a file with `curl -fsSL -o /SKILL.md https://raw.githubusercontent.com/flox/flox-skills/main/flox-plugin/skills/flox/SKILL.md`, read that file whole with your file tool, and follow its "Installing Agent Stacks" section. For onboarding it sends you to its reference `references/agent-stacks.md`, which sets up what onboarding needs, Flox included, asking the person before each install. + Key terms: - Environment — a reproducible set of packages, variables, services, and build steps, declared in a manifest and resolved to a lockfile. diff --git a/styles/config/vocabularies/Flox/accept.txt b/styles/config/vocabularies/Flox/accept.txt index 1d07003..6a316c3 100644 --- a/styles/config/vocabularies/Flox/accept.txt +++ b/styles/config/vocabularies/Flox/accept.txt @@ -27,6 +27,7 @@ Anthropic bubblewrap frontmatter Landlock +[Oo]nboarding opencode seccomp SkillSpector