# 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.

```sh
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`).