# OpenMetal

> OpenMetal is the compute gateway for AI agents. One REST API, TypeScript SDK, CLI, and Agent Skill provision and manage CPU sandboxes across Blaxel, Cloudflare, CodeSandbox, Daytona, E2B, Freestyle, Modal, Northflank, Runloop, and Vercel, with capability-based routing, project-scoped API keys, and one prepaid organization balance.

Important notes:

- The REST API base URL is `https://api.openmetal.sh`. Versioned routes are under `/v1`.
- Sandbox, operation, process, file, and HTTP endpoint routes use a project API key. Send `Authorization: Bearer metal_sk_...` and `X-Metal-Project-ID: prj_...`.
- Organization, member, project, API key, provider credential, billing, usage, and webhook management use a user access token. The two credential types are not interchangeable.
- Lifecycle and runtime mutations can return `202 Accepted` before provider work finishes. Persist the operation ID and wait until the operation is `succeeded`, `failed`, or `cancelled`.
- After an uncertain network result, retry a mutation with the same `Idempotency-Key` and identical input. Reusing a key with different input returns `idempotency_mismatch`.
- OpenMetal provides sandbox lifecycle, argv-based processes, binary file operations, and time-limited HTTP endpoints. It does not provide interactive terminals, streaming stdin, SSH, WebSocket, or a general connection API. Runtime support varies by provider.
- CPU sandboxes are available now. GPU workloads, browser computers, and persistent machines are planned but not available yet.
- Install the Agent Skill with `npx skills add superagent-ai/openmetal --skill openmetal`, the CLI with `npm install --global @openmetal/cli`, and the TypeScript SDK with `npm install @openmetal/sdk`.
- Never print API keys or place them in sandbox metadata, environment values, or process arguments.

Documentation links below point to Markdown versions of each page. API endpoint links open the rendered API reference. The complete documentation is also available as one file at https://www.openmetal.sh/llms-full.txt.

## Get started

- [Give your agent access to OpenMetal](https://www.openmetal.sh/llms.mdx/get-started/agents/content.md): Install the OpenMetal skill and CLI so your coding agent can provision portable sandboxes.
- [Authenticate requests](https://www.openmetal.sh/llms.mdx/get-started/authentication/content.md): Choose the correct credential for account management and compute routes.
- [Start with the CLI](https://www.openmetal.sh/llms.mdx/get-started/cli/content.md): Give agents and automation a stable command interface to OpenMetal.
- [Build an agent with TypeScript](https://www.openmetal.sh/llms.mdx/get-started/typescript/content.md): Embed OpenMetal sandbox workflows with the published TypeScript SDK.

## SDK and CLI

- [Agent skill](https://www.openmetal.sh/llms.mdx/sdk-and-cli/agent-skill/content.md): Give compatible coding agents exact OpenMetal workflows and safety rules.
- [CLI reference](https://www.openmetal.sh/llms.mdx/sdk-and-cli/cli/content.md): Configure OpenMetal profiles and automate production workloads from a terminal or CI.
- [TypeScript SDK](https://www.openmetal.sh/llms.mdx/sdk-and-cli/typescript-sdk/content.md): Build agent applications with the typed @openmetal/sdk client.

## Guides

- [Create a sandbox](https://www.openmetal.sh/llms.mdx/guides/create-sandbox/content.md): Provision portable compute and wait until it is ready.
- [Pause and resume a sandbox](https://www.openmetal.sh/llms.mdx/guides/pause-and-resume-sandbox/content.md): Suspend supported sandboxes and continue them through durable lifecycle operations.
- [Run a process](https://www.openmetal.sh/llms.mdx/guides/run-process/content.md): Execute an argv based command and consume ordered output.
- [Work with files](https://www.openmetal.sh/llms.mdx/guides/filesystem/content.md): Upload, download, list, and remove sandbox files without changing bytes.
- [Expose an HTTP endpoint](https://www.openmetal.sh/llms.mdx/guides/expose-endpoint/content.md): Create a time limited public route to a process in a sandbox.
- [Route across providers](https://www.openmetal.sh/llms.mdx/guides/routing-and-providers/content.md): Select automatic routing, explicit providers, fallback, and BYOK.
- [Prime Intellect sandboxes](https://www.openmetal.sh/llms.mdx/guides/prime-intellect/content.md): Run CPU VM sandboxes on Prime through OpenMetal.
- [Manage billing and credits](https://www.openmetal.sh/llms.mdx/guides/billing/content.md): Fund managed compute, understand charges, and configure automatic top ups.
- [Receive webhooks](https://www.openmetal.sh/llms.mdx/guides/webhooks/content.md): Deliver signed OpenMetal lifecycle events to your systems with retries and redelivery.
- [Webhook event catalog](https://www.openmetal.sh/llms.mdx/guides/webhooks/events/content.md): Every subscribable OpenMetal event type with signed payload examples.

## Concepts

- [What OpenMetal does](https://www.openmetal.sh/llms.mdx/concepts/what-is-metal/content.md): Understand the OpenMetal platform and its portable compute model.
- [Routing and capabilities](https://www.openmetal.sh/llms.mdx/concepts/routing/content.md): Understand candidate order, fallback safety, and current provider limits.
- [Authentication model](https://www.openmetal.sh/llms.mdx/concepts/authentication/content.md): Understand user sessions, project keys, and resource scope.
- [Asynchronous operations](https://www.openmetal.sh/llms.mdx/concepts/operations/content.md): Track accepted mutations, terminal states, events, and uncertain outcomes.

## API reference

- [OpenMetal API](https://www.openmetal.sh/llms.mdx/api-reference/content.md): Provision and manage portable compute through the production OpenMetal REST API.
- [OpenAPI specification](https://api.openmetal.sh/v1/openapi.json): Machine-readable OpenAPI 3.1 document with every route, schema, and error.

## Errors

- [Diagnose common errors](https://www.openmetal.sh/llms.mdx/errors/common-errors/content.md): Match stable error codes to safe recovery actions.

## Optional

- [Get Health](https://www.openmetal.sh/api-reference/endpoints/ops/getHealth): `GET /health`
- [Get Ready](https://www.openmetal.sh/api-reference/endpoints/ops/getReady): `GET /ready`
- [Get Meta](https://www.openmetal.sh/api-reference/endpoints/ops/getMeta): `GET /v1/meta`
- [List Organizations](https://www.openmetal.sh/api-reference/endpoints/organizations/listOrganizations): `GET /v1/organizations`
- [Create Organization](https://www.openmetal.sh/api-reference/endpoints/organizations/createOrganization): `POST /v1/organizations`
- [Get Organization](https://www.openmetal.sh/api-reference/endpoints/organizations/getOrganization): `GET /v1/organizations/{organization_id}`
- [Update Organization](https://www.openmetal.sh/api-reference/endpoints/organizations/updateOrganization): `PATCH /v1/organizations/{organization_id}`
- [Delete Organization](https://www.openmetal.sh/api-reference/endpoints/organizations/deleteOrganization): `DELETE /v1/organizations/{organization_id}`
- [List Organization Members](https://www.openmetal.sh/api-reference/endpoints/members/listOrganizationMembers): `GET /v1/organizations/{organization_id}/members`
- [Update Organization Member](https://www.openmetal.sh/api-reference/endpoints/members/updateOrganizationMember): `PATCH /v1/organizations/{organization_id}/members/{user_id}`
- [Remove Organization Member](https://www.openmetal.sh/api-reference/endpoints/members/removeOrganizationMember): `DELETE /v1/organizations/{organization_id}/members/{user_id}`
- [Create Organization Invitation](https://www.openmetal.sh/api-reference/endpoints/members/createOrganizationInvitation): `POST /v1/organizations/{organization_id}/invitations`
- [Update Organization Invitation](https://www.openmetal.sh/api-reference/endpoints/members/updateOrganizationInvitation): `PATCH /v1/organizations/{organization_id}/invitations/{invitation_id}`
- [Revoke Organization Invitation](https://www.openmetal.sh/api-reference/endpoints/members/revokeOrganizationInvitation): `DELETE /v1/organizations/{organization_id}/invitations/{invitation_id}`
- [Resend Organization Invitation](https://www.openmetal.sh/api-reference/endpoints/members/resendOrganizationInvitation): `POST /v1/organizations/{organization_id}/invitations/{invitation_id}/resend`
- [Get Organization Billing](https://www.openmetal.sh/api-reference/endpoints/billing/getOrganizationBilling): `GET /v1/organizations/{organization_id}/billing`
- [Quote Credit Purchase](https://www.openmetal.sh/api-reference/endpoints/billing/quoteCreditPurchase): `GET /v1/organizations/{organization_id}/billing/quote`
- [Create Billing Checkout](https://www.openmetal.sh/api-reference/endpoints/billing/createBillingCheckout): `POST /v1/organizations/{organization_id}/billing/checkout`
- [Update Auto Topup](https://www.openmetal.sh/api-reference/endpoints/billing/updateAutoTopup): `PUT /v1/organizations/{organization_id}/billing/auto-topup`
- [Create Billing Payment Method Setup](https://www.openmetal.sh/api-reference/endpoints/billing/createBillingPaymentMethodSetup): `POST /v1/organizations/{organization_id}/billing/payment-method`
- [Get Organization Usage](https://www.openmetal.sh/api-reference/endpoints/usage/getOrganizationUsage): `GET /v1/organizations/{organization_id}/usage`
- [List Projects](https://www.openmetal.sh/api-reference/endpoints/projects/listProjects): `GET /v1/organizations/{organization_id}/projects`
- [Create Project](https://www.openmetal.sh/api-reference/endpoints/projects/createProject): `POST /v1/organizations/{organization_id}/projects`
- [Get Project](https://www.openmetal.sh/api-reference/endpoints/projects/getProject): `GET /v1/projects/{project_id}`
- [Update Project](https://www.openmetal.sh/api-reference/endpoints/projects/updateProject): `PATCH /v1/projects/{project_id}`
- [Delete Project](https://www.openmetal.sh/api-reference/endpoints/projects/deleteProject): `DELETE /v1/projects/{project_id}`
- [List Provider Credentials](https://www.openmetal.sh/api-reference/endpoints/provider-credentials/listProviderCredentials): `GET /v1/organizations/{organization_id}/provider-credentials`
- [Remove Provider Credential](https://www.openmetal.sh/api-reference/endpoints/provider-credentials/removeProviderCredential): `DELETE /v1/organizations/{organization_id}/provider-credentials/{provider}`
- [Configure Provider Credential](https://www.openmetal.sh/api-reference/endpoints/provider-credentials/configureProviderCredential): `PUT /v1/organizations/{organization_id}/provider-credentials/{provider}`
- [List Project Api Keys](https://www.openmetal.sh/api-reference/endpoints/api-keys/listProjectApiKeys): `GET /v1/projects/{project_id}/api-keys`
- [Create Project Api Key](https://www.openmetal.sh/api-reference/endpoints/api-keys/createProjectApiKey): `POST /v1/projects/{project_id}/api-keys`
- [Delete Project Api Key](https://www.openmetal.sh/api-reference/endpoints/api-keys/deleteProjectApiKey): `DELETE /v1/projects/{project_id}/api-keys/{api_key_id}`
- [Revoke Project Api Key](https://www.openmetal.sh/api-reference/endpoints/api-keys/revokeProjectApiKey): `POST /v1/projects/{project_id}/api-keys/{api_key_id}/revoke`
- [List Project Sandboxes](https://www.openmetal.sh/api-reference/endpoints/sandboxes/listProjectSandboxes): `GET /v1/projects/{project_id}/sandboxes`
- [Pause Project Sandbox](https://www.openmetal.sh/api-reference/endpoints/sandboxes/pauseProjectSandbox): `POST /v1/projects/{project_id}/sandboxes/{sandbox_id}/pause`
- [Destroy Project Sandbox](https://www.openmetal.sh/api-reference/endpoints/sandboxes/destroyProjectSandbox): `DELETE /v1/projects/{project_id}/sandboxes/{sandbox_id}`
- [List Sandboxes](https://www.openmetal.sh/api-reference/endpoints/sandboxes/listSandboxes): `GET /v1/sandboxes`
- [Create Sandbox](https://www.openmetal.sh/api-reference/endpoints/sandboxes/createSandbox): `POST /v1/sandboxes`
- [Get Sandbox](https://www.openmetal.sh/api-reference/endpoints/sandboxes/getSandbox): `GET /v1/sandboxes/{sandbox_id}`
- [Destroy Sandbox](https://www.openmetal.sh/api-reference/endpoints/sandboxes/destroySandbox): `DELETE /v1/sandboxes/{sandbox_id}`
- [Pause Sandbox](https://www.openmetal.sh/api-reference/endpoints/sandboxes/pauseSandbox): `POST /v1/sandboxes/{sandbox_id}/actions/pause`
- [Resume Sandbox](https://www.openmetal.sh/api-reference/endpoints/sandboxes/resumeSandbox): `POST /v1/sandboxes/{sandbox_id}/actions/resume`
- [Create Sandbox Process](https://www.openmetal.sh/api-reference/endpoints/runtime/createSandboxProcess): `POST /v1/sandboxes/{sandbox_id}/processes`
- [Get Sandbox Process](https://www.openmetal.sh/api-reference/endpoints/runtime/getSandboxProcess): `GET /v1/sandboxes/{sandbox_id}/processes/{process_id}`
- [Stream Sandbox Process Events](https://www.openmetal.sh/api-reference/endpoints/runtime/streamSandboxProcessEvents): `GET /v1/sandboxes/{sandbox_id}/processes/{process_id}/events`
- [Cancel Sandbox Process](https://www.openmetal.sh/api-reference/endpoints/runtime/cancelSandboxProcess): `POST /v1/sandboxes/{sandbox_id}/processes/{process_id}/actions/cancel`
- [Read Sandbox File](https://www.openmetal.sh/api-reference/endpoints/runtime/readSandboxFile): `POST /v1/sandboxes/{sandbox_id}/filesystem/read`
- [Write Sandbox File](https://www.openmetal.sh/api-reference/endpoints/runtime/writeSandboxFile): `POST /v1/sandboxes/{sandbox_id}/filesystem/write`
- [List Sandbox Files](https://www.openmetal.sh/api-reference/endpoints/runtime/listSandboxFiles): `POST /v1/sandboxes/{sandbox_id}/filesystem/list`
- [Delete Sandbox File](https://www.openmetal.sh/api-reference/endpoints/runtime/deleteSandboxFile): `POST /v1/sandboxes/{sandbox_id}/filesystem/delete`
- [Get Sandbox Runtime Operation](https://www.openmetal.sh/api-reference/endpoints/runtime/getSandboxRuntimeOperation): `GET /v1/sandboxes/{sandbox_id}/runtime-operations/{runtime_operation_id}`
- [List Sandbox Endpoints](https://www.openmetal.sh/api-reference/endpoints/runtime/listSandboxEndpoints): `GET /v1/sandboxes/{sandbox_id}/endpoints`
- [Create Sandbox Endpoint](https://www.openmetal.sh/api-reference/endpoints/runtime/createSandboxEndpoint): `POST /v1/sandboxes/{sandbox_id}/endpoints`
- [Revoke Sandbox Endpoint](https://www.openmetal.sh/api-reference/endpoints/runtime/revokeSandboxEndpoint): `DELETE /v1/sandboxes/{sandbox_id}/endpoints/{endpoint_id}`
- [Get Operation](https://www.openmetal.sh/api-reference/endpoints/operations/getOperation): `GET /v1/operations/{operation_id}`
- [Stream Operation Events](https://www.openmetal.sh/api-reference/endpoints/operations/streamOperationEvents): `GET /v1/operations/{operation_id}/events`
- [List Events](https://www.openmetal.sh/api-reference/endpoints/events/listEvents): `GET /v1/events`
- [List Webhook Endpoints](https://www.openmetal.sh/api-reference/endpoints/webhooks/listWebhookEndpoints): `GET /v1/organizations/{organization_id}/webhooks`
- [Create Webhook Endpoint](https://www.openmetal.sh/api-reference/endpoints/webhooks/createWebhookEndpoint): `POST /v1/organizations/{organization_id}/webhooks`
- [Get Webhook Endpoint](https://www.openmetal.sh/api-reference/endpoints/webhooks/getWebhookEndpoint): `GET /v1/organizations/{organization_id}/webhooks/{webhook_id}`
- [Update Webhook Endpoint](https://www.openmetal.sh/api-reference/endpoints/webhooks/updateWebhookEndpoint): `PATCH /v1/organizations/{organization_id}/webhooks/{webhook_id}`
- [Delete Webhook Endpoint](https://www.openmetal.sh/api-reference/endpoints/webhooks/deleteWebhookEndpoint): `DELETE /v1/organizations/{organization_id}/webhooks/{webhook_id}`
- [Rotate Webhook Secret](https://www.openmetal.sh/api-reference/endpoints/webhooks/rotateWebhookSecret): `POST /v1/organizations/{organization_id}/webhooks/{webhook_id}/rotate`
- [Test Webhook Endpoint](https://www.openmetal.sh/api-reference/endpoints/webhooks/testWebhookEndpoint): `POST /v1/organizations/{organization_id}/webhooks/{webhook_id}/test`
- [List Webhook Deliveries](https://www.openmetal.sh/api-reference/endpoints/webhooks/listWebhookDeliveries): `GET /v1/organizations/{organization_id}/webhooks/{webhook_id}/deliveries`
- [Redeliver Webhook Delivery](https://www.openmetal.sh/api-reference/endpoints/webhooks/redeliverWebhookDelivery): `POST /v1/organizations/{organization_id}/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`
- [Privacy Policy](https://www.openmetal.sh/llms.mdx/privacy/content.md): How OpenMetal collects, uses, discloses, and protects personal information.
- [Terms of Service](https://www.openmetal.sh/llms.mdx/terms/content.md): Terms governing access to and use of OpenMetal.