On this page
Sandboxes quickstart
From an empty environment to a command running in a lease, in five calls
This takes an environment to a machine running your command, and then gives the machine back. Every step exists in the console too, but the calls are the clearest statement of what is happening.
1. Create a lease
A lease needs nothing: create it with an empty spec and the platform resolves
the machine — a general machine of the base image on the linux-s shape,
for 300 seconds. No catalog lookup and no size to choose.
sylphx sandboxes leases create \
--parent orgs/acme/projects/shop/envs/productioncurl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"spec":{}}'const lease = await sylphx.sandboxes.leases.create({
lease: { spec: {} },
parent: 'orgs/acme/projects/shop/envs/production',
})kind defaults to general; image to that kind's template (base for a
general machine); shape to linux-s; and ttl to 300 seconds, capped at the
shape's longest lease. The response records the resolved shape and ttl, so
lease.spec.shape and lease.spec.ttl say what you got.
create waits for READY and gives up on the wait after 60 seconds; pass
skip_wait_ready to be answered at GRANTED instead and poll the lease
yourself. A machine that cannot be granted this second is refused, not
queued — the answer carries status.refusal, one of no_capacity,
no_matching_cell, shape_not_offered, shape_not_entitled,
image_not_found or abuse_hold.
2. Override the defaults
Every default is a field you may set instead. The shape catalog is read-only, and it is the list of machines you may ask for:
sylphx sandboxes sandbox-shapes listcurl "https://api.sylphx.com/v1/sandbox_shapes" \
-H "Authorization: Bearer $SYLPHX_API_KEY"const response = await sylphx.sandboxes.sandboxShapes.list({})A shape carries the operating system, the vCPUs, the memory, the disk, the
Cell capability Placement matches, the kinds it can serve, and
min_lease_duration and max_lease_duration — the shortest and longest lease
of it. offered says whether the shape is sold now, and a lease naming one
that is not is refused SHAPE_NOT_OFFERED. The collection
page lists every field.
This lease asks for sandbox_shapes/linux-xs — one vCPU, 1024 MiB of memory
and a 5 GiB disk on the kata capability — runs it for ten minutes, and pins
it to a region:
sylphx sandboxes leases create \
--parent orgs/acme/projects/shop/envs/production \
--spec.shape sandbox_shapes/linux-xs \
--spec.ttl 10m \
--spec.region gracurl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"spec":{"shape":"sandbox_shapes/linux-xs","ttl":"10m","region":"gra"}}'const response = await sylphx.sandboxes.leases.create({
lease: { spec: { shape: 'sandbox_shapes/linux-xs', ttl: '10m', region: 'gra' } },
parent: 'orgs/acme/projects/shop/envs/production',
})ttl is the longest the lease may live, counted from the grant. A microVM
takes a ttl from one minute to 24 hours. kind picks the machine that
serves browser, desktop, or android work where a general machine cannot,
and region pins placement to one region rather than letting the platform
choose.
3. Run a command
exec runs one command in a ready lease and answers when it finishes, with
exit_code, stdout and stderr:
sylphx sandboxes leases exec \
orgs/acme/projects/shop/envs/production/leases/lease \
--command echo --command hello --idempotency-key example-command-1curl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:exec" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"command":["bash","-lc","echo hello"],"idempotency_key":"example-command-1"}'const response = await sylphx.sandboxes.leases.exec({
command: ['bash', '-lc', 'echo hello'],
idempotencyKey: 'example-command-1',
name: 'orgs/acme/projects/shop/envs/production/leases/lease',
})The command does not go through a shell unless you ask for one: the request
takes an argument list, and ["bash", "-lc", "…"] is the shape to use when
you want shell syntax. The default timeout is 60 seconds and the longest is
30 minutes, bounded by lease expiry. Each HTTP response waits at most 20
seconds. A pending command returns 409 IDEMPOTENCY_IN_PROGRESS and
Retry-After; the SDK and CLI keep observing the same request and key until
it finishes or the caller's deadline expires. With curl, resend the exact
body and key after that delay. Persist a fresh key for each intended command;
keep it to recover after a disconnect. EXEC_OUTCOME_UNKNOWN is terminal
and must never be retried under a new key.
Disconnecting stops observation. To request cancellation, call
leases.cancelExec({name, idempotencyKey}) or POST {idempotency_key} to
/v1/{lease}:cancelExec, then observe the original exec request. Only a
terminal response with cancelled: true confirms cancellation; an already
completed command keeps its result. Interactive processes use guest_uri.
Decode the streams before you print them
stdout and stderr are bytes on the wire, so they arrive base64-encoded,
and the generated TypeScript type declares them as plain strings. Decode
before printing, or a byte count will look right and the text will not.
4. Write and read a file
Files go in with write_file and come back with read_file, at most 16 MiB
at a time. Missing parent directories are created for you.
sylphx sandboxes leases write-file \
orgs/acme/projects/shop/envs/production/leases/lease \
--path /home/user/hello.txt \
--content hellocurl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:writeFile" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path":"/home/user/hello.txt","content":"…"}'const response = await sylphx.sandboxes.leases.writeFile({
name: 'orgs/acme/projects/shop/envs/production/leases/lease',
path: '/home/user/hello.txt',
content: 'hello',
})Reading it back is the same call the other way:
sylphx sandboxes leases read-file \
orgs/acme/projects/shop/envs/production/leases/lease \
--path /home/user/hello.txtcurl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:readFile" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{"path":"/home/user/hello.txt"}'const response = await sylphx.sandboxes.leases.readFile({
name: 'orgs/acme/projects/shop/envs/production/leases/lease',
path: '/home/user/hello.txt',
})A file written this way lives on the lease's own disk. When the lease ends the disk goes with it — a volume is what makes work outlive a lease.
5. Release the lease
sylphx sandboxes leases release \
orgs/acme/projects/shop/envs/production/leases/lease \
--yescurl -X POST "https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/leases/lease:release" \
-H "Authorization: Bearer $SYLPHX_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'const response = await sylphx.sandboxes.leases.release({
name: 'orgs/acme/projects/shop/envs/production/leases/lease',
})release ends the lease now and answers with the ended lease, whose
end_reason is END_REASON_RELEASED. The machine is destroyed and never
leased again. Leaving the lease alone instead ends it at its ttl, and the
end_reason says which one happened.
The lease's own history outlives it, so the last call of the run is the one that says what happened to the machine:
sylphx sandboxes lease-events list \
orgs/acme/projects/shop/envs/production/leases/lease