> ## Documentation Index
> Fetch the complete documentation index at: https://docs.harborframework.com/llms.txt
> Use this file to discover all available pages before exploring further.
# ASP
> Agent Sandbox Protocol: run any agent harness's tools in a remote sandbox over SSH.
This page is an RFC draft. Comments are welcome on
[PR #3023](https://github.com/harbor-framework/harbor/pull/3023).
Initially proposed by and codesigned with [@alexgshaw](https://github.com/alexgshaw)
## TL;DR
* ASP lets any agent harness execute its tools in a remote sandbox through
.asp.json; **SSH** is the first transport because it already provides
command execution, file transfer, and authentication that every
sandbox can expose.
* An agent implementing ASP **does not realize** it operates on a remote
machine: all of its tools execute in the sandbox, so the sandbox is the
only environment it can observe.
* Agent tools have two layers, a model-facing policy layer (schemas,
truncation, pagination) and a mechanism layer doing raw I/O; ASP swaps
only the mechanism from local I/O to I/O over the network, and the policy
layer remains unchanged.
* To support ASP, an existing agent only needs two additions: detect
`.asp.json`, and route its tools' raw I/O (read, write, exec) through the
configured transport instead of the local machine.
## Goal
*Decouple the brain from the hands!* Standardize the interface between an agent harness (the **brain**: agent loop,
LLM calls, credentials) and the sandbox where its tools execute (the **hands**:
filesystem, shell). Any harness should drive any sandbox through one
declarative config file and a standard transport, with no provider SDK in
the harness.
## Background
Coding agents are ubiquitous, and non-coding agents increasingly rely on
execution environments too. Yet most agents run in the **same environment** they
execute code in. In low-trust or cloud settings the two are better
**separated**, as argued in
[Vercel's post on security boundaries in agentic architectures](https://vercel.com/blog/security-boundaries-in-agentic-architectures):
credentials and host information stay out of the agent's reach, the agent
cannot OOM or kill its own runtime, and infrastructure can be tuned per
side, for example disabling internet in the sandbox while the runtime keeps
connectivity.
Today only an agent's own developers can make that split, by rewriting its
execution tools to route into a sandbox. Everyone building on top of an
existing agent (Claude Code, Codex, pi) inherits its tools and cannot
decouple. Shared environments hurt
reproducibility, and sandbox internet access is a major reward-hacking
channel, yet cutting it is impossible while the agent runs inside the
sandbox, so developers fall back to brittle allowlists of model endpoints.
[Anthropic's managed agents](https://www.anthropic.com/engineering/managed-agents)
decomposes an agent system into session, orchestration, harness, sandbox,
resources, and tools, and achieves the split by installing an environment
worker inside the sandbox, which couples the sandbox to that harness.
Provider SDK integrations do the reverse and couple the harness to one
provider.
On the other hand, [SSH](https://en.wikipedia.org/wiki/Secure_Shell) already implements the primitives the missing interface needs. It can run commands, transfer files through SFTP, and handle authentication and host verification. Many sandbox providers are already reachable over SSH or can be configured that way. What’s missing is a shared convention for telling a harness to run its tools remotely and describing how to connect. **ASP provides that convention.**
## Scope
Measured against the managed-agents component table, ASP is **deliberately
niche**. It standardizes only the harness-to-sandbox edge, and within that
component's interface only `execute(name, input) -> String`.
The
`provision({resources})` half is explicitly **out of scope**, provisioning is
the orchestrator's job (e.g. [harbor](https://github.com/harbor-framework/harbor)), done before the agent starts by
tooling such as
[daytona\_setup.py](https://github.com/kobe0938/harbor/blob/asp/asp/daytona_setup.py)
and
[docker\_setup.py](https://github.com/kobe0938/harbor/blob/asp/asp/docker_setup.py),
and the agent must not have the freedom to provision at runtime. Sessions,
orchestration, resources, and tool definitions remain whatever the harness
already does.
*ASP adopts execute and deliberately excludes provision.*
## The contract: .asp.json
Check full definition at
[asp.schema.json](https://github.com/kobe0938/harbor/blob/asp/asp/asp.schema.json).
Examples:
[daytona](https://github.com/kobe0938/harbor/blob/asp/asp/examples/daytona/.asp.json) and
[docker](https://github.com/kobe0938/harbor/blob/asp/asp/examples/docker/.asp.json).
| Field | Meaning |
| - | - |
| `version` | `"0"` |
| `transport` | `"ssh"` (the first supported transport; the field exists so more can be added) |
| `connection.host`, `.port`, `.user` | SSH endpoint; providers may encode an access token as the username |
| `connection.identity` | client private key, by env var name or file path; omitted when token auth suffices |
| `connection.host_key` | pinned server public key; omitted means trust-on-first-use |
| `workspace` | absolute sandbox path that relative tool paths resolve against |
A harness that finds `.asp.json` (working directory, then parents) binds its
tool I/O to the sandbox. Tool calls are **stateless**, fresh shell per command,
persistent filesystem.
The agent is **unaware** of any of this. It is not told about the transport, and
it could not act on the knowledge anyway: all of its tools execute remotely,
so it has no verb that reaches the harness machine and no way to inspect the
environment the harness runs in. The only environment it can observe is the
sandbox itself. The boundary is enforced by capability, not by policy or
prompt.
### Architecture
An agent's tools split into two layers.
The policy layer is model-facing:
the tool schema (path, offset, limit), truncation limits, pagination.
The
mechanism layer is a small seam of raw I/O functions underneath (read,
write, exec).
ASP swaps only the mechanism, local I/O becomes the same I/O
over the transport; the policy layer runs unchanged in the harness, so the
model sees identical tool behavior and existing prompts and evals carry
over.
## Two Agent ASP examples
* [A vanilla Python agent](https://github.com/kobe0938/harbor/blob/asp/asp/agent.py) with the asyncssh SDK
* [An extension](https://github.com/kobe0938/harbor/blob/asp/asp/pi-asp.ts) for a minimal harness called [pi](https://github.com/earendil-works/pi)
*The vanilla agent running in Daytona with ASP*
## Internet configurability
ASP composes cleanly with sandboxes whose internet is turned off. SSH is ingress: a stateful firewall
admits replies on connections the harness initiated while dropping every
connection the sandbox starts, so tools keep working with all egress dead
(verified on Daytona and Docker).
## Future steps
Soon, we are planning to add terminus-slim, an ASP-based version of [Terminus](https://github.com/harbor-framework/terminal-bench-1/blob/main/terminal_bench/agents/terminus_1.py). ASP v0 begins with SSH, but the format can later support transports such as stdio and HTTP. In the future, a more opinionated version could define transport-independent operations and types for **generating SDKs**.
This is a v0 draft so everything here, including the schema, is **subject to change** in v0.1 or v1. **Comments are welcome!**.
## Appendix for support matrix
SSH SDKs
| Language | Library | Notes | Verified in this MVP |
| - | - | - | - |
| Python | [asyncssh](https://github.com/ronf/asyncssh) | async, clean SFTP support | [yes](https://github.com/kobe0938/harbor/blob/asp/asp/agent.py) |
| Python | [paramiko](https://github.com/paramiko/paramiko) | synchronous, mature | no |
| TypeScript | [ssh2](https://github.com/mscdex/ssh2) | the standard Node library; [ssh2-sftp-client](https://github.com/theophilusx/ssh2-sftp-client) adds promise SFTP | no |
| TypeScript | [node-ssh](https://github.com/steelbrain/node-ssh) | promise wrapper over ssh2 | no |
| Go | [ssh](https://pkg.go.dev/golang.org/x/crypto/ssh) | official extended stdlib | no |
| Rust | [russh](https://github.com/Eugeny/russh) | async (tokio), includes SFTP | no |
| any | [OpenSSH client](https://www.openssh.com/) | no dependency; ControlMaster multiplexing | [yes](https://github.com/kobe0938/harbor/blob/asp/asp/pi-asp.ts) |
Sandbox providers
| Provider | Notes | Verified in this MVP |
| - | - | - |
| Docker | sshd in container, published port | [yes](https://github.com/kobe0938/harbor/blob/asp/asp/examples/docker/.asp.json), incl. egress block |
| Apple Container | sshd in container, routable VM IP | yes |
| Daytona | managed gateway, token as username | [yes](https://github.com/kobe0938/harbor/blob/asp/asp/examples/daytona/.asp.json), incl. SFTP and `network_block_all` |
| E2B | documented, via websocat ProxyCommand over WSS, custom template | no; needs a `proxyCommand` field |
| Modal | no native SSH endpoint; sshd plus Modal tunnel should work | no |
| GKE | no native SSH endpoint; sshd in pod plus port-forward | no |
## References
* [https://www.daytona.io/docs/en/guides/claude/claude-managed-agents/](https://www.daytona.io/docs/en/guides/claude/claude-managed-agents/)
* [https://www.daytona.io/docs/en/guides/pi/pi-extension/](https://www.daytona.io/docs/en/guides/pi/pi-extension/)
* [https://www.anthropic.com/engineering/managed-agents](https://www.anthropic.com/engineering/managed-agents)
* [https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#how-it-differs-from-cloud-environments](https://platform.claude.com/docs/en/managed-agents/self-hosted-sandboxes#how-it-differs-from-cloud-environments)
* [https://agentclientprotocol.com/protocol/v1/terminals#checking-support](https://agentclientprotocol.com/protocol/v1/terminals#checking-support)
* [https://modelcontextprotocol.io/examples](https://modelcontextprotocol.io/examples)
* [https://github.com/daytona/integrations/blob/main/packages/pi-extension/src/ops.ts](https://github.com/daytona/integrations/blob/main/packages/pi-extension/src/ops.ts)
* [https://opencode.ai/docs/tools/](https://opencode.ai/docs/tools/)
* [https://github.com/earendil-works/pi/blob/main/packages/coding-agent/examples/extensions/ssh.ts](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/examples/extensions/ssh.ts)
* [https://vercel.com/blog/security-boundaries-in-agentic-architectures](https://vercel.com/blog/security-boundaries-in-agentic-architectures)
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.