Deployments

A deployment runs an instruction as an agent on a machine or a service of yours. You can deploy one instruction, or make a rule that runs every instruction of a project or a folder: each instruction released there gets an agent of its own, and you choose what happens when a new version comes out.

You set it up in the editor. On the machine, one command, instruction fleet, starts the agents and keeps them in step with what the rule says.

Plans: rules are on Team and Enterprise. Deploying one instruction at a time is on Pro and above.

1. Make a rule

  1. In the editor, open the ⋯ menu on a project or a folder and choose Run every instruction here on…
  2. Under Where they run, give the machine a short name, such as laptop or support-server. The command you run there uses this name.
  3. Choose which instructions: those in its folders too, or only those with some tags.
  4. Choose how the agents act (see the choices below). The preview says how many agents the rule would start now.
  5. Save. The editor shows the command to run on the machine.

To run a single instruction instead, open it and choose Deploy to…. Its command names the machine (--platform) rather than a rule. Everything else below works the same way.

2. Run it on the machine

The machine needs Node.js 18 or later. Sign in there once. On a machine without a browser, you get a code to enter on another device:

Shell
npx -y instruction.md login --device

Then run the command the editor showed you. For Claude Code:

Shell
npx -y instruction.md fleet --rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B -- claude -p "Do the work your instruction describes."

For Codex:

Shell
npx -y instruction.md fleet --rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B -- codex exec --skip-git-repo-check "Do the work your instruction describes."

The runner makes a folder for each agent and runs your command inside it. Each folder holds a .instruction/follow.json that names the instruction its agent follows:

Folders
instruction-fleet/
  acme__support-triage/
    .instruction/follow.json      the instruction this agent follows
  acme__refunds/
    .instruction/follow.json
  .instruction-fleet.json          what the runner started (it keeps track here)

Claude Code and Codex apply the instruction through instruction.md's plugin, so install it once on that machine for the user the runner runs as (Claude Code, Codex, or managed settings for every user). Codex asks you once to trust the plugin's hooks.

Before it starts an agent, the runner writes the MCP servers and skills its instruction names into the agent's folder, and checks that every sign-in the agent needs is there; one that isn't shows as Needs sign-in, with the command to run. See Servers, skills and sign-ins. When an agent asks a question or wants permission, it asks you on the Deployments page: see Talking with agents.

Any other program works too. In your command, {instruction} becomes the instruction's address, {name} its name and {dir} the agent's folder. Each program also gets the address in INSTRUCTION_MD_FOLLOW and its deployment's id in INSTRUCTION_MD_DEPLOYMENT:

Shell
npx -y instruction.md fleet --platform laptop --org acme -- ./my-agent --instruction {instruction}

--platform runs every deployment for that machine name in the organization, instead of one rule's. To see what the runner would start and stop without doing it:

Shell
npx -y instruction.md fleet --rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B --dry-run -- claude -p "Do the work your instruction describes."

3. Keep it running

Choose by what your agent does.

An agent that keeps running

For a service or a bot that stays up, run the runner as a service. It checks the rule every minute: it starts an agent for a new instruction, stops the agent of one that left, and applies new versions. --restart-on-exit starts an agent again if it stops on its own. Stopping the runner stops every agent it started.

/etc/systemd/system/instruction-agents.service
[Unit]
Description=instruction.md agents
After=network-online.target

[Service]
User=agents
WorkingDirectory=/srv/agents
ExecStart=/usr/bin/npx -y instruction.md fleet --rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B --restart-on-exit -- ./my-agent --instruction {instruction}
Restart=on-failure
# (the runner stops its agents first: SIGTERM, then SIGKILL after 10 seconds)
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target

A task that runs and ends

claude -p and codex exec do one piece of work and end. Run the runner on a schedule with --once: it starts every agent, waits for each to finish, reports, and ends. --clean also removes the folders of agents that were stopped.

crontab
# every 15 minutes: one pass, each agent runs to its end; never two passes at once
*/15 * * * * cd /srv/agents && flock -n .fleet.lock npx -y instruction.md fleet --rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B --once --clean -- claude -p "Do the work your instruction describes." >> fleet.log 2>&1

4. Approve new agents

In an organization, a rule's new agent waits until an owner or an admin approves it. That is the default, and you can change it in the rule. An instruction a member deploys by itself waits too. Owners and admins are told in their notifications, and Settings ▸ Deployments shows how many are waiting. Approve them there. The notice is marked read once nothing it mentions is waiting any more.

In your personal workspace, new agents start right away.

The choices in a rule

ChoiceWhat happens
Version to followThe latest version, the one named stable, or another name you keep for releases.
When a new version is released: each agent takes it at its next turnThe agent keeps running. In Claude Code and Codex, the plugin gives it the new version with its next prompt.
… restart each agent with itThe runner stops the agent and starts it again on the new version.
… wait for an owner's or an admin's approvalThe agent stays on the version it runs. The new one waits in Settings ▸ Deployments until someone approves it.
When a new agent is neededWait for an owner's or an admin's approval, or start it right away.
When an instruction leaves this placeStop its agent, or keep it running. An instruction leaves when it is moved out, archived, deleted, or loses the tags the rule asks for.
At most this many agentsThe rule starts no more than this. Team allows up to 50 per rule, Enterprise has no limit. Past it, owners and admins are told which instructions got no agent. Lower it and the newest agents stop, those still waiting for approval first; raise it again and they start again, after approval if the rule asks for it.

Pausing a rule holds every new version until you resume it. Its agents keep running the versions they have. Stopping one agent by hand leaves its instruction out of the rule from then on, so the rule doesn't start it again.

Only released instructions get an agent: a draft that was never released has nothing to run.

What you see

The runner reports each agent: whether it is running, the version it runs, and, if it failed, the last lines it wrote. Settings ▸ Deployments shows every rule's agents, and which ones run an older version than the rule says. It updates as agents start, stop and report, without reloading the page.

All the options

OptionWhat it does
--rule dpr_…the agents of one rule
--platform NAME [--org SLUG]every agent for this machine name in the organization: from every rule, and the instructions deployed one at a time
--dir FOLDERwhere the agents' folders go (./instruction-fleet by default)
--max Nat most this many agents on this machine, whatever the rule allows
--interval SECONDShow often it checks the rule (every 60 seconds by default)
--onceone pass: start the agents, wait for each to end, report, end
--dry-runsay what it would start and stop, and do nothing
--restart-on-exitstart an agent again when it stops on its own
--cleanwith --once: remove the folders of agents that were stopped
--host APPthe app it says the agents run in, in its reports (claude-code, codex)
--url, --tokenanother registry, or a token instead of the kept sign-in

After -- comes the command to run for each agent. Ctrl-C stops the runner and every agent it started (each is asked to stop, then made to after 10 seconds).

What this doesn't do

  • Holding a version back, for an approval or a paused rule, works for agents that instruction fleet started. An agent you set up some other way follows its own .instruction/follow.json.
  • It doesn't install Claude Code, Codex or the plugin, and it doesn't fence the agents in: they run as the user who runs the runner, with that user's files and permissions. Use each tool's permission settings, and a user of their own for the agents.
  • A token given with --token is used as it is and never renewed. For a runner that keeps running, sign in with instruction login instead.