Remote Agents
Start a task on your laptop, and let Archestra finish it. Your coding agent hands the task to a Remote Agent in Archestra, with your repository changes and context. The task keeps running after you close the laptop. When it is done, your coding agent brings the result back as a patch.
With a dedicated runtime, the task runs in its own container, with a live terminal you can watch.
Start With Connect
You need Agent Runtime set up on the deployment. Connect adds instructions to your local agent's system prompt. By default, they tell it to offer “move this to Archestra Remote Agents” once per session and load the Remote Agents Handoff skill when you ask. The suggestion uses your deployment’s configured name. The prompt makes the agent aware of handoff; the skill supplies the transfer procedure.
- Connect your local client with the MCP Gateway and shared skills enabled.
- Start a new client session. Claude Code, Codex, Copilot CLI, OpenCode, and Kilo Code receive updated instructions on their next launch. Older connections need setup run once to install instruction refreshing; Unix wrappers require Python 3. Cursor and Claude Desktop need setup updated. Clients keep the last fetched instructions during an outage.
- Ask to “move this to Archestra Remote Agents”. The client loads the skill, chooses an accessible agent with a runtime, and prepares your task context and files.
To change the suggestion, use Settings → Connect Page → Instructions for connected agents, with organizationSettings:update. Turning it off removes this prompt guidance; you can still ask explicitly for the handoff skill.
Hand Off a Task
The skill transfers a starting point the remote agent can actually use, including repository changes that exist only on your laptop.
- Let your local agent inspect staged, unstaged, and untracked changes, and select the files needed for the task. It supplies the repository, exact base commit, changes, goal, and acceptance criteria; a local path alone is not a transfer.
- The client starts a remote session and transfers the selected files. Follow-up instructions reuse that session instead of starting another one. Open its run link to check progress and the live terminal.
- To continue locally, ask to “bring it back and continue here”. The client coordinates a stopping point and retrieves the result and continuation notes before workspace retention expires.
- Review the returned patch against your current local changes. The client checks applicability, reports conflicts, and runs the relevant local checks after applying it.
Processes, installed dependencies, and databases do not transfer automatically. Keep secrets out of ordinary file transfers; use the agent's saved credentials or the credential transfer flow. Missing tools or an expired workspace must be resolved before the handoff can continue.
What Your Agent Uses
The skill drives these tools on the MCP Gateway. You can also call them yourself.
- Find an agent:
list_.agents - Start a run:
start_. It returns aagent_ run run_and a link to the run page. The other tools take thatid run_.id - Check progress:
get_, oragent_ run list_withagent_ runs mine_for your own runs.only - Change course:
steer_oragent_ run cancel_. Steering a finished run starts a new turn with the same files.agent_ run - Read or write files without starting a turn:
read_andworkspace_ file write_.workspace_ file
Only the person who started a run can steer it or use its files.
Hand Off With Guardrails On
With Guardrails on, a run keeps the restrictions of the session that started it, when Guardrails check that session. They check it when your coding agent is connected as a Guardrails client: its model requests go through the LLM Proxy.
- A client Guardrails check: the run starts under your session's restrictions. Its answer passes the guardrail check before your agent reads it. Another session cannot steer the run or read its files.
- Any other client: the Unrecognized clients setting decides. When it is Allowed, the run starts without your session's restrictions, and Guardrails still check each tool call inside it. When it is Blocked, the run does not start.
A file you read or download while the run is in the middle of a tool call comes back as pending. Guardrails pin that version and release it once the tool call finishes, so call the same tool again a little later.
If a request is refused:
- "OpenAPPA does not recognize this client": unrecognized clients are blocked. Connect the client so that Guardrails check it. Or allow unrecognized clients, which needs
organizationSettings:update. - "This runtime is bound to a different session": another session started the run. Continue it from that session.
- "This runtime is bound to a Guardrails session, and this call carried no proof of its source": the call reached Archestra without the proof the LLM Proxy attaches to a model's runtime tool calls. A script or a client whose model requests skip the LLM Proxy gets this. Make the call as a tool call from the run's own conversation or from the one that started it. If the client is not connected, connect it. Once a yell turns Guardrails off for the run's session or the session that started it (the Yell tool setting under Break the glass), its calls need no proof.
- "The protected file could not be admitted": Guardrails held the file's bytes from your session. The ruling after the message says why and names any plan that lets them through.
Pass a Credential
Your agent can give the run a credential, such as a GitHub token, with transfer_. It reaches the container on the next turn and serves only your runs.
What to know:
- The value passes through your agent's model and transcript. A secret that must never reach a model belongs in the agent's Environment variables instead.
- To refuse transfers, turn off Accept credentials from a connected client on the agent.
- Claude Code's auto mode can block the transfer before it reaches Archestra. Connect adds the allow rule that prevents this. If you added the gateway another way, add the rule in
/permissions.