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.
- 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 410snapshot_lostand 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). 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.