Create a sandbox

Create requests are asynchronous. OpenMetal returns a sandbox ID and an operation ID before provider provisioning finishes.

Before you begin

Create an account, organization, project, and project API key through the agent setup or OpenMetal dashboard. Set the production API and project credentials:

export OPENMETAL_API_URL="https://api.openmetal.sh"
export OPENMETAL_PROJECT_ID="prj_your_project"
export OPENMETAL_API_KEY="metal_sk_your_key"

Managed sandbox creation requires a positive organization balance. BYOK uses your provider account.

const mutation = await metal.sandboxes.createAsync({
  provider: "auto",
  source: {
    kind: "environment",
    environment: "metal/node",
    version: "latest",
  },
  resources: {
    vcpu: 2,
    memory_mb: 4096,
    architecture: "any",
  },
  lifecycle: {
    runtime_timeout_seconds: 1800,
    on_runtime_timeout: "destroy",
  },
});

const operation = await metal.operations.wait(mutation.operation);

Interpret the result

Only succeeded, failed, and cancelled are terminal operation states. A successful create should leave the sandbox in ready.

Keep one stable idempotency key when retrying an uncertain submission. A new key requests a new mutation.

See the operations model and common errors.