Quickstart

Platinum runs untrusted and AI-generated code in isolated sandboxes. This page takes you from an API key to a running sandbox. Use it for your first ten minutes with Platinum.

How Platinum works

Term	Meaning
image	Any Docker image.
template	A frozen image plus default CPU, RAM, and disk.
sandbox	A running microVM, created from a template.
snapshot	A capture of a sandbox's state.
fork	A new sandbox created from a snapshot.

image → template → sandbox → snapshot → fork

If you name no template, Platinum uses the built-in pt-base. See Templates and Snapshots.

Get an API key

Create an API key in the dashboard → API Keys, or run pt login.

export PT_API_URL=https://api.platinum.dev
export PT_TOKEN=pt_live_…

Install

npm install @platinum-dev/sdk

pip install platinum-sdk

npm install -g @platinum-dev/cli

Create a sandbox and run a command

Create a sandbox, wait for the running state, then exec a command.

import { Platinum } from "@platinum-dev/sdk";

const client = new Platinum({ url: process.env.PT_API_URL!, token: process.env.PT_TOKEN! });

const sbx = await client.sandboxes.create(
  { template: "pt-base", ram_mb: 512 },
  { waitForRunning: true },
);
console.log((await sbx.exec(["uname", "-a"])).stdout);

import os
from platinum import Platinum

client = Platinum(api_url=os.environ["PT_API_URL"], token=os.environ["PT_TOKEN"])

sbx = client.sandboxes.create(template="pt-base", ram_mb=512, wait_for_running=True)
print(sbx.exec(["uname", "-a"]).stdout)

SBX=$(pt sandbox create -t pt-base --ram 512 -q)
pt sandbox exec $SBX 'uname -a'

SBX=$(curl -sS -X POST "$PT_API_URL/v1/sandboxes?wait_for_state=running" \
  -H "Authorization: Bearer $PT_TOKEN" -H "Content-Type: application/json" \
  -d '{"template":"pt-base","ram_mb":512}' | jq -r .id)

curl -sS -X POST $PT_API_URL/v1/sandboxes/$SBX/exec \
  -H "Authorization: Bearer $PT_TOKEN" -H "Content-Type: application/json" \
  -d '{"cmd":["uname","-a"]}' | jq -r .result.stdout

Run code

run-code is a one-call interpreter. Pass code, get stdout, stderr, and exit code. See Exec.

const r = await sbx.runCode("import math; print(math.pi)", { lang: "python" });
console.log(r.stdout);

r = sbx.run_code("import math; print(math.pi)", lang="python")
print(r.stdout)

pt sandbox run-code $SBX 'import math; print(math.pi)' --lang python

curl -sS -X POST $PT_API_URL/v1/sandboxes/$SBX/run-code \
  -H "Authorization: Bearer $PT_TOKEN" -H "Content-Type: application/json" \
  -d '{"code":"import math; print(math.pi)","lang":"python"}'

Stop and resume

Stop keeps memory and processes. Start restores them where they left off. See Sandboxes for the full lifecycle.

await sbx.stop({ waitForStopped: true });
await sbx.start({ waitForRunning: true });

sbx.stop(wait_for_stopped=True)
sbx.start(wait_for_running=True)

pt sandbox stop $SBX
pt sandbox start $SBX

curl -sS -X POST "$PT_API_URL/v1/sandboxes/$SBX/stop?wait_for_state=stopped" \
  -H "Authorization: Bearer $PT_TOKEN"
curl -sS -X POST "$PT_API_URL/v1/sandboxes/$SBX/start?wait_for_state=running" \
  -H "Authorization: Bearer $PT_TOKEN"

Clean up

Delete removes the sandbox and its disk. This is permanent.

await sbx.delete();

sbx.delete()

pt sandbox rm $SBX

curl -sS -X DELETE $PT_API_URL/v1/sandboxes/$SBX \
  -H "Authorization: Bearer $PT_TOKEN"

Sandboxes — lifecycle: pause, archive, resize, delete
Exec and Filesystem — commands, interpreter, file operations
Templates — build custom templates, or use the declarative builder
Snapshots — capture, restore, clone, fork
Networking — expose ports, preview URLs
CLI — the full pt command set