Documentation

Coding agents on your own machine

Run the roles of your AI profile on a coding agent on the machine of whoever starts the task, with CoRoid's tools and nothing of the machine.

A role of your AI profile can run on a coding agent on your own machine instead of a model CoRoid calls. The agent does the role's reasoning there, signed in as you set it up, on your own account with its provider. CoRoid gives it the role's tools and keeps everything else of the workflow: the task, the checks and gates, the record of what happened.

What it covers

  • Every role of a profile but the Decision engine: the Architect and the Coordinator, the Developer, QA, the Reviewer, the web tester, the translator and the others. The Decision engine is not an agent run: it asks a decisions model for a probability of each allowed answer, which a coding agent does not give.
  • Four agents: Codex and OpenCode, and for some organisations only, for now, Claude Code and Cursor. Each runs under your own plan with its provider (see Your agent's plan).
  • Every way a task runs. In Coordinator mode, the Coordinator and the children it hands work to run on the agent like any other role.

Your agent's plan

The agent works under your own sign-in and on your own plan with its provider: Anthropic for Claude Code, OpenAI for Codex, Cursor for Cursor, and whichever providers you set up in OpenCode. CoRoid never sees that sign-in, and it does not resell or share anyone's plan: each person connects their own machine, and the agent does work they started.

Whether a plan's terms allow using it through another product, and for which work, is between you and the provider. It differs between providers, and between their personal and business plans, may depend on how much work goes through it, and can change. Read the terms of your plan, and ask the provider when they do not settle it.

An organisation that assigns roles to agents should check the same for its people's plans. Its policy can allow only the agents whose terms it has checked (see What your organisation allows).

How it connects

Your machine

CoRoid connector

Open source. Starts the agent for a turn in a new, empty directory and stops it after.

Your coding agent

The agent you use, signed in as you, with its own tools switched off.

  1. 1Asks for work. Each request is held up to 25 seconds; the connector reports what the agent says every 3 seconds.
  2. 2Calls the role's tools. With a token for this turn only, which stops working when the turn ends.
  3. 3Asks its model. As it would without CoRoid. CoRoid never sees that sign-in.

CoRoid

Orchestrator

Hands out a role's work to the machine of the person who started the task (1).

The role's tools

Run in the task's sandbox, where your code stays (2).

The agent's provider

Answers the agent's model requests under your own sign-in, on your plan (3).

Nothing reaches into the machine: the connector opens no port, sends none of its files and runs no command of its own.

On the machine stay your sign-in to the agent and whatever the agent itself keeps of a turn.

Every connection starts on the machine and goes out over HTTPS. The repository stays in the task's sandbox in CoRoid; the agent works on it only through the role's tools.

The machine works for CoRoid through the CoRoid connector, a small open-source program you install and run. Every connection starts on the machine: the connector asks CoRoid for work, the agent calls the role's tools in the task's sandbox, and the agent asks its own provider for its model's answers, under your sign-in. The connector opens no port and sends none of the machine's files. The connector's security covers what it does and does not do, and how to check a release.

Connect a machine

  1. Install the agent on the machine and sign in to it, as you would to use it yourself.

  2. Install the connector, with Homebrew on macOS or Linux:

    brew install coroid-ai/tap/coroid-connector

    or with npm, anywhere with Node.js 20 or newer:

    npm install --global @coroid/connector
  3. For Codex or Claude Code, add the agent: coroid-connector add codex (or add claude). This installs the agent's ACP adapter, which brings its own copy of the agent (about 350 MB), into ~/.coroid/connector, from the packages that connector release locks by hash. OpenCode and Cursor need no adding: CoRoid uses your own installation.

  4. Open Settings → Connections → Your machines and run the command shown there (coroid-connector --api …). Your browser opens: approve the machine for your organisation. Approve only a connector you started a moment ago.

The connector then keeps running until you stop it, asking CoRoid for work. Your machines lists the machine as connected, with the agents the connector found on it and the version of each. An agent shows as ready only on a version CoRoid has tried; on another version it is shown and not used.

coroid-connector status shows the same from the machine, with the model each agent is set to.

Only you see your machines. Disconnect ends the machine's sign-in, and its connector stops within a minute.

Assign a role to an agent

An organisation owner does this in a custom profile, under Settings → AI profile (see AI profiles).

  1. Open the profile's details. In the first field of a role, the list starts with On your own machine: the agents your organisation is offered, and beside each whether a machine of yours has it ready.
  2. Choose the agent. Two more fields appear:
    • Model in : the model the agent is to use for this role, from the models your connected machines report for it. As set on the machine leaves the agent on the model its owner has set in it.
    • Without a connected machine: the model that runs the role when no machine takes the work. It is the model the role had.
  3. Save.

Choosing a model in the first field again takes the agent away, and the model named for it with it.

What happens when a task runs

The assignment is the organisation's; the machine is the person's. When a role starts, CoRoid looks for a machine of the person who started the task:

  • connected in this organisation in the last minute,
  • with the assigned agent ready on a version CoRoid has tried,
  • and offering the named model, if the assignment names one.

If there is one, the role's work goes to that machine. If not, the role runs on the model under Without a connected machine, exactly as it would have. Nothing waits for a machine. Work nobody started (an automation on an event, a schedule) has no such machine and runs on its model.

On the machine, the connector starts the agent in a new, empty directory and gives its session one set of tools: CoRoid's tools for this role, reachable for this piece of work only. The Developer changes the code through them, in the task's workspace in CoRoid, as a model does; QA and the Reviewer judge that change through them. A message added to the task while the agent works reaches it with its next tool result.

A role that waits goes back to the agent. The Coordinator hands work to the Developer, QA and the Reviewer and waits for each; a child may wait for the Coordinator's answer. When the wait is over, the role goes back to the agent, which is given the conversation so far. A machine runs up to four roles at once (connector 0.4.0), so the explorers the Developer starts run beside it.

If the machine stops answering in the middle of a role, the role goes on in the same conversation on its cloud model, which is told what happened. A task that is stopped stops the agent too. When a role is over, its agent is stopped and the directory removed.

What stays on your machine

The connector removes the directory a role ran in. What the agent keeps of the work in its own storage depends on the agent:

AgentWhat it keeps
Claude CodeNo transcript: the connector starts it with session persistence off
CodexA transcript of each session in ~/.codex/sessions, including the files it read
OpenCodeIts sessions in its own database under ~/.local/share/opencode
CursorEach session in its own database under ~/.cursor/acp-sessions

Codex, OpenCode and Cursor offer no switch for this today. If your organisation must keep code off laptops, allow only Claude Code in its policy (see below).

What your organisation allows

An owner or admin decides in Settings → Identity and access → Org policy, under Coding agents on people's machines, on every plan:

  • Allow coding agents on people's machines. When it is off, every role runs on its model, also a role a profile already assigns to an agent.
  • One switch per agent your organisation is offered, beside what that agent keeps on the machine. With every agent on, an agent CoRoid offers later is on too.

The AI profile form offers only the agents the policy allows, and a role cannot be newly assigned to another. A role assigned before the policy changed keeps its assignment, and the form says that it runs on its model. A project's policy can narrow the organisation's, never widen it.

What the agent can and cannot do

  • Only CoRoid's tools. Each agent's own tools (its shell, file editing, web search, its own MCP servers and connectors) are switched off for the session, in the way that agent provides. A request to use anything else is refused.
  • Nothing of the machine. The agent does not work in your checkout and gets no files of the machine. CoRoid gets no access to the machine either: the connector only asks CoRoid for work and reports what the agent says.
  • The same checks. What the agent changes goes through the same QA, review, gates and step limits as a model's work.
  • What is sent. What the role needs (the code it reads, the requirements, the results of its tools, an attachment's images) goes to the machine, and from there to the agent's provider under the sign-in the agent has there. If your organisation must keep code with particular providers, take that into account before you assign a role to an agent.

Cost and records

The agent's reasoning is on the account of the person whose machine did the work, not on CoRoid's model spend. A task's activity shows such a run as, for example, Codex (gpt-6-luna) on Ada's laptop · not metered, never as zero tokens. If a role went on on its cloud model, that part is metered as usual.

CoRoid records each piece of work it handed to a machine: which machine and agent, the model named, how it ended and how many tool calls it made.

Export and import

An assignment's agent and its model travel with the profile in a settings export, and the policy's choice of agents travels with the org policy. An organisation that does not have local agents, is not offered that agent, or whose policy does not allow it, imports the assignment with its cloud model alone, and the import says so. See Export and import settings.