The PillDrops SDKs.

pip install pilldrops

npm install @pilldrops/sdk

# one-line installer (macOS / Linux, arm64 + x64)
curl -fsSL https://pilldrops.com/install.sh | sh

# or via npm — downloads the same static binary on first run
npm install -g @pilldrops/cli

export PILLDROPS_API_URL=https://pilldrops.com
export PILLDROPS_API_KEY=sf_...

# or pass explicitly:
Sandbox.create(template="python-3.11",
               api_url="https://pilldrops.com", api_key="sf_...")

export PILLDROPS_API_URL=https://pilldrops.com
export PILLDROPS_API_KEY=sf_...

// or pass explicitly:
await Sandbox.create({ template: 'python-3.11',
  apiUrl: 'https://pilldrops.com', apiKey: 'sf_...' })

# browser sign-in (same account as the dashboard) — stores a key in ~/.pilldrops/config.json
pilldrops login

# headless / CI / agents:
pilldrops login --key sf_...
# …or just export PILLDROPS_API_KEY and skip login entirely

from pilldrops import Sandbox

with Sandbox.create(template="python-3.11") as sb:
    r = sb.run("python3 -c 'print(2+2)'")
    print(r.stdout)          # "4\n"
    print(r.ok)              # True (exit_code == 0)
# sandbox destroyed automatically when the block exits

import { Sandbox } from '@pilldrops/sdk'

const sb = await Sandbox.create({ template: 'python-3.11' })
try {
  const r = await sb.run("python3 -c 'print(2+2)'")
  console.log(r.stdout)      // "4\n"
  console.log(r.ok)          // true (exitCode === 0)
} finally {
  await sb.kill()          // destroy the sandbox
}

pilldrops sandbox create --template python-3.11
# → sb_abc123…
pilldrops exec sb_abc123 -- python3 -c 'print(2+2)'
# → 4  (exec exits with the remote command's exit code, like ssh)
pilldrops sandbox rm sb_abc123

sb = Sandbox.create(
    template="node-20",
    env={"NODE_ENV": "production"},
    vcpu=2, mem_mb=2048,
    timeout=1800,               # auto-destroy after 30 min
)
print(sb.id)        # "sb_…"
print(sb.status)    # "running"
print(sb.template)  # "node-20"

const sb = await Sandbox.create({
  template: 'node-20',
  env: { NODE_ENV: 'production' },
  vcpu: 2, memMb: 2048,
  timeout: 1800,             // auto-destroy after 30 min
})
console.log(sb.id)         // "sb_…"
console.log(sb.status)     // "running"
console.log(sb.template)   // "node-20"

r = sb.run("pip install requests && python3 app.py", timeout=120)

r.stdout      # captured stdout (str)
r.stderr      # captured stderr (str)
r.exit_code   # int — 0 on success
r.truncated   # True if output was cut at the size cap
r.ok          # exit_code == 0
r.check()     # raise RuntimeError if it failed (chainable)

# run in a specific directory — simplest is cd inside the command:
sb.run("cd app && npm test", timeout=300)
# cwd works too, but must be an ABSOLUTE path that exists:
sb.run("npm test", cwd="/root/app", timeout=300)

const r = await sb.run('pip install requests && python3 app.py', undefined, 120)

r.stdout      // captured stdout (string)
r.stderr      // captured stderr (string)
r.exitCode    // number — 0 on success
r.truncated   // true if output was cut at the size cap
r.ok          // exitCode === 0

// run in a specific directory — simplest is cd inside the command:
await sb.run('cd app && npm test', undefined, 300)
// the 2nd arg is cwd — if set, it must be an ABSOLUTE path that exists

r = sb.run_code("""
import json
data = {"answer": sum(range(101))}
print(json.dumps(data))
""")
print(r.stdout)   # {"answer": 5050}

sb.run_code("console.log(process.version)", lang="node")
sb.run_code("uname -a", lang="bash")

const r = await sb.runCode(`
import json
data = {"answer": sum(range(101))}
print(json.dumps(data))
`)
console.log(r.stdout)   // {"answer": 5050}

await sb.runCode('console.log(process.version)', 'node')
await sb.runCode('uname -a', 'bash')

# single files (str or bytes)
sb.files.write("app/config.json", '{"debug": false}')
text = sb.files.read("app/config.json")

# list a directory → [{name, is_dir, size, modified}, …]
for entry in sb.files.list("app"):
    print(entry["name"], entry["is_dir"])

# whole directories — tar-streamed both ways
sb.upload("./my-project", "app")      # local dir  → sandbox
sb.download("app/dist", "./dist")     # sandbox dir → local

# upload/download work for single files too
sb.upload("./main.py", "main.py")
sb.download("out.txt", "./out.txt")

// single files (string or Uint8Array)
await sb.writeFile('app/config.json', '{"debug": false}')
const text = await sb.readFile('app/config.json')

// upload a local file or an entire directory (tar-streamed)
await sb.upload('./my-project', 'app')

// directory listing / bulk download aren't wrapped yet in JS —
// use run() or the raw API for those:
const ls = await sb.run('ls -la app')

# cp works both directions, scp-style
pilldrops cp ./main.py sb_abc123:/workspace/main.py
pilldrops cp sb_abc123:/workspace/out.txt ./out.txt

with Sandbox.create(
    template="node-20",
    start="npm run dev",
    ports=[3000],
) as app:
    print(app.url)   # https://…/preview/sb_…/3000/

const app = await Sandbox.create({
  template: 'node-20',
  start: 'npm run dev',
  ports: [3000],
})
console.log(app.url)   // https://…/preview/sb_…/3000/

with Sandbox.create(template="node-20", timeout=1800) as sb:
    sb.run("git clone --depth 1 https://github.com/you/repo app", timeout=300).check()
    sb.run("cd app && npm install", timeout=600).check()
    r = sb.run("cd app && npm test", timeout=600)
    print(r.stdout if r.ok else r.stderr)

const sb = await Sandbox.create({ template: 'node-20', timeout: 1800 })
await sb.run('git clone --depth 1 https://github.com/you/repo app', undefined, 300)
await sb.run('cd app && npm install', undefined, 600)
const r = await sb.run('cd app && npm test', undefined, 600)
console.log(r.ok ? r.stdout : r.stderr)
await sb.kill()

with Sandbox.create(template="python-3.11") as sb:
    sb.upload("./my-project", "app")
    sb.run("cd app && pip install -r requirements.txt", timeout=600).check()
    sb.run("cd app && pytest --cov --cov-report=html", timeout=600)
    sb.download("app/htmlcov", "./htmlcov")   # pull the report back

const sb = await Sandbox.create({ template: 'python-3.11' })
await sb.upload('./my-project', 'app')
await sb.run('cd app && pip install -r requirements.txt', undefined, 600)
const r = await sb.run('cd app && pytest', undefined, 600)
// bulk download isn't wrapped in JS yet — read single files:
const report = await sb.readFile('app/report.txt')
await sb.kill()

sb.pause()                # suspend — billing stops, disk kept
sb.resume()               # wake it up where it left off

sb.set_timeout(3600)      # replace the remaining TTL: destroy 1 h from now

sb.kill()                 # destroy immediately (idempotent, never raises)

await sb.pause()          // suspend — billing stops, disk kept
await sb.resume()         // wake it up where it left off

await sb.setTimeout(3600) // replace the remaining TTL: destroy 1 h from now

await sb.kill()           // destroy immediately

out = sb.logs()       # {"lines": [...], "truncated": False}
for line in out["lines"]:
    print(line)

m = sb.metrics()      # {"cpu": …, "mem": …, …}

const m = await sb.metrics()   // { cpu: …, mem: …, … }

// app logs aren't wrapped yet in JS — GET /v1/sandboxes/{id}/logs,
// or tail from inside: await sb.run('tail -n 100 /var/log/app.log')

pilldrops logs sb_abc123 -f     # follow app logs
pilldrops ps sb_abc123          # process list (pid, cmd, cpu, mem)
pilldrops metrics sb_abc123     # live CPU / RAM

from pilldrops import Templates

for t in Templates().list():
    print(t["id"])

import { listTemplates } from '@pilldrops/sdk'

const templates = await listTemplates()
console.log(templates.map(t => t.id))

pilldrops templates

from pilldrops import Sandbox, build_image

img = build_image("./myapp", "myapp")      # dir with a Dockerfile → tag

with Sandbox.create(image=img) as sb:
    sb.run("python3 --version").check()

import { Sandbox, buildImage } from '@pilldrops/sdk'

const img = await buildImage('./myapp', 'myapp')

const sb = await Sandbox.create({ image: img })

pilldrops image build ./myapp -t myapp
pilldrops sandbox create --image myapp

try:
    sb = Sandbox.create(template="python-3.11")
except PermissionError:      # 401 — invalid API key
    ...
except RuntimeError as e:    # any other API failure (message has status + body)
    ...

r = sb.run("pytest")
if not r.ok:                 # command failed — not an exception
    print(r.stderr)

sb.run("pytest").check()     # …or make it raise, subprocess-style

try {
  const sb = await Sandbox.create({ template: 'python-3.11' })
} catch (err) {
  // API failure — err.message carries the status + response body
}

const r = await sb.run('pytest')
if (!r.ok) {                 // command failed — not an exception
  console.error(r.stderr)
}