Cette page n’est pas encore traduite.

The runner (instruction agents run)

This page is for developers who run agents on their own machines. You will install the runner, instruction agents run, point it at a deployment rule or a platform, and keep it running so each instruction released there has an agent of its own.

A deployment is one instruction assigned to a platform: a short name for a machine or a service, such as agents-box or laptop. The server takes 1 to 48 letters, digits, dots, dashes and underscores, starting with a letter or a digit, and keeps it in lower case; the editor's Where they run field takes up to 40. A deployment rule makes one deployment for each instruction in a scope (a project, a folder, some tags) and keeps them in step as instructions come and go. The runner reads those deployments, starts one process per deployment, and reports back what each one runs.

One process per deployment, each in a folder of its own, reported back to instruction.md.

Before you start

Plans On Pro, Team, and Enterprise

Deploying one instruction (Share ▸ Deploy to… in the editor, or deployments_create) needs the plan above. A rule (Run every instruction here on… on a project or a folder, or deployments_rules_create) needs this one:

Plans On Team and Enterprise

  • Who can do this. An organization's owners and admins make rules and approve agents. Deploying one instruction needs the Admin role on it (the manage permission). It starts at once in a personal workspace or when an owner or admin deploys it; a member's deployment waits for an owner's or an admin's approval.
  • The machine. Node.js 20.19 or later, and the agent's app installed for the user the runner runs as: Claude Code (claude), Codex (codex) or your own program. The runner doesn't install them.
  • A released version. Only released instructions get an agent: a draft that was never released has nothing to run.

The rule itself is made in the editor or over MCP. The people side of it, step by step with the editor's labels, is Run agents.

Install the runner

The runner is the run command of @instruction.md/agents. Install it once, for every user, on the machine:

Shell
npm i -g @instruction.md/agents
instruction-agents --version

instruction agents run … (from npm i -g instruction.md, 0.11.0 or later) hands over to the same command, and instruction-agents run … is its own name. With nothing installed, npx runs it:

Shell
npx -y @instruction.md/agents run --help

For a service, install it globally rather than through npx: the unit and the cron line below name a fixed path, and an agent's header command runs the same binary.

Sign the runner in

The runner reads the deployments as whoever is signed in on the machine, so the user it runs as signs in once. On a machine with no browser, --device prints a code to enter on another device:

Shell
# as the user the agents run as (here: agents), once
sudo -u agents -H instruction-agents login --device
sudo -u agents -H instruction-agents whoami

That sign-in is the same as instruction login's, and it is renewed as it runs out. The person who signs in must be able to read the instructions: the runner sees only the deployments of instructions that person can read.

A token passed with --token or INSTRUCTION_MD_TOKEN is used as it is and never renewed. That suits a pass that ends before the token does, such as one minted from an agent credential for each cron run. A runner that keeps running needs the stored sign-in.

Shell
# a token given as it is: used, never renewed (a short pass only)
INSTRUCTION_MD_TOKEN="<access token>" instruction agents run --rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B --once -- claude -p "Do the work your instruction describes."

Run it

After -- comes the command to run for each agent. For Claude Code, give the task as claude -p "…". The runner then hosts Claude Code itself, so its questions and permission requests reach people on instruction.md (Conversations):

Shell
instruction agents run --rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B -- claude -p "Do the work your instruction describes."

For Codex:

Shell
instruction agents run --rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B -- codex exec --skip-git-repo-check "Do the work your instruction describes."

--rule runs one rule's deployments. --platform runs every deployment for that platform name in the organization: those of every rule, and the instructions deployed one at a time.

Shell
instruction agents run --platform agents-box --org acme -- claude -p "Do the work your instruction describes."

The editor shows the same line under Run this on the machine, with Copy the command, written as npx -y @instruction.md/agents fleet …: fleet is the earlier name of run, and both work.

What the runner prints as it starts, on stderr:

Output
$ instruction agents run --rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B -- claude -p "Do the work your instruction describes."
fleet: rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B, folders in /srv/agents/instruction-fleet; Ctrl-C stops every agent it started
acme/refunds: no servers or skills
acme/refunds: started at v3 in /srv/agents/instruction-fleet/acme__refunds
acme/support-agent: servers desk; skills triage
acme/support-agent: started at v7 in /srv/agents/instruction-fleet/acme__support-agent
fleet Support on agents-box: 3 deployment(s), 2 running
  acme/onboarding                      v1       live     waiting for approval
  acme/refunds                         v3       live     running (pid 41822)
  acme/support-agent                   v7       live     running (pid 41823)
fleet: listening for changes (and reading every 60 s)

Your own command

Any program works. In the command, three placeholders are replaced for each agent:

  • {instruction} becomes the address the agent follows, such as instruction://acme/support-agent@latest. When a release is held for approval, or the rule is paused, it names the version the agent may run instead of the ref.
  • {name} becomes owner/name, such as acme/support-agent.
  • {dir} becomes the agent's folder, which is also its working directory.

Each process also gets INSTRUCTION_MD_FOLLOW (the same address), INSTRUCTION_MD_DEPLOYMENT (its deployment's id, dep_…), INSTRUCTION_MD_ACCOUNTS (this machine's accounts file) and, for another server than the default, INSTRUCTION_MD_URL.

Shell
instruction agents run --platform agents-box --org acme -- ./my-agent --instruction {instruction} --name {name} --workdir {dir}
./my-agent
#!/bin/sh
# ./my-agent: what the runner starts in each agent's folder (the folder is the working directory)
echo "following $INSTRUCTION_MD_FOLLOW as deployment $INSTRUCTION_MD_DEPLOYMENT" >&2
exec agentd --follow "$INSTRUCTION_MD_FOLLOW"

The runner writes the MCP servers and skills an instruction names only for Claude Code and Codex, which it tells from the command's first word (claude, codex). A script that runs Claude Code inside sets those up itself, with instruction agents apply (Servers, skills and accounts).

See what it would do

--dry-run reads the deployments once, prints what it would start, stop, restart or leave, and exits. It starts nothing and reports nothing.

Output
$ instruction agents run --rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B --dry-run -- claude -p "Do the work your instruction describes."
would start acme/refunds (instruction://acme/refunds@latest)
would start acme/support-agent (instruction://acme/support-agent@latest)
would leave acme/onboarding: waiting for approval

Folders and logs

Each deployment gets a folder under --dir (./instruction-fleet by default), named owner__name. The runner starts the agent's process in it.

instruction-fleet/
instruction-fleet/
  .instruction-fleet.json            the folders the runner made, and what it started
  acme__support-agent/
    .instruction/
      follow.json                    the instruction this agent follows, and its deployment
      fleet.log                      everything the agent wrote (stdout and stderr)
      applied.json                   the servers and skills written for it
      mcp.json                       Claude Code: its servers (--mcp-config)
      claude-settings.json           Claude Code: its allowed and denied tools (--settings)
      state.json                     the hooks' copy of the version it runs
    .claude/skills/triage/SKILL.md   its skills
  acme__refunds/
    .instruction/follow.json
  • .instruction/follow.json names the instruction the agent follows, so the agent's hooks give it the instruction and each new version (How following works). It also names the deployment, which the hooks use to hand over people's messages. "converse": true means the runner hosts the agent, and the hooks leave messages to it.
  • .instruction/fleet.log holds everything the agent wrote. The runner keeps the last 20 lines of its stderr, and reports the last 5 when it fails.
  • .instruction-fleet.json records the folders the runner made, and the process it started for each. It never deletes a folder it didn't make.
  • Codex reads a folder's .codex/config.toml only in a trusted folder. The runner marks its own folders trusted in a block of its own in $CODEX_HOME/config.toml, and takes them out again with --clean.
.instruction/follow.json
{
  "follow": "instruction://acme/support-agent@latest",
  "deploymentId": "dep_01JX9K3V5N7Q2R4T6W8Y0Z1A3C",
  "converse": true
}

What the runner does on each pass

The runner reads the deployments when it starts, every --interval seconds (60 by default), and whenever the server announces a change on the platform's deployment:// address. On each pass it compares what runs with what the server says:

The deployment What the runner does
New and active Writes its folder, its servers and skills, checks its sign-ins, and starts it.
Waiting for approval (pending_approval) Starts nothing until an owner or an admin approves it.
A new version, onRelease: live Points the folder at it. The agent takes it at its next turn, through its hooks.
A new version, onRelease: restart Stops the agent and starts it again on the new version.
A new version, onRelease: approve Keeps the agent on its approved version. The new one waits as the deployment's pending version.
A new version that changes its servers or skills Restarts the agent, even with live, because its app reads them as it starts.
Paused (the rule is paused) Keeps the agent at its version, and starts it again pinned to that version if it isn't running.
Retired, or gone from the list Stops the agent.
Over the limit Leaves it out: --max on this machine, or the rule's maxAgents. When a limit is lowered, the agents last by deployment id stop.

When the rule is deleted, the runner stops every agent and exits. Ctrl-C or SIGTERM stops the runner and every agent it started: each is sent SIGTERM, then SIGKILL after 10 seconds.

Before it starts a Claude Code or Codex agent, the runner checks the app's own sign-in and each server's account, as instruction agents check --fleet does. An agent that would wait for a sign-in nobody is there to give is not started. It is reported as needing a sign-in, with the command to run on the machine, and it starts once that is fixed. See Servers, skills and accounts.

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 systemd service. --restart-on-exit starts an agent again when it exits on its own, after 5 seconds, then 10, doubling up to 5 minutes.

instruction-agents.service
# /etc/systemd/system/instruction-agents.service
[Unit]
Description=instruction.md runner (instruction agents run)
After=network-online.target
Wants=network-online.target

[Service]
User=agents
WorkingDirectory=/srv/agents
Environment=PATH=/usr/local/bin:/usr/bin:/bin
ExecStart=/usr/local/bin/instruction-agents run --rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B --restart-on-exit -- claude -p "Do the work your instruction describes."
Restart=on-failure
# the runner stops its agents itself (SIGTERM, then SIGKILL after 10 seconds): give it the time, and signal it alone
KillMode=mixed
TimeoutStopSec=30

[Install]
WantedBy=multi-user.target
Shell
sudo systemctl daemon-reload
sudo systemctl enable --now instruction-agents
journalctl -u instruction-agents -f

User=agents gives the service that user's home, where its sign-in and accounts are kept. The agents run as that user too, with its files and permissions: give them a user of their own.

A task that runs and ends

claude -p and codex exec do one piece of work and end. Run the runner from cron with --once: it starts every agent, waits for each to finish, reports, and exits. --clean then removes the folders of agents that were retired. Cron runs with a short PATH, so set it.

crontab
# crontab -e, as the user the agents run as
PATH=/usr/local/bin:/usr/bin:/bin
# every 15 minutes: one pass, each agent runs to its end; flock keeps two passes from overlapping
*/15 * * * * cd /srv/agents && flock -n .runner.lock instruction-agents run --rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B --once --clean -- claude -p "Work through the new tickets, then stop." >> runner.log 2>&1

With --once, a Claude Code agent the runner hosts is closed as soon as its task ends, so the pass doesn't wait on an idle session.

Remote Control

With --remote-control, each Claude Code agent runs as a session you control in the Claude app. On claude.ai/code or the phone app you watch it work, write to it, approve what it asks to do and answer its questions. Each session is named instruction.md: owner/name, so you can tell them apart. In the Agents app, an agent run this way shows Open in Claude instead of a chat.

Shell
instruction agents run --rule dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B --remote-control -- claude -p "Do the work your instruction describes."

It needs:

  • Claude Code signed in with a claude.ai account on a Pro, Max, Team or Enterprise plan, not an API key. On Team and Enterprise, an admin turns Remote Control on. The runner doesn't hand the agents ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN or ANTHROPIC_BASE_URL from its own environment, so the claude.ai sign-in is the one used.
  • Linux or macOS. The session runs in a pseudo-terminal from the system's script command (/usr/bin/script or /bin/script).
  • The task as claude -p "…". The runner turns it into an interactive session and gives it the task as its first message. Any other command runs without Remote Control, and the runner says so once.
  • A runner that keeps running. These sessions don't end on their own, so --remote-control with --once exits with code 2.

The runner answers Claude Code's question whether to trust the folder, since it made the folder. Questions and permission requests are then answered in the Claude app, not on instruction.md. Messages written on instruction.md still reach the agent through its hooks at its next prompt. The conversation is kept by Anthropic, as for any Claude Code session you control from the app. If Claude Code refuses Remote Control (an API key instead of a claude.ai sign-in, a plan without it, an admin's switch off), the runner logs its words, and they are among the lines reported if the agent fails.

Rules over MCP

The editor sets the scope and the five controls it shows. The other controls and selectors exist only over MCP: deployments_rules_create, deployments_rules_update (a control set to null goes back to its default) and deployments_rules_preview, which shows what a selector takes before you save it. All of them are on the tools reference.

deployments_rules_create
{
  "orgId": "acme",
  "name": "Support on agents-box",
  "platform": "agents-box",
  "selector": {
    "project": "prj_01JX0000000000000000000000",
    "tags": { "any": ["support", "billing"] },
    "visibility": ["internal"],
    "exclude": { "instructions": ["ins_01JX0000000000000000000001"] }
  },
  "controls": {
    "ref": "stable",
    "onRelease": "restart",
    "onCreate": "approve",
    "onLeave": "retire",
    "maxAgents": 20,
    "requireSignature": true,
    "answerWithin": 60,
    "parameters": {
      "region": "eu-west",
      "ins_01JX0000000000000000000002": { "region": "us-east" }
    },
    "budget": { "currency": "EUR", "perAgentPerDay": 20 }
  }
}

Controls

Plans Team 50 · Enterprise unlimited

ControlTypeIn the editorDefaultEffect
refstringVersion to followlatestThe ref each agent follows: latest, stable, or another ref you keep.
onReleaselive | restart | approveWhen a new version is releasedlivelive: the agent takes the release at its next turn, through its hooks. restart: the runner restarts the agent on it. approve: the release waits as the deployment's pending version until an owner or admin approves it.
onCreatestart | approveWhen a new agent is neededapprove in an organization, start in a personal workspacestart: a new deployment is active at once. approve: it waits for deployments_approve.
onLeaveretire | keepWhen an instruction leaves this placeretireretire: the agent of an instruction that leaves the scope (moved, archived, deleted, a tag removed) is stopped. keep: it keeps running.
maxAgentsinteger 1 or moreAt most this many agents10, held to the plan's ceilingThe most agents the rule makes. Past it, instructions get no agent and owners and admins are told once. Lowered, the newest agents are retired.
parametersobjectMCP onlynoneParameter values, at most 16 KB: keys for every instruction, and an "ins_…" key for one instruction's own. Stored on each deployment and returned by deployments_list. instruction agents run doesn't pass them to the agent.
budgetobjectMCP onlynoneA spending allowance, an object of at most 4 KB, kept with the rule. Neither the server nor the runner enforces it yet.
requireSignaturebooleanMCP onlyfalseWritten into each follow.json: the agents' hooks take signed versions only.
answerWithininteger 1–1440MCP only30Minutes an agent's question or permission waits for a person. Then a permission is denied and a question is left to the agent.

Selector

The selector's parts are AND-combined, and at least one of project, folder, tags, instructions or workspace is given. A rule takes only instructions its maker can read.

SelectorIn the editorWhat it takes
projectRun every instruction here on… on a projectA project's instructions (prj_…).
folderRun every instruction here on… on a folder; Include the instructions in its folders too{ id, deep }: a folder's instructions, and with deep its subfolders' too.
tagsOnly instructions with these tags; Any of these tags / All of these tags{ all, any }: instructions with every one, or one, of up to 20 tags.
instructionsMCP onlyA list of up to 500 instructions, by id or owner/name.
workspaceMCP onlyA workspace's instructions (ws_… or its slug).
visibilityMCP onlyNarrows the others to private, internal or public instructions.
excludeSet when you stop one agent by hand{ instructions, tags }: left out of the rule.

Approve, pause and stop

  • deployments_approve approves what waits on a deployment: a new agent, or a release held by onRelease: approve. In the editor, that is Approve or Approve the version on Settings ▸ Deployments.
  • deployments_rules_update with paused pauses a rule: nothing new starts or changes, its agents keep their version, and releases wait until it resumes.
  • deployments_retire stops one agent for good. One a rule made is added to the rule's exclude, so the rule doesn't make it again. In the editor, that is Stop on a running agent, or Decline on one waiting for approval.
deployments_rules_update
{ "ruleId": "dpr_01JX7Q2M4N8R5T6V9W0Y3Z1A2B", "paused": true }

An organization keeps at most 200 rules.

All the options

These are generated from the command's own usage line:

instruction agents run --help
usage: instruction agents run (--rule dpr_… | --platform LABEL [--org SLUG]) [--dir D] [--max N] [--interval S] [--once] [--dry-run] [--restart-on-exit] [--clean] [--host APP] [--accounts FILE] [--no-apply] [--no-converse] [--remote-control] [--cli CMD] [--url U] [--token T] -- <command…>
OptionDefaultWhat it does
--rule dpr_…Run the deployments of one rule. Give --rule or --platform, not both.
--platform LABELRun every deployment for this platform name: those of every rule and those deployed one at a time with Deploy to….
--org SLUGWith --platform only: the organization, by slug or id (exit 4 when it isn't one of yours). Without it, the server takes your personal workspace's organization (an agent credential's own), and the runner can't listen for changes, so it reads every --interval.
--dir D./instruction-fleetWhere the agents' folders go, one per deployment, named owner__name.
--max Nno limitAt most this many agents on this machine, whatever the rule allows. A whole number above 0.
--interval S60Seconds between reads of the deployments (at least 1). The runner also reads again whenever the server announces a change.
--onceOne pass: start every agent, wait for each to end, report, and exit. For cron and CI. Not with --remote-control.
--dry-runPrint what it would start, stop, restart or leave, and do nothing. Nothing is reported.
--restart-on-exitStart an agent again when it exits on its own, after a pause that doubles from 5 seconds up to 5 minutes.
--cleanWith --once: remove the folders the runner made for deployments that are retired or gone. It never removes a folder it didn't make.
--host APPthe command's appThe app the reports name (claude-code, codex, agentd…). The app is told from the command (claude, codex) whatever this says.
--accounts FILE$INSTRUCTION_MD_ACCOUNTS, else ~/.config/instruction-md/accounts.jsonThis machine's accounts file. Handed to each agent as INSTRUCTION_MD_ACCOUNTS and named in its servers' header commands.
--no-applyDon't write the instruction's MCP servers and skills into the agent's folder.
--no-converseRun Claude Code as a plain process: its questions and permission requests stay in the process. Messages still reach it through its hooks.
--remote-controlRun each Claude Code agent as a session you control in the Claude app (see Remote Control below).
--cli CMDthis runnerHow the agents' apps run instruction-agents for a server's credential (the header command).
--url Uhttps://instruction.md/mcpAnother instruction.md server. Written into each follow.json when it isn't the default.
--token Tthe stored sign-inA token used as it is and never renewed. INSTRUCTION_MD_TOKEN does the same.

The flag reference for every other instruction agents command is instruction agents commands.

Exit codes and states

Exit code When
0 It stopped normally (Ctrl-C, SIGTERM, the rule deleted), or a --once pass where every agent exited 0, or a --dry-run.
1 A --once pass where an agent exited with another code, or the first read of the deployments failed with another server error.
2 A usage error: neither or both of --rule and --platform, --org without --platform, no command after --, a bad --max or --interval, --remote-control with --once.
3 Not signed in, or the server couldn't be reached on the first read.
4 --org names no organization of yours, or the first read found no such rule (not_found).
5 The first read was refused (forbidden).

Only the first read ends the runner. A later read that fails is logged as reconcile: …, and the next pass tries again.

The runner reports each agent with deployments_report: whether it runs, the version it applied, and its health. Settings ▸ Deployments shows the same.

Health Meaning
ok It runs, or it ended with code 0, or the runner stopped it.
failed It exited with another code or a signal. The report carries the last 5 lines of its stderr.
needs_sign_in It wasn't started, or its app exited, because a sign-in is missing. The report lists what is missing and the command that gives it. Whoever made the rule and whoever deployed it are notified once.

A report is sent on every change. While nothing changes, the same report is sent again on the first pass at least 5 minutes after the last one, so with the default --interval every agent reports at least every 5 minutes.

Before you start the service, check the machine as the runner's user. --fleet treats a sign-in that would wait for a person as a blocker:

Shell
$ sudo -u agents -H instruction-agents check --host claude-code --fleet
✓ signed in (no project here follows an instruction)
✓ Claude Code 2.1.330, signed in

Nothing stops the agent.

What this doesn't do

  • Holding a version back, for an approval or a paused rule, works for agents the runner started. An agent you set up another 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 runner's user. Use each app's permission settings, and a user of their own.
  • It doesn't pass a rule's parameters to the agent, and nothing enforces its budget yet.

If it doesn't work

What you see Why What to do
instruction agents run reads your organization's deployments: sign in first No sign-in for this user (exit 3). Run instruction-agents login --device as that user.
no organization acme among yours (…) --org isn't one of the signed-in person's organizations (exit 4). Check the slug, or sign in as a member.
deployments_list: not_found: … The rule's id is wrong, or the signed-in person can't see the rule (exit 4). Copy the command again from the rule's Edit ▸ The command to run on Settings ▸ Deployments, or sign in as a member who can read it.
rule dpr_…: … (its deployments run with the defaults: live, no limit of the rule's) The signed-in person may not read the rule. Sign in as someone who can, or use --platform.
… not started, it needs: … A sign-in is missing for the agent's app or a server. Run the fix it prints, as the runner's user, then wait for the next pass. See Servers, skills and accounts.
fleet: its agents' questions can't reach instruction.md: … Claude Code isn't run as claude -p "…", or the command already sets --input-format or --output-format. Give the task as claude -p "…" without those flags.
An agent shows Behind on Settings ▸ Deployments It runs an older version than the rule says: a release waits for approval, or a live agent hasn't had its next turn. Approve the version, or wait for its next turn.

Still stuck: ask us.

Last checked against the product:

Was this page helpful? Report a problem