Sandbox REST API and SDKs

Authorization: Bearer <token>
Accept: application/json
Content-Type: application/json

export STACKSHIFT_API_URL='https://api.stackshift.cloud'
export IDEMPOTENCY_KEY='<stable-uuid>'

curl --fail-with-body --silent --show-error \
  --request POST "$STACKSHIFT_API_URL/api/v1/sandboxes" \
  --header "Authorization: Bearer $STACKSHIFT_TOKEN" \
  --header 'Content-Type: application/json' \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --data @- <<'JSON'
{
  "name": "agent-session-42",
  "profile": "coding_agent",
  "template": "ghcr.io/acme/polyglot-agent@sha256:<64-hex-digest>",
  "source": {"kind": "blank"},
  "resources": {
    "cpu": {"reserved": 1, "limit": 2},
    "memory_mb": {"reserved": 2048, "limit": 4096},
    "disk_mb": {"root": 8192, "workspace": 20480, "ephemeral": 2048},
    "pids": 512,
    "swap_bytes": 0
  },
  "lifecycle": {
    "idle_timeout_seconds": 900,
    "idle_action": "sleep",
    "auto_resume": true,
    "max_runtime_seconds": 21600,
    "ttl_seconds": 86400,
    "on_exit": "sleep",
    "activity_mode": "both"
  },
  "network": {
    "egress": "allowlist",
    "allowed_hosts": ["api.github.com", "registry.npmjs.org"],
    "allowed_cidrs": [],
    "denied_hosts": [],
    "denied_cidrs": [],
    "inbound": "none"
  },
  "metadata": {"product": "coding-agent", "session_id": "42"},
  "tags": ["agent", "customer-acme"]
}
JSON

import {
  StackshiftOperationError,
  StackshiftSandboxClient,
} from '@stackshift-cloud/sandbox'

const client = new StackshiftSandboxClient({
  baseUrl: process.env.STACKSHIFT_API_URL ?? 'https://api.stackshift.cloud',
  token: process.env.STACKSHIFT_TOKEN,
})

const operation = await client.sandboxes.create({
  name: 'agent-session-42',
  profile: 'coding_agent',
  template: 'ghcr.io/acme/polyglot-agent@sha256:<64-hex-digest>',
  tags: ['agent'],
}, 'session-42-create')

try {
  await client.operations.wait(operation.id)
  const sandbox = client.sandbox(operation.sandbox_id)
  const execution = await sandbox.exec({
    argv: ['npm', 'test'],
    cwd: '/workspace',
    timeout_seconds: 1200,
    stdout_mode: 'capture',
    stderr_mode: 'capture',
  }, 'session-42-tests')
  console.log(execution.id)
} catch (error) {
  if (error instanceof StackshiftOperationError) {
    console.error(error.operation.failure_code, error.operation.id)
  }
  throw error
}

import os

from stackshift_sandbox import (
    StackshiftOperationError,
    StackshiftSandboxClient,
)

client = StackshiftSandboxClient(
    os.getenv("STACKSHIFT_API_URL", "https://api.stackshift.cloud"),
    token=os.environ["STACKSHIFT_TOKEN"],
    timeout=30,
)

operation = client.sandboxes.create(
    {
        "name": "interpreter-42",
        "profile": "interpreter",
        "template": "ghcr.io/acme/python@sha256:<64-hex-digest>",
        "tags": ["interpreter"],
    },
    idempotency_key="interpreter-42-create",
)

try:
    client.operations.wait(operation["id"], timeout=600)
    sandbox = client.sandbox(operation["sandbox_id"])
    execution = sandbox.exec(
        {"argv": ["python", "-V"], "cwd": "/workspace"},
        key="interpreter-42-version",
    )
    print(execution["id"])
except StackshiftOperationError as error:
    print(error.operation.get("failure_code"), error.operation["id"])
    raise

client, err := sandbox.New(sandbox.Options{
    BaseURL: "https://api.stackshift.cloud",
    Token:   os.Getenv("STACKSHIFT_TOKEN"),
})
if err != nil {
    return err
}

operation, err := client.Sandboxes.Create(ctx, sandbox.CreateSandboxInput{
    Name:     "ci-42",
    Profile:  "ci",
    Template: "ghcr.io/acme/ci@sha256:<64-hex-digest>",
    Tags:     []string{"ci"},
}, "ci-42-create")
if err != nil {
    return err
}

operation, err = client.Operations.Wait(ctx, operation.ID, sandbox.WaitOptions{
    Timeout: 10 * time.Minute,
})
if err != nil {
    return err
}

{
  "error": {
    "code": "capacity_unavailable",
    "message": "No qualified capacity is currently available",
    "retryable": true,
    "request_id": "req_...",
    "operation_id": "..."
  }
}