Sandboxes

A sandbox is a machine for code you don't trust yet: something an agent just wrote, a dependency you haven't read, a script from the internet. It's an Instant machine with three differences:

• It has a lifetime. When the lifetime ends, the sandbox is deleted with everything in it. A new sandbox gets one hour. You can change that at any time, or keep the sandbox.
• It has no public address. No public IPv6, no public IPv4, no open ports: nothing on the internet can connect to it. Web links still work, because they go through us.
• It isn't in a VPC. It can't be put on a private network with your other machines.

Everything else is a normal machine: its own kernel, root, shells, commands, files, snapshots, the same sizes and prices, billed per second.

What a sandbox doesn't change

• Outbound internet is on, as on any machine, so the code inside can download what it needs. It can also send out anything it can read inside the sandbox. To cut it off, turn the machine's internet off (machine page → Internet, set_network, or "network" in the API) and allow only the destinations it needs.
• Don't put secrets in it that the code shouldn't see: API keys, SSH keys, customer data.
• It's deleted on time whether it's awake or asleep, and whether or not someone is connected. Copy out what you want to keep before then, or give it more time.

Make one

• In the app: New machine → SANDBOX, then size, image and name as usual.
• Agents (MCP): create_machine with sandbox: true, and lifetime_minutes if an hour isn't right.
• API: POST /v1/machines with "sandbox": true, and "lifetime_seconds" if an hour isn't right.

curl -s -X POST https://api.shell.639cloud.com/v1/machines \
  -H "Authorization: Bearer $KEY" \
  -d '{"size": "s1", "image": "python", "sandbox": true, "lifetime_seconds": 900}'

The reply says "sandbox": true and gives "expires_at", the time it will be deleted. Lists show the same, and the app marks sandboxes on My machines with the time they have left.

The lifetime

• From 1 minute to 30 days, counted from the moment you set it.
• Change it: the machine's page → Lifetime…, set_lifetime over MCP, or PATCH /v1/machines/{name} with "lifetime_seconds".
• Keep it: a lifetime of 0. The machine stays until you delete it, and it stays a sandbox: still no public address and no VPC.
• Delete protection wins. If you turn delete protection on for a sandbox, it isn't deleted when its lifetime ends: it's kept, and its lifetime is removed.
• A fork of a sandbox is a sandbox too, and ends when the one it was forked from does.
• A normal machine can't be turned into a sandbox, and a sandbox can't be turned into a normal machine. To move work out of a sandbox, copy the files out.

Every sandbox deleted at the end of its lifetime is in your history (sandbox-expire).

This page as Markdown: /docs/sandboxes.md