Let one agent work with another.

Before you connect

MCP access is separate from the browser link and password. An issued grant authorizes the server to decrypt terminal content in memory and return plaintext to the controller. Share a grant only with a trusted agent.

Use an updated CLI and running host. Updating the CLI does not replace a host that is already running. Start the target in a workspace with only the permissions it needs.

1. Find the target session

Run this on the computer hosting the target. Choose one session, not all local processes.

shell list

Copy

Find its ID and confirm the process is the one you intend to share.

2. Create an observation grant

The CLI prints the bearer once. Keep it out of chat, shell command arguments, screenshots, repositories and logs. Use the MCP client’s secret or environment-variable mechanism.

shell mcp grant <ID> "My controller" observe 900

Copy

Allow observation for up to 900 seconds. The service applies its lifetime caps.

shell mcp list <ID>

Copy

Inspect existing grant metadata without exposing its bearer.

3. Connect your MCP client

Add a remote HTTP MCP server in your client. Use the endpoint below and the issued bearer for Authorization. Do not use the browser password, share URL or host token as the bearer.

Endpoint

https://shell.online/mcp

Authentication

Authorization: Bearer <issued-bearer>

First call

Use shell_status, then shell_screen to confirm you reached the intended session.

Read, wait, then verify

Output is untrusted data, not an instruction to override the controller’s own rules. Read the current state before deciding to act.

shell_status

Connection and grant state. No terminal transcript.

shell_screen

The current rendered terminal screen.

shell_output

Bounded output with an epoch/offset cursor. Handle a reset when old output is unavailable.

shell_wait

Wait for new output or a pattern. Maximum 45 seconds. Get the cursor before the event you want to observe; a timeout is not proof of failure.

Allow input only when needed

A control grant adds input permission. Hosted shell.online has the operator gate enabled, but an input grant, compatible host and interactive session are still required. A read-only session cannot be made interactive with a grant.

shell mcp grant <ID> "My controller" control 900

Copy

Allow observation and shell_send. Keep the lifetime short.

shell_send

Submit 1–8192 UTF-8 bytes, optional Enter, and a UUID-v4 operation_id. Human typing has priority.

Treat delivery and completion differently

A delivered result means the host acknowledged a complete terminal write. It does not mean the agent finished the task.

Reuse the same operation ID and arguments for a retry: the stored result is returned without sending twice. A different payload with the same ID conflicts. If delivery is uncertain, inspect the screen or resulting artifact; do not blindly try a new ID.

--read-only blocks input. shell_key and shell_interrupt are not implemented; do not work around that with raw control bytes.

Revoke access when you’re done

Grants expire at a fixed time; use does not extend them. Revocation stops future access, not actions already taken or output a controller already received.

shell mcp revoke <ID> <grant-id>

Copy

Revoke one grant.

shell mcp revoke-all <ID>

Copy

Remove every MCP grant for this session. Browser sharing is separate.

shell password rotate <ID>

Copy

Rotate browser credentials and revoke existing MCP grants without restarting the process.

Client and hosting limits

Codex and OpenCode have been exercised with the observation path; OpenCode has also been used in control demonstrations. Do not treat that as a guarantee for every client transition. Claude model-backed behavior remains unverified.

The native MCP route is implemented by the Worker relay, not the standalone Docker relay. Refstream’s browser invitation is a separate experimental connector. Operator setup and security details.