The sandbox and its gateway

Sandbox sessions give your AI agent a private computer in Sydney, and the agent can reach only the internet addresses that you list. You pay by the second from prepaid credit.

The first minute of a session takes a minimum of A$5.00. The first hour of a 2 vCPU session is free, once for each verified card and phone number. You allow the agent to reach the addresses that you list and to use the credentials that you attach.

A sandbox session runs your agent (Claude Code, Codex or any MCP client), or the commands that you send, on one fresh Graviton instance. That instance serves the session alone. The gateway, which TALOS Defence operates, is the only way out of the session. Your account's policy can require a named person to approve each consequential action on their phone. Every session ends with a job certificate.

The isolation statement

Every session certificate contains this statement, word for word:

One fresh instance served this session alone and was terminated at its end. AWS Nitro is the isolation boundary. The gateway, operated by TALOS Defence, was the session's only way out: it connected only to the destinations named on this certificate and attached credentials by name, so no credential entered the session. Companion containers ran inside the session's own instance and budget, with no inbound access. The sandbox reset is recorded step by step with each AWS response.

Starting a session

hangar sandbox start --shape c --vcpus 2 \
  --allow api.anthropic.com --allow api.github.com \
  --attach GITHUB_TOKEN=api.github.com:authorization:Bearer \
  -- claude -p "fix the failing test"

Worked examples

Each row is a whole session. Hangar charges every minute as the minute starts, then trues up at the end. A session pays at least A$5.00, charged once with the first minute. A session with the first hour free has no minimum. The meter in the instance and the ledger in the control plane are both tested against this table.

A session has 2, 4, 8 or 16 vCPUs. Hangar meters compute by the second while the session's instance runs. The meter starts when the instance is running. The meter stops when the session pauses or ends, and starts again at each resume.

Hangar takes the charge from your prepaid credit one minute at a time, as each minute starts. The first minute takes the A$5.00 minimum. The minutes after the first take nothing until the use passes the minimum. At the end, the true-up returns the part of the last minute that the session did not use.

A session starts with credit for its first ten minutes, the minimum included. The first hour of a 2 vCPU session is free, once for each verified card and phone number.

A session ends by itself when its credit reaches the last minute. You can also set a hard stop with stop_after_seconds, from one hour to seven days of compute. Hangar bills no second after the hard stop.

Commands sent by your organisation, or by a session token, enter the session. Each command has an id and is listed on the session certificate. A session has no interactive shell, no SSH and no console. TALOS Defence operators cannot send a command to a session. hangar sandbox status <id> --logs returns the agent's own output.

Commands and streaming

hangar sandbox exec <id> -- <program> <arguments> sends one command to a session. POST /v1/sandboxes/{id}/commands does the same through the API. Each command has its own id and its own number in the session, from 1. Up to 16 commands run at once in one session, and each command streams its own output.

A command's output is one stream of bytes, numbered by offset from 0. Each chunk is marked stdout or stderr. GET /v1/sandboxes/{id}/commands/{cid}/output?after=<offset>&wait=25 returns the output past that offset. It answers as soon as there is some output, or after 25 seconds.

The CLI prints stdout chunks to its standard output and stderr chunks to its standard error. The CLI exits with the command's exit code. The worker keeps output that Hangar has not yet acknowledged and sends that output again. A lost reply therefore loses no byte and duplicates none. A command that makes output faster than the worker can deliver it waits until delivery catches up.

Each command that the session ran is a job on the session certificate. Its job id is <session id>/cmd/<number>, and the certificate shows its outcome. The page Sandbox sessions sets out each command status.

Reattaching

A client that drops loses nothing. The commands keep running, and Hangar keeps their output by offset. hangar sandbox attach <id> reattaches by session id. It reads each command's state from GET /v1/sandboxes/{id}/attach. It resumes each command from the last offset that the client acknowledged, so Hangar replays the gap. Ctrl-C ends the CLI and leaves the command running. Run hangar sandbox attach again to pick the command up.

Attaching to a session that has ended returns the session's final state and each command's outcome. Attaching never starts a session.

Idle, pause and resume

A session in mode commands is idle when no command runs and no client has attached in the last 30 seconds. After the idle timeout, the session ends. If you set --idle pause, the session pauses instead. The idle timeout is 15 minutes unless you set --idle-timeout from 1 minute to 24 hours.

A session in mode agent runs its agent until the agent exits, and then ends. That mode has no idle timeout and cannot pause.

hangar sandbox pause <id> stops the session's instance. These things happen:

• The workspace stays on the session's own volume. The volume is encrypted under a key that Hangar makes for the session and seals under your organisation's key.
• Running commands end, and no process survives the pause.
• The instance's credential for Hangar ends. The gateway's certificate authority for the session ends. The attached values end.
• Pending approvals are withdrawn.
• Session tokens stay valid until they expire or you revoke them.

hangar sandbox resume <id> starts the same instance again with the workspace as the workspace was. The session's authority does not come back as it was:

• The instance proves what it is again.
• The gateway makes a new certificate authority.
• Hangar reads the allowlist and the attachments again against your account's current policy and secrets.

A destination that you removed from your egress list while the session was paused is absent after resume. A secret that you deleted while the session was paused is also absent. A revoked session token stays revoked. A session stays paused for at most 7 days, and then the session ends.

The page Sandbox sessions sets out, event by event, what happens to files, processes, credentials, policy and billing.

What idle and pause cost

Idle time costs the session's vCPU rate, as running time does, until the idle timeout pauses or ends the session. While a session runs, the vCPU price includes the session's volume.

While a session is paused, Hangar charges no compute. Hangar charges the session's 64 GiB volume at A$0.20 per GiB-month, GST included, with a month of 730 hours. Hangar adds up the paused time across the session and charges it an hour at a time, as each hour starts. Hangar trues up to the second when the session ends.

Templates

--template name@version starts a session from a template instead of your own image. A template is a ready-made session image. Hangar's image pipeline builds each template under a declared build network policy. Hangar records the image digest of the template and the digest of the template's software bill of materials. A template contains no credential and no customer data.

A template is either shared with every organisation or belongs to your organisation. hangar sandbox templates lists the templates that your sessions can start from.

Tenants and session tokens

--tenant <name> names the customer of yours that a session serves. The session's start record shows the tenant, so the session certificate shows the tenant. The session attaches that tenant's secrets.

hangar sandbox token create <id> --scope read,exec --ttl 1h --public-key key.pem makes a session token for that one session. You hand the token to your service or to your customer's client. Hangar shows the token once.

• A session token works only for its own session.
• The token has only the scopes that you choose (read, exec, control).
• The token lasts at most 24 hours.
• A P-256 key binds the token. The client signs every request with the matching private key and sends the signature in the Hangar-Proof header.

A token ends when it expires, when you revoke it with hangar sandbox token revoke, or when its session ends. A retry, a restart or a resume does not bring an ended token back.

Companion containers

A companion is a helper container, such as a database or a cache, that runs beside your agent. --companion db=sha256:<digest>@5432 runs a companion inside the session's own instance, under containerd. The image comes from your registry, by digest.

The instance runs linux/arm64. The agent's image and each companion's image are linux/arm64 images, or multi-platform images with a linux/arm64 entry. The worker on the host fetches each image through presigned URLs, one for each stored object. The containers never reach the store. The page How images are staged sets out each step.

The agent and its companions share one network namespace, so the agent reaches the companion at 127.0.0.1:5432. They also share one budget: the instance's memory and vCPUs, less a small reserve for Hangar's worker.

Companions reach the outside only through the gateway, under the session's allowlist. Companions accept connections from inside the session alone. The session's security group admits nothing. The instance's own rules drop every new connection from outside. The session certificate shows each companion with its image digest.

The gateway

The gateway is a pair of instances in Sydney that TALOS Defence operates. You set what a session may reach and which credentials the session may use. Only TALOS Defence configures the gateway itself, through Hangar's release process. The session's subnet sends all traffic to the gateway. The session's security group lets traffic out to the gateway alone.

Protocols the gateway passes

The gateway passes HTTPS on port 443. It accepts HTTP/1.1 and HTTP/2 from the session. It connects to the destination over HTTP/2 or HTTP/1.1, as the destination chooses. It also passes gRPC, which travels over HTTP/2 end to end with its trailers. The gateway speaks TLS 1.3 to the session and TLS 1.3 to the destination. It checks the destination's certificate against the public certificate authorities.

The certificate authority your session trusts

When a session starts, and again at each resume or recovery, the gateway makes a certificate authority for that session alone. The gateway makes the authority's key in memory, and the key stays in memory. The authority has a name constraint that permits exactly the destinations that the session lists. The authority can vouch for those destinations and for no other. The gateway signs a certificate for each listed destination when the session first connects to that destination.

The session trusts this authority and no other. The worker writes the authority's certificate to /etc/hangar/session-ca.pem in every container. The worker also sets SSL_CERT_FILE, CURL_CA_BUNDLE, REQUESTS_CA_BUNDLE, NODE_EXTRA_CA_CERTS, GRPC_DEFAULT_SSL_ROOTS_FILE_PATH and GIT_SSL_CAINFO to that path.

Hangar records the authority's SHA-384 digest each time the gateway makes an authority. Hangar records the destruction of the authority under the same digest, at the pause, at the interruption or in the reset.

How the gateway checks a destination

A destination is a DNS name, written exactly, such as api.github.com. Each name that you list with --allow must be in your account policy's egress list, which an owner sets. The gateway does these things:

• It answers the session's DNS for a listed name with the gateway's own address. It answers NXDOMAIN for every other name.
• It reads the name that the session asks for in the TLS hello, before any handshake. It passes the connection on only when that name is on the list.
• It resolves the name itself and connects to the public addresses that it finds, so the address that the session dialled plays no part. The gateway refuses a name that resolves to a private, loopback, link-local or shared address. A listed name can therefore never point inside Hangar's network.
• It allows each request only for the host that the connection was made for.

The gateway refuses anything that it cannot name: a hello with no server name, an encrypted client hello, a name not on the list, and traffic that is not TLS. The session certificate shows each refusal with its reason.

Credentials attached by name

--attach SECRET=destination:header[:scheme] makes the gateway add a secret to every request for that destination, in that header. You set the secret first with hangar secret set. For example, the gateway adds authorization: Bearer <value>.

The value goes from Hangar's secret store to the gateway's memory and into the request's header, and nowhere else. The session, its containers and its files contain no credential. If the session sends a header of the same name, the gateway replaces that header. At each resume or recovery, the gateway receives the values again from the store, so a deleted secret is no longer attached.

A destination's reply can repeat the value, in a header or in the body. Before the reply reaches the session, the gateway replaces every occurrence with asterisks of the same length. The certificate shows the secret by name as masked. The page Credentials in sandboxes and jobs sets out how Hangar stores secrets.

Approvals on your phone

Your account's sandbox policy, the Lock, says which uses need a named person:

• credential_use: the first use of each attached credential in a session (on from the start).
• destination_first_use: the first connection to each destination in a session.

Hangar counts a first use again after each resume or recovery, because the session's authority is issued fresh.

When an action needs approval, the gateway pauses the request. It sends a proposal through the TALOS Warrant approval relay to the approvers' phones. The card shows a sentence that Hangar writes from the proposal's fields. The card also shows the SHA-384 digest that binds the sentence to those fields. The request goes on only after a named person approves. The decision is a signed record with the approver's identity, on the session certificate.

An agent can also propose an action of its own. The agent sends a POST to https://approvals.hangar.internal/v1/proposals with the tool's name and the SHA-384 digest of the exact call. The gateway answers at that address itself. The gateway pauses the call until a person decides, and then replies approved or declined.

What the gateway records

For every connection, the gateway records:

• the session, the destination, the port and the protocol;
• when the connection opened and closed;
• the bytes each way and the number of requests;
• whether the gateway passed or refused the connection, and why;
• the secrets attached by name, and the secrets masked by name.

The gateway records no request body, no reply body and no header value. The gateway sends the connections to Hangar in batches. Each batch is a signed record on the session certificate.

Refusals on the certificate

The model route

A Claude Code session signs in inside the sandbox through the gateway, as Claude Code does on your own machine. List claude.ai, console.anthropic.com and api.anthropic.com. The sign-in stays inside the session. Hangar passes the connection on and stores nothing from the connection.

When the session ends

The sandbox reset runs. It does these things, and records each with its AWS response:

• It terminates the instance together with the session volume.
• It checks the rules of the session security group.
• It revokes the credentials, and destroys the session volume key with them.
• It destroys the gateway's certificate authority.
• It detaches the secrets.

The session certificate follows, with the kind sandbox session. The certificate records each attempt and each interruption with its outcome. The certificate lists each command as a job. The page The sandbox reset sets out each step.

Read this page as Markdown