Quickstart

You need a Zode account and a Linux or macOS machine (amd64 or arm64).

Your Personal workspace starts with $10 of free credit, no card needed: about 440 hours of a `small` sandbox. When it runs out, sandboxes stop until you add a card in **Billing**. A team workspace starts with $0 and gets its $10 when its first card is saved. See Pricing.

With the CLI

Install the CLI

curl -fsSL https://zode.dev/install | sh

The script checks the SHA-256 of the download and installs zode to /usr/local/bin if it can write there, otherwise to ~/.local/bin. Set ZODE_INSTALL_DIR to choose another directory.

zode login

zode login opens your browser and prints a code. Confirm the code in the browser, and the CLI saves an API key for that workspace. zode whoami shows who and where you are signed in.

Make a sandbox

zode new demo

Without --size you get a small sandbox: 2 vCPU, 4 GB RAM, 50 GB disk. The command returns once the sandbox is running and prints its size, region and how long the create took.

Run a command

zode exec demo -- uname -a

zode exec streams the output and exits with the command’s exit code.

Open a shell

zode ssh demo

You get a login shell in the sandbox. Type exit to leave; the sandbox keeps running.

Fork it

zode fork demo demo-2

demo-2 is a new running sandbox with a copy of demo’s memory and disk. Processes running in demo are running in demo-2 too.

Stop one, delete the other

zode stop demo
zode rm demo-2

zode stop hibernates demo: its disk and memory are kept and compute billing stops. zode start demo wakes it. zode rm deletes demo-2 and its disk for good.

The Free plan runs at most 2 sandboxes at once. After the fork step, demo and demo-2 use both slots. A third create, fork or start fails with “Your free plan runs at most 2 sandboxes at once. Stop one first.” Stopped sandboxes do not count.

From TypeScript or curl

Both need an API key. Create one in the console under API keys (console.zode.dev/tokens), then export it:

export ZODE_API_KEY=zode_tok_...

The TypeScript SDK needs Node 22 or later:

npm i @zodedev/sdk

These examples do the same steps as the CLI. If demo from the CLI steps still exists, run zode rm demo first or pick another name: names do not have to be unique, but the CLI then asks you for the id.

import { Sandbox } from "@zodedev/sdk";

// Reads ZODE_API_KEY from the environment.
const sbx = await Sandbox.create({ name: "demo", vcpus: 2 });

const r = await sbx.exec("uname -a");
console.log(r.exit_code, r.stdout);

const copy = await sbx.fork({ name: "demo-2" });
await sbx.stop();
await copy.delete();

API=https://api.zode.dev
AUTH="Authorization: Bearer $ZODE_API_KEY"

# Create: returns the sandbox once it is running
ID=$(curl -sS -X POST $API/v1/sandboxes -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"demo","vcpus":2}' | jq -r .id)

# Run a command: returns exit_code, stdout, stderr and duration_ms
curl -sS -X POST $API/v1/sandboxes/$ID/exec -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"command":"uname -a"}'

# Fork, stop the parent, delete the fork
FORK=$(curl -sS -X POST $API/v1/sandboxes/$ID/fork -H "$AUTH" \
  -H "Content-Type: application/json" \
  -d '{"name":"demo-2"}' | jq -r .id)
curl -sS -X POST $API/v1/sandboxes/$ID/stop -H "$AUTH"
curl -sS -X DELETE $API/v1/sandboxes/$FORK -H "$AUTH"

In the API and SDK you pick a size by vcpus: 2, 4, 8 or 16. RAM and disk follow the size, and leaving vcpus out gives small. A string command runs under bash -lc. The buffered exec route stops a command after 30 seconds by default and 55 seconds at most; for longer or interactive work, see Sandboxes. Errors come back as JSON with a stable code, for example:

{"error": {"code": "concurrency_limit", "message": "Your free plan runs at most 2 sandboxes at once. Stop one first."}}

Sandboxes: lifecycle, statuses, limits and billing.
Snapshots and fork: copy a sandbox or roll it back.
CLI overview and TypeScript SDK.

Get started

Concepts

CI

CLI

TypeScript SDK

Platform

With the CLI

From TypeScript or curl

Next