# Snapshots, background commands and env

Four things an agent harness usually needs from a sandbox: environment variables set once at create, a command that keeps running after the call that started it returns, a snapshot that keeps a sandbox's disk and memory after the sandbox is gone, and a sized sandbox that starts warm. Each is one field or one route on the [kosa8 Cloud API](https://docs.kosa8.com/guides/cloud/).

## Environment variables at create

Pass `env`, an object of names to string values. Every command in the sandbox gets them, through the API and through the direct route alike, in a persistent sandbox's container too, and a fork or a sandbox made from a snapshot keeps them. A command's own `env` wins for a name it also sets.

```
curl -s -X POST https://api.kosa8.com/v1/sandboxes \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"template":"base","env":{"APP_MODE":"test","REGION":"eu"}}'

curl -s -X POST https://api.kosa8.com/v1/sandboxes/sbx_…/exec \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"cmd":["sh","-c","echo $APP_MODE $REGION"]}'
# {"exit":0,"stdout":"test eu\n","stderr":""}
```

Names are letters, digits and `_`, not starting with a digit; at most 64 of them, a value at most 8 KiB and 64 KiB in all. Anything else is **400** `invalid_env`. The values live only on the sandbox's host: the audit log records the names, never the values. For credentials that a command should use but never read, use [Secrets](https://docs.kosa8.com/guides/cloud-secrets/) instead.

From code, the same body over plain HTTP (the SDK clients send the same JSON):

```
// JavaScript, fetch
const api = (path, body) => fetch(`https://api.kosa8.com${path}`, {
  method: body ? "POST" : "GET",
  headers: { Authorization: `Bearer ${process.env.KOSA8_API_KEY}`, "Content-Type": "application/json" },
  body: body && JSON.stringify(body),
}).then((r) => r.json());

const { sandbox } = await api("/v1/sandboxes", { template: "base", env: { APP_MODE: "test" } });
const r = await api(`/v1/sandboxes/${sandbox.id}/exec`, { cmd: ["sh", "-c", "echo $APP_MODE"] });
// r.stdout === "test\n"
```

## Background commands

Add `"background": true` to an exec. The answer is **202** at once, with an exec id; the command keeps running in the sandbox's own container after the call returns, its stdout and stderr going to a file under `/workspace/.kosa8-bg/`. Ask for its state and output later, or read the files it writes like any other.

```
curl -s -X POST https://api.kosa8.com/v1/sandboxes/sbx_…/exec \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"cmd":["sh","-c","sleep 5; echo done > /workspace/flag"],"background":true}'
# 202 {"exec":{"id":"bg_…","sandbox_id":"sbx_…","state":"running","pid":41,
#      "output_path":"/workspace/.kosa8-bg/bg_….out","exit_path":"/workspace/.kosa8-bg/bg_….exit"}}

curl -s https://api.kosa8.com/v1/sandboxes/sbx_…/exec/bg_… \
  -H "Authorization: Bearer $KOSA8_API_KEY"
# {"exec":{"id":"bg_…","state":"exited","exit":0,"output":"","output_bytes":0,…}}

# six seconds later the file is there
-d '{"cmd":["cat","/workspace/flag"]}'
# {"exit":0,"stdout":"done\n","stderr":""}
```

`state` is `running` until the command ends, then `exited` with its `exit` code. `output` is the combined stdout and stderr while it is at most 1 MiB; past that it is `null` with `output_truncated`, and you read the file with `/files` or a streamed download. A background command takes no `image` and no `stream` (**400**), and needs `/bin/sh` in the image. If the sandbox goes to sleep while one runs, the process is frozen with the sandbox's memory and goes on when it wakes; set `sleep_after_s` long enough for the work. To keep a server up for good, use a [persistent sandbox](https://docs.kosa8.com/guides/cloud/).

```
# Python, requests
import os, time, requests
api = "https://api.kosa8.com"
h = {"Authorization": f"Bearer {os.environ['KOSA8_API_KEY']}"}

job = requests.post(f"{api}/v1/sandboxes/{sid}/exec", headers=h,
                    json={"cmd": ["sh", "-c", "npm test"], "background": True}).json()["exec"]
while True:
    st = requests.get(f"{api}/v1/sandboxes/{sid}/exec/{job['id']}", headers=h).json()["exec"]
    if st["state"] == "exited":
        break
    time.sleep(2)
print(st["exit"], st["output"])
```

## Snapshots

A snapshot saves a sandbox, disk and memory, under an id that belongs to your organisation. It outlives the sandbox: sleep it, wake it, delete it, and the snapshot is still there to start new sandboxes from, each with the files and the running state of the moment it was taken.

```
curl -s -X POST https://api.kosa8.com/v1/sandboxes/sbx_…/snapshots \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' -d '{"name":"after-setup"}'
# 201 {"snapshot":{"id":"snap_…","state":"ready","source_sandbox_id":"sbx_…","bytes":1879048192,…}}

curl -s -X DELETE https://api.kosa8.com/v1/sandboxes/sbx_… -H "Authorization: Bearer $KOSA8_API_KEY"

curl -s -X POST https://api.kosa8.com/v1/sandboxes \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"snapshot":"snap_…"}'
# 201 {"sandbox":{"id":"sbx_…","state":"running","source":"snapshot","snapshot_id":"snap_…",…}}

curl -s https://api.kosa8.com/v1/snapshots -H "Authorization: Bearer $KOSA8_API_KEY"
curl -s -X DELETE https://api.kosa8.com/v1/snapshots/snap_… -H "Authorization: Bearer $KOSA8_API_KEY"
```

A create from a snapshot takes the snapshot's template, size, image and disk, so it refuses `template`, `size`, `image`, `disk_gb` and the like (**400**); it takes `env` (added to the snapshot's, yours winning), `name`, `sleep_after_s`, `delete_after_s` and `direct_access`. `GET /v1/snapshots?sandbox_id=sbx_…` lists one sandbox's snapshots. Another organisation's snapshot id answers **404**.

- **Where it lives.** A snapshot is kept on the host its sandbox ran on, and sandboxes made from it start on that host. If that host is full the create answers **503** `no_capacity`; try again shortly. If the host has lost the snapshot, the create answers **410** `snapshot_lost` and the snapshot shows `"state":"error"`.

- **What it costs.** Storage at the checkpoint rate, **$0.08 per GB-month**, billed by the hour for the bytes it holds, from when it is taken until you delete it. It shows on the bill as `snapshot_storage_usd`. The sandboxes you start from it are billed like any other.

- **Limits.** 50 snapshots per organisation (**429** `snapshot_limit`; delete one, or write to [contact@kosa8.com](mailto:contact@kosa8.com)). A sandbox with brokered secrets or dedicated cores cannot be snapshotted (**409**), so a snapshot never carries a secret. An egress policy set on the source sandbox is not carried over; the new sandbox gets your organisation's policy.

```
// JavaScript, with the api() helper above
const { snapshot } = await api(`/v1/sandboxes/${sandbox.id}/snapshots`, {});
await fetch(`https://api.kosa8.com/v1/sandboxes/${sandbox.id}`,
  { method: "DELETE", headers: { Authorization: `Bearer ${process.env.KOSA8_API_KEY}` } });
const copy = await api("/v1/sandboxes", { snapshot: snapshot.id });   // copy.sandbox.state === "running"
```

Snapshots differ from checkpoints (`POST /v1/sandboxes/{id}/checkpoints`): a checkpoint belongs to its sandbox and goes with it; a snapshot is the organisation's.

## A warm start for a sized sandbox

A sized create normally boots cold and answers **202** `creating`. When the size and image match a pool a host keeps warm (for example `{"template":"base","size":"2x4"}`, Alpine with 2 vCPU and 4 GiB), it takes a pre-booted VM instead and answers **201** `running` in about the time of a template create. The sandbox reports the pool's template (`base-2x4`) and is billed, budgeted and paid for as the 2x4 it is. A create that names a different `disk_gb`, `docker`, another image, or a size no host pools boots cold as before.

---
Source: https://docs.kosa8.com/guides/cloud-snapshots-background/
