kosa8 docs

Guides / kosa8 Cloud / Snapshots, background commands and env

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.

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

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

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