Skip to the content.

Remote Sandbox Guide

core/sandbox-remote runs a sandbox.Runner across a process or host boundary. The client is a sandbox.Runner whose processes execute on the server; the server is a thin adapter over any other runner.

Nothing above the client changes. The tool set, the approval chain and the escalation path see the interface they see for a local backend, because the client is a proxy rather than a second implementation.

// The server: one runner, built by whoever starts it.
inner := local.New(root)                     // or bwrap, seatbelt, windows
server, err := remote.NewServer(inner, remote.WithServerToken(token))
http.ListenAndServe(":8443", server)

// The client: a Runner, decorated exactly like a local one.
runner, err := remote.New(ctx, "https://sandbox.internal:8443",
    remote.WithToken(token))
composed := engine.ComposeLocal(runner, policy)

One server exposes one runner. It is not a scheduler and holds no fleet: the server carries sessions over the wire and keeps the handles it needs to answer by id.

Deployment

sandbox:
  backend: remote
  remote:
    transport: http # http (default) | unix
    endpoint: https://sandbox.internal:8443
    token: "${SANDBOX_TOKEN}"
    timeout: 30s # per request; zero uses the client default
    poll_hold: 15s # how long a read or wait asks the server to hold
    insecure_skip_verify: false
Field Rule
transport http (aliases https, tcp) or unix (alias socket).
endpoint Required for http, must be http(s); rejected with unix.
socket Required for unix; rejected with http.
token Bearer credential. Optional over a unix socket, where the boundary is the directory's permissions.
timeout Per-request deadline.
poll_hold How long a read or a wait asks the server to hold before answering "nothing yet". Must stay under any proxy's idle timeout.
insecure_skip_verify Only meaningful over TLS; rejected with unix, which carries none.

The field a transport does not use is a validation error, not a comment: a socket path beside an endpoint is configuration that silently does nothing.

Files do not cross. The built-in file tools work on a local fsx tree, so a deployment that puts commands on a remote host needs that host's filesystem mounted where the tools run, or those tools turned off — which is why the runtime warns when tools.files is enabled with backend: remote. This package moves the process boundary only.

What crosses, and what does not

Session ids are opaque and minted by the server. The client never parses one, and their width is the server's business — which leaves room for an instance layer (one sandbox per session) without changing paths later.

Output is a cursor, not a stream. A read carries after_seq and answers with a sequence range, so a dropped connection is cheap: a reconnecting client re-reads from its last cursor instead of losing what it missed. That is also why the transport can stay request/response.

One operation pushes. The session event stream is carried as Server-Sent Events on POST /v1/events. It needs no resume cursor of its own: the contract's Watch replays the retained log before following live, and a consumer that fell behind recovers with a Read from the sequence its lag event names. A slow consumer loses no frames — the client buffers between the socket and the channel — which the conformance suite checks by stalling one.

Capabilities are forwarded, never edited

The client reports the server's declaration verbatim. A capability the far end does not claim is one this client does not claim either, and one it does claim has to work — the conformance suite checks both directions of every advertised feature, including the rule that a backend declaring Events must really deliver the terminal status.

The server re-validates what arrives and can only narrow it. Policy stays on the client side of the wire; the caller is not the authority on what the far end can enforce.

Security

The server refuses to be built without an authentication decision: either a bearer token (WithServerToken) or an explicit WithoutAuth() for a listener that already sits behind an authenticator.

Transport Boundary
http Bearer token in the Authorization header, never in a query string — query strings end up in proxy logs. TLS is the deployment's job (remote.WithHTTPOptions(remote.WithHTTPTLS(...))).
unix The socket's directory. ListenUnix creates the parent 0700 and the socket 0600, and a token is optional.

The socket path is bounded (maxUnixPathBytes = 100, under UNIX_PATH_MAX of 108 on Windows and 104 on macOS), and the check happens before the listen so a too-long path is a clear error rather than a truncated one.

A unix socket is not automatically "local" on Windows: there os.Chmod only sets a read-only attribute, so the directory ACL is the real boundary — which is why the token stays meaningful there.

Failure semantics

// An operation that is safe to repeat is retried after a transport failure.
// defaultRetries = 3, backoff 20ms / 100ms / 500ms with ≤20% jitter,
// retryBudget = 620ms — a caller that needs a tighter bound sets its own context.

Wire

core/sandbox-remote/wire is the DTO layer: version 1, one route per operation, and an error envelope that carries errdefs.Kind so the client rebuilds the same error class (NotFound, NotAvailable, Cancelled, …) instead of flattening everything into one status.

Route Operation
POST /v1/hello Version handshake; a mismatch fails the client before any session.
POST /v1/start, /attach, /list, /terminate, /close Session lifecycle.
POST /v1/read, /write, /close-input, /resize, /signal, /wait Session I/O, all addressed by opaque id.
POST /v1/journal Journal read, carrying the cursor.
POST /v1/events The SSE stream above.

Two operations are binary, not JSON:

The magic prefixes exist so "this is not our frame" is decidable rather than guessed at. There is no negotiation: the content type of a request says which frame it is, and an unknown body is a decode error naming the version.

Measured cost

On an 8-core laptop with the loopback transport, the remote path costs about 17% over the local one for a small echo (2.40 ms vs 2.17 ms), and a 1 MiB drain moves at ~1569 MB/s with a 256 KiB read window. The window matters: at 64 KiB, a megabyte cost sixteen round trips instead of four, which measured ~30% off a 1 MiB Exec. A single-window stall is a network problem, not a wire problem — on the same machine it is cheaper to widen the window than to change the transport.

See sandbox.md for the contract every backend implements, and runtime.md for how sandbox.remote is validated at build time.