Skip to content
Console
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.

Shell
sylphx sandboxes leases create \
  --parent orgs/acme/projects/shop/envs/production
Shell
curl -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":{}}'
TypeScript
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:

Shell
sylphx sandboxes sandbox-shapes list
Shell
curl "https://api.sylphx.com/v1/sandbox_shapes" \
  -H "Authorization: Bearer $SYLPHX_API_KEY"
TypeScript
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:

Shell
sylphx sandboxes leases create \
  --parent orgs/acme/projects/shop/envs/production \
  --spec.shape sandbox_shapes/linux-xs \
  --spec.ttl 10m \
  --spec.region gra
Shell
curl -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"}}'
TypeScript
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:

Shell
sylphx sandboxes leases exec \
  orgs/acme/projects/shop/envs/production/leases/lease \
  --command echo --command hello --idempotency-key example-command-1
Shell
curl -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"}'
TypeScript
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.

Shell
sylphx sandboxes leases write-file \
  orgs/acme/projects/shop/envs/production/leases/lease \
  --path /home/user/hello.txt \
  --content hello
Shell
curl -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":"…"}'
TypeScript
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:

Shell
sylphx sandboxes leases read-file \
  orgs/acme/projects/shop/envs/production/leases/lease \
  --path /home/user/hello.txt
Shell
curl -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"}'
TypeScript
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

Shell
sylphx sandboxes leases release \
  orgs/acme/projects/shop/envs/production/leases/lease \
  --yes
Shell
curl -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 '{}'
TypeScript
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:

Shell
sylphx sandboxes lease-events list \
  orgs/acme/projects/shop/envs/production/leases/lease

Next