Sandboxes

A sandbox is a machine for running code and automation, with no screen: run commands, execute code that keeps its state, watch files, and snapshot and fork. It works just like a VM, minus the graphical display.

Create and connect

npm install @solarisdk/sandbox

import { SandboxClient } from "@solarisdk/sandbox"

const sandboxes = new SandboxClient({
  apiKey: process.env.SOLARI_API_KEY!, // your Solari API key
  baseUrl: "https://api.getsolari.com",
})

const sbx = await sandboxes.create({
  template: "base",
  cpu: 4,                             // number of CPUs, 1-8 (default 2)
  memMb: 8192,                        // memory in MB, up to 16384 (default 2048)
  timeoutMs: 15 * 60 * 1000,          // pause after this much idle time
  lifecycle: { onTimeout: "pause" },  // when idle: pause (default), or "kill"
})
await sbx.connect()

Pick how many CPUs (cpu, from 1 to 8, default 2) and how much memory (memMb, up to 16 GB, default 2 GB) the sandbox has — above those the create is rejected with a400, not quietly reduced — same as a VM. The size sticks across snapshot, pause, and resume. Both the 1–8 cpu range and the up-to-16 GB memMb range above are for isolation: "dedicated" (the default) and "hardened" — isolation: "shared" has its own, lower ceiling on both: cpu up to 4, memMb up to 2048 (default 512, not 2048); see below.

Isolation tiers

isolation picks how much of a machine you get. "dedicated" (the default) is a microVM of your own. "hardened" is the same, with all outbound network blocked. "shared" is cheaper and starts faster: your sandbox is a process tree inside a VM you share with your other "shared" sandboxes, isolated from them by namespaces and a cgroup rather than by a hypervisor. Cross-organization isolation is unaffected either way — you never share a VM with another org.

const sbx = await sandboxes.create({
  template: "base",
  isolation: "shared",
  cpu: 4,      // shared's own ceiling — see below, this is NOT the 1-8 range
  memMb: 1024, // default 512 if you don't set it — lower than dedicated's 2048
})

Run commands

commands.run runs a command to completion and returns { exitCode, stdout, stderr }; pass onStdout/onStderr to stream output live, and cwd/env to shape the environment.

const res = await sbx.commands.run("sh", {
  args: ["-c", 'echo "$GREETING"'],
  cwd: "/opt/app",
  env: { GREETING: "hi" },
  onStdout: (d) => process.stdout.write(d),
  onStderr: (d) => process.stderr.write(d),
})
console.log("exit:", res.exitCode)

For a long-running process, commands.start returns a handle with streamed output, stdin, and kill.

const proc = await sbx.commands.start("cat")
proc.onData((c) => process.stdout.write(`[${c.stream}] ${c.data}`))
await proc.stdin("echo me\n")
await proc.kill()

Interactive PTY

Need a real terminal (colours, full-screen apps, a shell prompt)? pty.create opens one you can write to, resize, and read from. It's what powers the console's web terminal.

const term = await sbx.pty.create({ cols: 100, rows: 30 })
term.onData((bytes) => process.stdout.write(bytes))
await term.write("ls -la\n")
await term.resize(120, 40)

Run code

runCode runs a snippet and remembers its state between calls, so variables and imports you set stick around. Output comes back in results: text from stdout and stderr, plus richer output like matplotlib figures as a base64 PNG on results[i].png.

await sbx.runCode("import numpy as np; x = np.arange(10)", { language: "python" })
const out = await sbx.runCode("print(x.sum())", { language: "python" })
console.log(out.results, "error:", out.error ?? "none")

// Matplotlib figures come back as base64 PNG result items.
const fig = await sbx.runCode("import matplotlib.pyplot as plt; plt.plot(x); plt.show()")
const png = fig.results.find((r) => r.png)?.png   // base64-encoded PNG

Structured charts

Alongside the PNG, a matplotlib figure also comes back as structured data on results[i].chart, and every chart in a run is collected on out.charts for convenience. Instead of an image you can't read, you get the chart's type (line, scatter, bar, pie, or composite), its title and axis labels, and the underlying series. That makes it easy for feeding a figure straight to an agent or re-rendering it yourself.

const r = await sbx.runCode(`
import matplotlib.pyplot as plt
plt.bar(["a", "b", "c"], [3, 7, 5])
plt.title("Scores"); plt.xlabel("group"); plt.ylabel("count")
plt.show()
`, { language: "python" })

const chart = r.charts[0]
console.log(chart.type)              // "bar"
console.log(chart.title)             // "Scores"
console.log(chart.x?.ticks)          // ["a", "b", "c"]
console.log(chart.y?.label)          // "count"
console.log(chart.elements)          // the raw series values

Version control

The git namespace wraps common Git operations so you don't have to shell out and parse porcelain yourself: clone, status, add, commit, push/pull, checkout, branches, and log all return typed results. Credentials are passed per-call and never touch a shell, so there is nothing to escape or inject.

await sbx.git.clone("https://github.com/psf/requests", {
  path: "/work/requests",
  depth: 1,
})
const status = await sbx.git.status("/work/requests")   // cwd
console.log(status.branch, status.clean)   // "main" true

await sbx.files.write("/work/requests/NOTE.md", "hi")
await sbx.git.add(["NOTE.md"], "/work/requests")        // paths, cwd
const { hash } = await sbx.git.commit("Add a note", {
  cwd: "/work/requests",
  author: "Agent", email: "agent@example.com",
})
const log = await sbx.git.log({ cwd: "/work/requests", maxCount: 1 })
console.log(log[0].hash === hash, log[0].message)   // true "Add a note"

Branch and publish the same way. Pass a username / password (a personal-access token) to push or pull and the credential is spliced into the remote URL for that one invocation only. It is never written to the repo or global Git config, so nothing is left behind on the machine.

await sbx.git.checkout("feature/notes", {
  cwd: "/work/requests",
  create: true,                 // -b: start a new branch
})
await sbx.git.push({
  cwd: "/work/requests",
  branch: "feature/notes",
  username: "agent",
  password: process.env.GITHUB_TOKEN,   // one-off auth, not persisted
})

Files

The files surface reads and writes guest files directly, plus list, search, watch, and upload/download of larger blobs.

await sbx.files.write("/tmp/hello.txt", "world")
const text = await sbx.files.readText("/tmp/hello.txt")
const entries = await sbx.files.list("/tmp")
const hits = await sbx.files.search("/tmp", "world")

// Stream filesystem events until you call the returned stop().
const stop = await sbx.files.watch("/tmp", (ev) =>
  console.log("fs:", ev.type, ev.path),
)
await stop()

Expose a port

previewUrl(port) gives you a public URL for something the sandbox is serving on that port: a dev server, an API, anything. Available where a preview domain is set up.

const preview = await sbx.previewUrl(3000)
console.log("preview:", preview.url)

The URL is signed: it carries a one-hour slr_token query parameter, and the response also returns that token separately as preview.token. Open preview.url as-is, or for other paths put the path before the query — or send the token as a header instead:

const { url, token } = await sbx.previewUrl(3000)
const origin = new URL(url).origin

// a specific path: path first, then the token
await fetch(`${origin}/api/health?slr_token=${token}`)

// or keep URLs clean and send the token as a header
await fetch(`${origin}/api/health`, {
  headers: { "x-solari-preview-token": token },
})

A 401 means the token was missing, altered, or older than an hour — call previewUrl() again for a fresh one. (If you're upgrading old code: pt_token, x-pinetree-preview-token, and the __pt_preview cookie were renamed on 2026-10-06 and are no longer accepted — a request using only an old name gets a distinct error naming the rename.) Anything that reaches the sandbox but finds nothing listening yet answers 425 Too Early; poll until it turns into your app.

The first request that authenticates via the query parameter also gets a host-scoped cookie carrying the same token, so a browser's follow-up requests for the page's own assets (which don't carry the query string) authenticate too. The cookie expires with the token — it is not a separate, longer-lived grant.

Snapshots

Save a prepared sandbox and start ready-to-go copies from it, or reset one back to that saved state between runs. See Snapshots for the full flow.

const snapId = await sbx.snapshot("after-setup")
const fork = await sandboxes.create({ template: "base", fromSnapshot: snapId })

Idle timeout

Like VMs, a sandbox stays running as long as you're using it. Set timeoutMs to say how long it can sit idle; every action and open connection resets the clock. When that time passes with no activity, lifecycle decides what happens: onTimeout: "pause" (the default) saves its state and pauses it, while onTimeout: "kill" shuts it down. If you don't set timeoutMs, it defaults to 30 minutes.

await sbx.setTimeout(15 * 60 * 1000)  // change how long it can sit idle (ms)
await sbx.pause()                     // pause it, state is saved, resumes on connect()

Park, hibernate, and durable checkpoints

The idle timeout above is one lever. Three more exist for finer-grained control over a running sandbox — all of them opt-in: none of this happens unless you set the field. A sandbox you create with no lifecycle beyond onTimeout behaves exactly as described above, with nothing extra going on in the background.

const sbx = await sandboxes.create({
  template: "base",
  timeoutMs: 15 * 60 * 1000,
  lifecycle: {
    onTimeout: "pause",
    parkAfterMs: 5_000,             // deschedule after 5s idle (min 2_000)
    hibernateAfterParkedMs: 60_000, // escalate to a full pause after 1 min parked
    checkpointEveryMs: 5 * 60_000,  // durable checkpoint every 5 min (min 60_000)
  },
})

parkAfterMs — instant descheduling for short waits

If your workload spends most of its time waiting on something else — a tool call, an LLM response, a webhook — set parkAfterMs to deschedule the sandbox after that many milliseconds of no activity. A parked sandbox's CPUs are frozen, but its slot, network connection, and control channel stay held, so the next request wakes it with nothing to restore. This is a different, lighter mechanism than the full pause above, not a faster version of it: pausing frees the slot and saves state to durable storage; parking freezes the CPUs in place and keeps everything resident.

parkAfterMs is floored at 2 seconds (a lower value is raised to it, so a caller can't ask for a park/unpark storm) and capped at your timeoutMs — parking after the session would already have paused is a no-op, so the value is clamped rather than silently ignored.

hibernateAfterParkedMs — escalate a long park to a full pause

If a parked sandbox stays parked this long with still no activity, the gateway escalates it to a full pause — state saved, slot freed — instead of holding the slot indefinitely on the chance activity resumes. Use it when waits are usually short but can occasionally run long, and you'd rather free the slot than keep paying for it during the long tail. Same floor as parkAfterMs, capped at timeoutMs.

const sbx = await sandboxes.create({
  template: "base",
  lifecycle: {
    onTimeout: "pause",
    parkAfterMs: 5_000,                  // deschedule almost immediately on idle
    hibernateAfterParkedMs: 15 * 60_000, // free the slot after 15 minutes parked
  },
})

checkpointEveryMs — durable continuations for long-running sessions

Take a durable checkpoint on this interval while the sandbox runs, so an unexpected host issue costs at most one interval of progress rather than the whole session. Off by default — nothing checkpoints a session unless you set this field. Floored at 60 seconds: a checkpoint briefly pauses the guest for the length of the snapshot, so too short an interval spends the session stuttering instead of working.

On wake latency: park’s handoff has no cold-restore step — the guest's memory never leaves host RAM — while a full pause restores from durable storage and is the slower of the two. Measured on staging across five trials, all resuming on the same host the session was paused on (resume defaults to the originating host; it only rebuilds on a different one if that host has become unreachable): once a pause had actually finished shipping its snapshot, resume took about 1.3 seconds. But pause and resume share a per-sandbox lock, so calling resume while a pause is still in flight queues behind it rather than failing or racing — resumes fired a few seconds after the pause call, before the snapshot had finished, took 16–20 seconds in our trials. If your workload calls resume shortly after pause, budget for the slower number; if pause has had time to settle first, expect the faster one. Either way, resume is safe to call as soon as you want it — it will simply wait its turn. We haven't yet measured the cross-host case (the host that held your paused session is gone or unreachable, so resume rebuilds from the durable snapshot elsewhere) — expect that path to be slower, and treat it as unmeasured rather than assuming it matches the number above.

Tear down

await sbx.kill()