Run your instructions as agents

This page is for anyone who wants an instruction to do its work as an agent on a computer or a server of their own. You will deploy one instruction, or set up a rule that gives every instruction in a project or a folder an agent of its own.

What a deployment is

A deployment is one agent that follows one instruction, on a machine you name. The machine can be a laptop, a server or a service your team runs. In the editor, the name of the machine is called Where they run. Use a short name such as laptop or support-server.

You can deploy one instruction at a time. Or you can make a rule for a project or a folder. Then every instruction there gets its own agent, and each instruction added later gets one too.

You choose everything in the editor. On the machine itself, someone runs one command that the editor gives you. That command starts the agents, gives each one a folder of its own, and keeps them in step with your choices. Each agent tells instruction.md how it is doing, so you can follow them all from the editor.

From a rule to agents on your machine.

An agent always runs a published version. A draft that was never published has nothing to run.

Before you start

  • Your plan. Deploying one instruction:

    Plans On Pro, Team, and Enterprise

    Running every instruction of a project or a folder:

    Plans On Team and Enterprise

  • Your role. To deploy one instruction, you need the Admin role on it. Only the organization's owners and admins can make a rule. See People and roles.

  • A published version. Publish the instruction first. See Publish a version.

  • A machine, and someone who can use it. The person who sets up the machine needs to run one command there. If that isn't you, send them the command the editor shows, and the page for developers: The runner.

Deploy one instruction

Plans On Pro, Team, and Enterprise

  1. Open the instruction

    Open the instruction in the editor.

  2. Choose Deploy to…

    Choose Share ▸ Deploy to…. If the instruction isn't published yet, the dialog says Publish it first: an agent runs a released version. Publish it, then come back.

  3. Name the machine

    Under Where they run, type a short name for the machine. Use letters, digits, - and _, up to 40 characters.

  4. Choose the version

    Under Version to follow, choose latest (the version that is live now) or another name your team keeps, such as stable. The agent moves to each new version with this name as it is published. A stable version exists only once someone creates it: see A stable version.

  5. Deploy

    Choose Deploy. The dialog shows the command to run on the machine. Under The agent to run, pick Claude Code, Codex or Your own command, then choose Copy the command.

In your personal workspace, the agent can start right away. In an organization, it waits until an owner or an admin approves it, unless you are one. The dialog then says Deployed. It waits until an owner or an admin approves it in Settings ▸ Deployments; then run this on …

Run every instruction in a project or a folder

Plans On Team and Enterprise

Who can do this: the organization's owners and admins.

Run every instruction here on…
  1. Open the menu of a project or a folder

    In the side bar, or on the Instructions page, open the ⋯ menu of a project or a folder. Choose Run every instruction here on…. You can also start from Settings ▸ Deployments ▸ New rule and pick the project or folder there.

  2. Name the machine

    Under Where they run, type a short name for the machine, such as support-server.

  3. Choose which instructions

    For a folder, keep Include the instructions in its folders too ticked to take its subfolders as well. To take only some instructions, type their tags under Only instructions with these tags (optional). With more than one tag, choose Any of these tags or All of these tags. Leave it empty to take every instruction here.

  4. Check the preview

    Under What it would start now, read the list. See Preview what a rule would start.

  5. Choose how the agents act (optional)

    Open How the agents act to change the defaults. Each choice is explained in The choices in a rule.

  6. Save

    Choose Save and continue. The dialog shows the one command to run on the machine. Under The agent to run, pick Claude Code, Codex or Your own command, then choose Copy the command.

The rule is named after its place and its machine, such as "Support on laptop". You can give it another name under How the agents act ▸ Name of the rule.

The choices in a rule

Choice What it does Default
Version to follow The latest version, or The version named stable. An agent runs the version this name points to. The latest version
When a new version is released Each agent takes it at its next turn: the agent keeps running and gets the new version at its next turn. Restart each agent with it: the agent stops and starts again on the new version. Wait for an owner's or an admin's approval: the agent stays on its version until someone approves the new one. Each agent takes it at its next turn
When a new agent is needed Wait for an owner's or an admin's approval, or Start it right away. In an organization, wait for approval
When an instruction leaves this place Stop its agent, or Keep its agent running. An instruction leaves when it is moved out, archived or deleted, or loses the tags the rule asks for. Stop its agent
At most this many agents The rule starts no more than this many agents. 10
Name of the rule How the rule is shown in Settings ▸ Deployments. Its place on its machine

How many agents a rule may start depends on your plan:

Plans Team 50 · Enterprise unlimited

When a rule takes more instructions than it may start, owners and admins are told which instructions got no agent. If you lower the number, the newest agents stop first, starting with those still waiting for approval. Raise it again and they start again, after approval if the rule asks for it.

Preview what a rule would start

While you fill in the rule, What it would start now lists each instruction it takes, with the version its agent would run. The line above the list says how many agents would start, for example This would start 3 agents:. When new agents wait for approval, it says This would add 3 agents, each waiting for approval:.

  • Untick an instruction to leave it out of the rule. Tick it again to put it back.
  • no version named stable means that instruction has no version called stable yet. Its agent has nothing to run until someone creates it.
  • No instruction here yet. An agent starts as each one is added. means the place is empty for now.
  • When the list is longer than the limit, a line says how many are kept and how many agents start. Raise At most this many agents, or leave some out.

Start the agents on the machine

The editor gives one command for each rule, and one for each machine you deploy single instructions to. Someone runs that command on the machine, once. From then on, it starts the agents, stops them, and brings them new versions as your choices say.

Each agent gets a folder of its own on the machine. Before an agent starts, the machine also sets up the tools and skills its instruction names. If one of them needs a sign-in, the agent shows Needs sign-in until someone signs in on that machine.

To see the command again later, open the rule's Edit in Settings ▸ Deployments, then The command to run. Use it for a second machine, or when you set the first one up again.

For developers: The runner explains the command, its options and how to keep it running.

Approve new agents and versions

In an organization, a new agent waits for approval by default. So does a new version, when the rule says Wait for an owner's or an admin's approval.

Owners and admins get a notification. Settings ▸ Deployments shows how many things wait, under Waiting for approval.

Settings ▸ Deployments, with agents waiting for approval.
  • Choose Approve to start a new agent.
  • Choose Approve the version to give an agent the new version that waits for it.
  • Choose Decline to turn down a new agent. It is stopped for good.

The notification is marked read once nothing it mentions is waiting any more.

Follow your agents

Settings ▸ Deployments lists every rule with its agents, then the instructions deployed one at a time under Single instructions. The page updates as agents start, stop and report, without reloading.

Under each agent, a line says where it runs, which version it runs, and when it last reported. Its badges say how it is:

Badge What it means
Running The agent runs.
Not started yet The agent is approved, but the machine hasn't reported it yet.
Not running The machine says the agent isn't running now.
Waiting for approval A new agent waits for an owner or an admin.
Paused The agent's rule is paused.
Stopped for good The agent was stopped. These are counted at the end of the list, not shown one by one.
Behind The agent runs an older version than its rule says, for example "runs v3, v4 is out".
v4 waiting for approval A new version waits for an owner or an admin.
Needs sign-in A tool the agent uses needs a sign-in on its machine. The line under it says what to run there.
Failed The agent stopped with an error. Its last line is shown.
Degraded The agent runs, but something isn't working fully.

Choose Conversation on an agent to read what it did and to write to it. See Answer your agents. To follow all your agents in one place, use the Agents app.

What happens when you publish

When you publish a new version, each agent that follows that version's name gets it the way its rule says: at its next turn, by restarting, or after an approval. Agents that wait for approval show the new version as a badge until someone approves it.

A new version reaching running agents.

Pause, resume or delete a rule

Who can do this: the organization's owners and admins.

In Settings ▸ Deployments, each rule has a row called This rule, with its buttons:

  • Pause holds the rule. Its agents keep running the version they have, and nothing new starts or changes. The rule shows Paused.
  • Resume lets the rule start agents and bring new versions again.
  • Edit opens the rule's choices, and The command to run.
  • Delete removes the rule. What happens to its agents depends on When an instruction leaves this place. With Stop its agent, its agents stop. With Keep its agent running, they keep running at their version. Either way, no new agents start, and the instructions stay as they are.

Stop an agent

Who can do this: the organization's owners and admins.

In Settings ▸ Deployments, choose Stop on the agent, then confirm. The agent stops on its machine and is stopped for good. To run it again, deploy it again.

When the agent belongs to a rule, its instruction is left out of the rule from then on, so the rule doesn't start it again. To put it back, open the rule's Edit and tick the instruction again in the preview.

If it doesn't work

What you see Why What to do
Deploying an instruction comes with the Pro plan Your plan doesn't include deployments. Choose See the plans. See Plans and billing.
Running every instruction of a place comes with the Team plan Your plan doesn't include rules. Choose See the plans, or deploy instructions one at a time.
Only the organization's owners and admins run every instruction of a place You aren't an owner or an admin. Ask one of them to make the rule.
Publish it first: an agent runs a released version. The instruction has no published version yet. Publish it, then choose Deploy to… again.
Use letters, digits, - and _ in the name of where they run (up to 40) The machine's name has spaces or other characters. Use a short name such as support-server.
No agents yet under a rule Nobody has run the command on the machine yet. Open the rule's Edit ▸ The command to run, and run it on the machine.
Needs sign-in A tool the agent uses isn't signed in on its machine. Run what the line under the agent says, on that machine.
Still stuck Something isn't working, or ask us.

Questions

How do I run an agent for every instruction in a project, and which plan do I need?

Make a rule: open the ⋯ menu of the project, choose Run every instruction here on…, and run the command it gives on your machine. Rules come with the plans shown in Run every instruction in a project or a folder. Only the organization's owners and admins can make one.

Does an agent get a new version by itself?

Yes, if its rule says Each agent takes it at its next turn or Restart each agent with it. With Wait for an owner's or an admin's approval, the new version waits in Settings ▸ Deployments until someone approves it. See The choices in a rule.

Can an agent run my draft?

No. An agent always runs a published version. Publish the instruction first, and the agent takes it the way its rule says.

What happens to the agents if I pause a rule?

They keep running the version they have. Nothing new starts, and no new version reaches them, until you choose Resume.

I stopped an agent. Why doesn't the rule start it again?

Stopping an agent by hand leaves its instruction out of the rule, so the rule doesn't undo your choice. Open the rule's Edit and tick the instruction again in the preview to put it back.

Last checked against the product:

Was this page helpful? Report a problem