# Promigence documentation, complete > Every page of the Promigence docs in one file, in reading order. Each page is also at its own address, and as > markdown at that address with `.md` added. The index of the docs: https://www.promigence.ai/docs/llms.txt ## Contents - [Docs overview](https://www.promigence.ai/docs): Start here, then pick a reference - [Quickstart](https://www.promigence.ai/docs/quickstart): Install the CLI, sign up, build a verified snapshot, quote a run, start 20 sandboxes from it and read their validity report - [Limits and notices](https://www.promigence.ai/docs/limits): What your account can run, and what happens when it reaches a limit: a spend cap that pauses a sandbox, the time a paused sandbox is kept, the monthly allowance for data sent out, a stop by support, and the notices you get about each - [CLI reference](https://www.promigence.ai/docs/cli): Every command and flag of the CLI (version 0.1.0-beta.14) - [API reference](https://www.promigence.ai/docs/reference/api): All the REST API's routes, from the published contract, with one page per group - [TypeScript SDK](https://www.promigence.ai/docs/sdk): The native TypeScript client, plus a compatibility Sandbox class for existing sandbox code - [Python SDK](https://www.promigence.ai/docs/sdk-python): The promigence package for Python 3.9 or newer: a Sandbox class for one sandbox and a client for the rest of the API, sync or async - [Errors and exit codes](https://www.promigence.ai/docs/errors): Each error code and exit code: whose failure it was, whether it was billed, and the fix - [API reference: Meta](https://www.promigence.ai/docs/reference/api/meta): Service health and status, and the agent guide as plain text - [API reference: Snapshots](https://www.promigence.ai/docs/reference/api/snapshots): Build snapshots and check them, move their aliases, delete them, turn an image tag into a digest, and list the templates - [API reference: GitHub](https://www.promigence.ai/docs/reference/api/github): Connect GitHub accounts and list the repositories they can read - [API reference: GitLab](https://www.promigence.ai/docs/reference/api/gitlab): Connect GitLab read-only and list the projects it can read - [API reference: Runs](https://www.promigence.ai/docs/reference/api/runs): Price a run before it starts, start it, follow it, cancel it, replay its environment failures and read its validity report - [API reference: Sandboxes](https://www.promigence.ai/docs/reference/api/sandboxes): Extend, pause, resume or end a sandbox, save it as a snapshot, or cut its network - [API reference: Execs](https://www.promigence.ai/docs/reference/api/execs): Run commands in a sandbox: buffered, streamed or in the background - [API reference: Files](https://www.promigence.ai/docs/reference/api/files): Files in a sandbox, from reading and writing them to searching, moving and archiving - [API reference: Ports and terminal](https://www.promigence.ai/docs/reference/api/ports-and-terminal): Preview URLs for ports, a terminal, and SSH - [API reference: Secrets](https://www.promigence.ai/docs/reference/api/secrets): Store and remove secrets by name - [API reference: Organisation](https://www.promigence.ai/docs/reference/api/organisation): Your account and its limits, the organizations you belong to with their members and team invites, the projects inside them with their monthly spend caps, and the audit log of who did what - [API reference: Billing](https://www.promigence.ai/docs/reference/api/billing): Your plan, this month's usage, the price list, the free credit and referrals - [API reference: Keys and sign-in](https://www.promigence.ai/docs/reference/api/keys-and-sign-in): Sign in from the CLI; create and revoke API keys - [Guides](https://www.promigence.ai/docs/guides): Step by step: run a coding agent, an agent framework or an eval harness in a Promigence sandbox, from installing it to reading what it did, with every command to copy. - [A GitHub Actions runner in two lines](https://www.promigence.ai/docs/guides/github-actions-runner): Move GitHub Actions jobs to Promigence sandboxes with one workflow line, on runners we host or ones you start with one command, and run GitLab CI jobs the same way with a tagged runner. - [Build an MCP server with an execute tool backed by a sandbox](https://www.promigence.ai/docs/guides/mcp-execute-tool): A complete MCP server in TypeScript and Python whose execute tool runs model-written code in a Promigence sandbox of its own per session, with no network, a spend cap and a timeout. - [Give every user of your product their own sandbox](https://www.promigence.ai/docs/guides/sandbox-per-user): Run each user's code in a sandbox of their own: a key for your backend, a project with a monthly cap, a sandbox found again by the user's id, paused when idle and capped in dollars, and the self-host question answered. - [Run AI security-testing agents against a fresh copy of your own application](https://www.promigence.ai/docs/guides/ai-pentest-fresh-target): Build your application into a Promigence snapshot once, then give your security-testing agent a fresh copy of it for every run, behind an outbound allow-list that names only your model API, with the model key kept out and a spend cap on the run. - [Run Claude Agent SDK agents in a Promigence sandbox](https://www.promigence.ai/docs/guides/claude-agent-sdk): Keep the Claude Agent SDK loop in your process and run Claude Code itself inside a Promigence sandbox, with your Anthropic key stored as a secret. - [Run Claude Code, Codex or OpenCode in a sandbox](https://www.promigence.ai/docs/guides/claude-code-and-codex): Start a coding agent in its own Promigence sandbox with one command, keep the model key off the command line, and drive sandboxes from Claude Code. - [Run Google ADK agents in a Promigence sandbox](https://www.promigence.ai/docs/guides/google-adk): Point a Google ADK agent's environment tools or code executor at a Promigence sandbox, so its commands and code run there. - [Run Harbor tasks in a Promigence sandbox](https://www.promigence.ai/docs/guides/harbor): Select Promigence in Harbor with one flag to run Terminal-Bench and other Harbor tasks in cloud sandboxes, each trial in its own copy. - [Run Inspect evals in a Promigence sandbox](https://www.promigence.ai/docs/guides/inspect-evals): Use sandbox="promigence" in Inspect to give every sample its own cloud sandbox, with Docker-style tasks running unchanged. - [Run LangChain Deep Agents in a Promigence sandbox](https://www.promigence.ai/docs/guides/langchain): Use a Promigence sandbox as the backend for a LangChain Deep Agent, or as the sandbox provider for deepagents-code. - [Run LLM-generated code safely](https://www.promigence.ai/docs/guides/run-ai-written-code-safely): Give each user or session its own sandbox, decide what it may reach on the network, cap its spend and time, keep credentials out of it, and end it when done. - [Run OpenAI Agents SDK agents in a Promigence sandbox](https://www.promigence.ai/docs/guides/openai-agents-sdk): Give an OpenAI Agents SDK SandboxAgent a Promigence sandbox, so its shell and file tools run there instead of on your machine. - [Run Strands agents in a Promigence sandbox](https://www.promigence.ai/docs/guides/strands): Give a Strands agent a Promigence sandbox, so its shell and file-editor tools run there with output streamed back as it is written. - [Run Vercel AI SDK agents in a Promigence sandbox](https://www.promigence.ai/docs/guides/vercel-ai-sdk): Pass a Promigence sandbox to the Vercel AI SDK as experimental_sandbox, or to bash-tool, so an agent's commands and files live there. - [Snapshot after npm install, then fork 10 copies](https://www.promigence.ai/docs/guides/snapshot-and-fork): Install dependencies once in a sandbox, take a snapshot of it while it runs, and start ten parallel attempts from that snapshot, in TypeScript, Python or the CLI. - [Migrate](https://www.promigence.ai/docs/migrate): Move code written for another sandbox provider to Promigence, and see which calls change. - [Moving from Runloop to Promigence](https://www.promigence.ai/docs/migrate/migrate-from-runloop-to-promigence): Move Runloop devboxes and blueprints to Promigence sandboxes: a concept map, the same code in TypeScript and Python, and checks that prove the move. --- Page: https://www.promigence.ai/docs # Everything you need to run a verified environment Promigence is a sandbox platform for AI agents: production-grade, isolated sandboxes that start in milliseconds, stay fast at a thousand at once, and bill by the second. The golden path bash ``` $ npm i -g promigence $ promigence signup # in your browser: sign up, then authorize the CLI $ promigence credits claim # claim your free credit $ promigence run --snapshot promigence/base --count 2 --cap 1 --json -- python3 -c 'print(6*7)' ``` - [Quickstart: From npm install to a verified snapshot and a 20-sandbox run.](https://www.promigence.ai/docs/quickstart) - [CLI reference: Every command, and every flag it matters to know.](https://www.promigence.ai/docs/cli) - [API reference: Every route of the published API, with its parameters, request body and answer.](https://www.promigence.ai/docs/reference/api) - [TypeScript SDK: The native client, and a compatibility Sandbox class so most existing sandbox code keeps working.](https://www.promigence.ai/docs/sdk) - [Errors and exit codes: What each failure means, whether it was billed, and whether it was yours or ours.](https://www.promigence.ai/docs/errors) - [Limits and notices: Your account's limits, paused sandboxes, data out, spend caps, support stops and CI jobs.](https://www.promigence.ai/docs/limits) ## If you are an AI agent reading this Run `promigence agent-guide`. It prints a ~1,200-token guide written for you rather than for a human: the command surface, the error codes, and the cost model. `--install` writes it into AGENTS.md or CLAUDE.md, .claude/skills and .cursor/rules. Plain-text sources for machine consumption: [/llms.txt](https://www.promigence.ai/llms.txt) for the index, [/llms-full.txt](https://www.promigence.ai/llms-full.txt) for the complete site as one document, [/docs/llms-full.txt](https://www.promigence.ai/docs/llms-full.txt) for these docs in one file, and [/facts.json](https://www.promigence.ai/facts.json) for the structured facts, pricing and measurements. Add `.md` to any page's address for the page as markdown. [/templates.json](https://www.promigence.ai/templates.json) lists every template you can start a sandbox from, with what it has installed and its size, and [/openapi.json](https://www.promigence.ai/openapi.json) is the API contract. --- Page: https://www.promigence.ai/docs/quickstart # From nothing to 20 verified episodes Five steps, about ten minutes, most of it the first snapshot build. Your free credit covers a first run like this, and there is no card to add. ## Install and sign up Install the CLI from npm: one package, the CLI and the TypeScript SDK together. `promigence signup` opens your browser: a new account sees a short welcome, and then you authorize the CLI, which stores your API key for you (`promigence login` signs in to an account you already have). Then claim your free credit in the browser: until it is claimed, a first run stops with `credit_unclaimed`. A key you already have is best read from an environment variable or stdin (`promigence auth login --from-env VAR`): a key on a command line lands in shell history and every process listing. Our servers are on the US East Coast. From far away, each call adds your network's round trip. Terminal ``` npm i -g promigence promigence signup # in your browser: sign up, then authorize the CLI promigence credits claim # claim your free credit promigence doctor ``` ## Build a verified snapshot Start from an image with git and your toolchain, clone your repository at a pinned commit, add the setup steps and a verify command. If verify does not exit zero, nothing is stored. Either way the build is billed per second at its size's rate for the time it runs, at most an hour, so a small build costs at most $0.17; a build that fails on our side is not billed. Pin the commit: a snapshot built from a moving ref is not reproducible. Terminal ``` promigence snapshot create \ --image node:22 \ --setup "git clone https://github.com// /work/repo && git -C /work/repo checkout <40-char sha>" \ --setup "cd /work/repo && npm ci" \ --verify "cd /work/repo && npm test" \ --tier small --alias myapp --wait --wait-timeout 10m ``` ## Price the run before you start it A quote is a ceiling, not an estimate: every sandbox running for its whole timeout. --cap enforces it: a run that would exceed the cap is refused outright, before anything starts. Terminal ``` promigence run quote --snapshot myapp --count 20 --timeout 15m # → 20 × small (2 vCPU, 4 GiB) for up to 15 minutes each # → max cost $0.83 ``` ## Fork, execute, report One command forks N environments, runs your command in each, and prints the validity report. A new account runs 20 sandboxes at once. Terminal ``` promigence run \ --snapshot myapp \ --count 20 --cap 1 \ -- sh -c "cd /work/repo && npm test" # → the validity report: completed, task failures, environment failures, and the cost ``` ## Read the report, open a failure A task failure is yours: your command exited non-zero. An environment failure is ours: it never counts against your agent. It is not billed before the sandbox reaches you; after that, when our side shows the failure was ours, the work since its last snapshot (or since it started), up to 24 hours, is credited back. An environment failure can be replayed, as a new sandbox billed like any other, and any failure can be reproduced from the command the report prints with --repro. Terminal ``` promigence run report --sandboxes failed promigence run report --sandbox --repro # the command that reproduces it ``` ## Next - [Every command and flag](https://www.promigence.ai/docs/cli) - [Do the same thing from TypeScript](https://www.promigence.ai/docs/sdk) - [What each error code means and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/limits # Limits and notices What your account may run, what happens at each limit, and what you are told when it does. A request over a limit is refused before anything starts, with an error code that names the limit and a fix that says what to do. ## Your account's limits Every account has limits: how many sandboxes run at once, the longest a sandbox may run, the largest size, data out a month and how much it keeps stored. `promigence pricing` shows your account's prices and limits; `promigence me` shows what is in use. A new account runs 20 sandboxes at once, each for up to an hour (15 minutes unless `--timeout` asks for more), on sizes up to large (8 vCPU), with 20 GB of data out a month. Over a limit, the request is refused before anything starts: `concurrency_limit`, `tier_over_plan`, `storage_limit_reached` or `egress_cap_reached`. To raise a limit, email support@promigence.ai. Terminal ``` promigence pricing # your prices and limits promigence me # your account, and what is in use ``` ## Welcome and setup questions A new account starts with a short welcome in the browser: a few questions about you and what you are building. If your account has setup questions to answer first, a command that starts new work (a run, a snapshot build, a verify) stops with `setup_required` (HTTP 403, exit 7) and a link to the questions; nothing is started or charged. Answer them, which takes under a minute, and run the command again. Everything else keeps working meanwhile: commands and files in sandboxes that are already running, pause and resume, reads, keys and billing. ## Spend caps and credit A run's spend cap (`--cap`, or `spend_cap` in the API) is a hard limit. A run whose quote is over its cap is refused before it starts (`cap_exceeded`); `promigence run quote` shows the quote first. A sandbox that reaches its run's cap while it runs is paused with its files and state kept: paused time is not billed, the sandbox shows `pause_reason: spend_cap`, and calls to it answer `cap_paused`. Raise the cap to go on, or end it: Terminal ``` promigence sandbox resume --cap # go on, under a higher cap promigence sandbox kill # or end it ``` A trial whose credits run out is paused the same way (`credits_paused`) and goes on once credits are added. A sandbox that cannot be paused is stopped at the cap, billed up to the cap and never past it. ## Paused sandboxes A paused sandbox is not billed by the second and does not count against your concurrency limit. It is kept for 30 days, and resuming it starts the 30 days again. - While it is paused, its `pause_expires_at` says when it will be deleted, with its files (`promigence sandbox info --json`, the API and the SDK). - In its last 7 days, the console shows the date on the sandbox, and an email goes to the organization's owner 7 days and 1 day before. - A paused sandbox that reaches its 30 days is deleted and ends `expired`. Resume it before then to keep it. ## Data out Each organization has a monthly data-out allowance. When the organization reaches it: - its sandboxes lose internet access but keep running: their commands and files still work through the CLI, the SDK and the API; - their terminals and SSH sessions end, and new ones are refused until internet access comes back; - new runs that need internet access are refused with `egress_cap_reached` (HTTP 403, exit 10); runs with `--network none` still start; - an email goes to the organization's owner, at most one a day. Everything comes back on the 1st of the month, 00:00 UTC. For more data out a month, email support@promigence.ai. A project that reaches its monthly spend cap has its sandboxes' internet access cut the same way; an owner raising the project's cap restores it for new sandboxes. ## Stopped by Promigence support Promigence support can stop a sandbox or a run, for example when it breaks our terms or when you ask. It ends `stopped_by_support` (exit 12) with the reason in its message: `promigence sandbox info ` and the console's page for the sandbox show it, and `promigence run status` counts it. The seconds it ran are billed, as a kill is, unless support found the cause was on our side: then the work since its last snapshot (or since it started), up to 24 hours, is credited back. Questions: email support@promigence.ai with the sandbox id. ## CI jobs With Promigence Runners on (CI, in the console), each CI job has its own page in the console: its repository, workflow, branch, commit and who started it; how long it waited for a runner, how long the runner took to be ready and how long it ran; the runner's size and what it cost; and, for a GitHub job, its steps and its log. If a GitHub organization you connected has not accepted the Promigence App's updated permissions, the Runners page says so and links to the page on GitHub where an owner of that organization accepts them. Its repositories stay listed, and their jobs wait until then. [Every error code, and whether it was billed](https://www.promigence.ai/docs/errors) · [every command](https://www.promigence.ai/docs/cli) · [every API route](https://www.promigence.ai/docs/reference/api) --- Page: https://www.promigence.ai/docs/cli # promigence CLI reference The commands of the CLI on npm, version 0.1.0-beta.14. Install: `npm i -g promigence`, then `promigence signup` ## Global flags - `--json`, One JSON document on stdout (default when stdout is not a TTY, except exec --sandbox: --json or PROMIGENCE_OUTPUT=json there) - `--text`, Human text: a result on stdout, an error on stderr - `--api-key K`, Precedence: --api-key > PROMIGENCE_API_KEY > the stored sign-in - `--request-timeout DUR`, How long one API request may take (default 30s); PROMIGENCE_REQUEST_TIMEOUT - `--version`, Print the version - `--help`, This help; `promigence --help` for one command ## Setup Sign up, check the install, and get an agent oriented in about 1,200 tokens. ### `promigence login` Signs you up or signs you in, by email or with GitHub or Google where those are enabled: it opens your browser, where you sign in and authorize the CLI, and saves a new API key on this machine. The key an earlier login saved here is revoked. - `--provider NAME`, Use this sign-in method (`email`, or `github` or `google` where enabled) instead of choosing in the browser - `--no-browser`, Print the sign-in link instead of opening a browser, then paste back the code shown after you sign in - `--key-name N`, Name for the new API key. Default: `cli@` - `--api-url URL`, Sign in to the API at URL instead of the default, without asking for confirmation - `--yes`, Use a non-default API set in `PROMIGENCE_API_URL` without asking for confirmation - `--ref CODE`, Referral code, applied only if this creates a new account - `--json`, Print the result as JSON, even in a terminal ### `promigence signup` Creates a new account in your browser and saves an API key on this machine. A new account sees a short welcome before it authorizes the CLI. - `--invite CODE`, Your invite code, for a sign-up that asks for it in the terminal; where the browser asks for it, enter it there (other users can see command-line arguments) - `--provider NAME`, Use this sign-in method (`email`, or `github` or `google` where enabled) instead of choosing in the browser - `--no-browser`, Print the sign-up link instead of opening a browser, then paste back the code shown when you finish - `--key-name N`, Name for the new API key. Default: `cli@` - `--api-url URL`, Sign up on the API at URL instead of the default, without asking for confirmation - `--yes`, Use a non-default API set in `PROMIGENCE_API_URL` without asking for confirmation - `--ref CODE`, Referral code, applied only if this creates a new account - `--json`, Print the result as JSON, even in a terminal ### `promigence logout` Removes the API key saved on this machine. If `promigence login` created that key, it is revoked too, so it stops working everywhere. - `--keep-key`, Only remove the key from this machine; it keeps working - `--json`, Print the result as JSON, even in a terminal ### `promigence auth login` Saves an API key you already have on this machine. It reads the key from an environment variable (`--from-env VAR`) or from standard input, so the key stays off the command line. - `--from-env VAR`, Read the key from the environment variable VAR - `--api-key K`, The key itself, on the command line; accepted with a warning, because other users can see it there ### `promigence keys list` Lists the API keys in the project your current key belongs to, showing when each was created and last used and when it expires. Add `--project` to list another project's keys. - `--all`, Include revoked keys - `--project P`, List this project's keys instead (you sign in first) - `--org ORG`, With `--project`: the organization that project is in - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence keys create` Creates a new API key and prints its secret. The secret is shown only this once, so store it straight away. - `--name N`, Name for the key, for example `ci-prod`. Default: `cli@` - `--org ORG`, Organization to create the key in; naming one other than your current key's signs you in. Default: your current key's organization - `--project P`, Create the key in this project (you sign in first) - `--service`, Make a service key for CI that keeps working after you leave the organization (owners only; you sign in first) - `--access A`, What the key may do: `full` (the default); `run` (sandboxes, runs and builds, but no changes to secrets, keys or billing); or `read` (reads everything, files and output included, and changes nothing) - `--expires WHEN`, When the key stops working: a lifetime such as `1h`, `30d` or `1y`, a date, or a UTC time such as `2027-01-31T12:00:00Z`. Default: never - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence keys revoke KEY_ID` Revokes an API key so it no longer works. Keys that were created with it are revoked too. - `--project P`, The project the key is in, if not your current key's (you sign in first) - `--org ORG`, With `--project`: the organization that project is in - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence org list` Lists your organizations, marking your default one with `*`. Without `--all` it lists only your current key's organization. - `--all`, List every organization you belong to (you sign in first) - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence org create NAME` Creates a new organization with you as its owner; you sign in first. It gets no free trial credit, so add a card before its first run. - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence org switch ORG` Signs you in, makes ORG your default organization and saves a new API key for it on this machine. The key an earlier sign-in saved here is revoked unless you pass `--keep-old-key`. - `--project P`, Project for the new key - `--keep-old-key`, Keep the replaced key working instead of revoking it - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence org members` Lists the members of your organization and their roles. - `--org ORG`, Use an organization other than the one your current key belongs to (you sign in first) - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence org invite EMAIL` Invites someone to your organization by email; they accept with `promigence org join`. Only owners can invite, and you sign in first. - `--role R`, Role to give them: `owner` or `member`. Default: member - `--org ORG`, Use an organization other than the one your current key belongs to - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence org invites` Lists your organization's pending invites, which expire after 14 days. Add `--mine` to see the invites sent to you instead. - `--mine`, List the invites sent to you instead (you sign in first) - `--org ORG`, Use an organization other than the one your current key belongs to (you sign in first) - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence org uninvite INVITE_ID` Withdraws a pending invite so it can no longer be accepted. Only owners can do this, and you sign in first. - `--org ORG`, Use an organization other than the one your current key belongs to - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence org resend INVITE_ID` Send an invite again (owners). - `--org ORG`, Another org than this key's - `--no-browser`, Sign in headless (or PROMIGENCE_ID_TOKEN) - `--yes`, Sign in to PROMIGENCE_API_URL without the prompt - `--json`, Force the JSON envelope ### `promigence org role USER_ID ROLE` Sets a member's role to `owner` or `member`; the last owner cannot be demoted. Only owners can change roles, and you sign in first. - `--org ORG`, Use an organization other than the one your current key belongs to - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence org remove USER_ID` Removes a member from your organization and revokes their API keys there; service keys keep working. Only owners can do this, and you sign in first. - `--org ORG`, Use an organization other than the one your current key belongs to - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence org leave [ORG]` Leaves an organization and revokes your API keys in it; without ORG, it leaves the one your current key belongs to. Leaving an organization other than your current key's signs you in first. - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence org join INVITE_ID` Accepts an invite and makes you a member of that organization. You sign in first, with the email address the invite was sent to. - `--decline`, Decline the invite instead of accepting it - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence org audit` Shows your organization's audit log, newest first: who did what, and when. Only owners can read it, and only when signed in rather than with an API key, so run it with `--sign-in`. - `--before SEQ`, Show entries older than SEQ (an entry's sequence number), to page back through the log - `--limit N`, How many entries to show, at most 100. Default: 100 - `--org ORG`, Use an organization other than the one your current key belongs to - `--sign-in`, Sign in in your browser; the log is read as you, never with an API key - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence org rename ORG NAME` Rename it (owners). - `--no-browser`, Sign in headless (or PROMIGENCE_ID_TOKEN) - `--yes`, Sign in to PROMIGENCE_API_URL without the prompt - `--json`, Force the JSON envelope ### `promigence org delete ORG` Deletes an organization and revokes all of its API keys. Only owners can do this; you sign in first and confirm with the organization's name. - `--confirm NAME`, The organization's name, typed again to confirm (required) - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence project list` Lists the projects in your organization and what each has spent this month. Every API key belongs to one project. - `--month YYYY-MM`, Show another month's spend, as `YYYY-MM` - `--org ORG`, Use an organization other than the one your current key belongs to (you sign in first) - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence project create NAME` Creates a project in your organization. To work in it, create a key with `promigence keys create --project NAME`. - `--org ORG`, Use an organization other than the one your current key belongs to (you sign in first) - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence project rename PROJECT NAME` Renames a project. The `default` project cannot be renamed. - `--org ORG`, Use an organization other than the one your current key belongs to (you sign in first) - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence project delete PROJECT` Deletes an empty project: its keys must be revoked, its snapshots deleted and nothing in it still running. Only owners can do this (you sign in first), and the `default` project cannot be deleted. - `--org ORG`, Use an organization other than the one your current key belongs to - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence project cap PROJECT USD|off` Sets the most a project may spend in a month (UTC), in USD, or removes the cap with `off`; new work that would go past it is refused. Only owners can do this, and you sign in first. - `--org ORG`, Use an organization other than the one your current key belongs to - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence project move PROJECT` Moves a project, with its snapshots and secrets, to another organization and revokes all of its API keys. Only owners can do this (you sign in first); past runs and their usage stay with the original organization. - `--to ORG`, The organization to move it to (required): one you belong to, with a card on file - `--org ORG`, The organization the project is in now, if not your current key's - `--no-browser`, Sign in without opening a browser on this machine, by pasting back a code (scripts can set `PROMIGENCE_ID_TOKEN`) - `--yes`, Sign in to the API set in `PROMIGENCE_API_URL` without asking for confirmation - `--json`, Print the result as JSON, even in a terminal ### `promigence me` Shows your account at a glance: organization, plan, sandboxes in use against your concurrency limit, trial credit left, spend so far, default spend cap and limits. - `--json`, Print the result as JSON, even in a terminal ### `promigence billing card` Prints a checkout link for adding a payment card (owners only). Nothing is charged when you add it, and any trial credit left is used before the card is billed. - `--json`, Print the result as JSON, even in a terminal ### `promigence doctor` Checks that the CLI is ready to use: the Node.js version, your API key and where it comes from, and whether the API is reachable and accepts the key. Each failed check says how to fix it. - `--json`, Print the result as JSON, even in a terminal ### `promigence ping` Your distance to our servers. - `--json`, Force the JSON envelope ### `promigence init` Writes a `promigence.toml` that describes how to build a snapshot of the repository in the current directory: the commit to pin, and setup and verify commands inferred from its lockfile and project files. Every inferred value is printed and can be overridden with a flag. - `--repo U`, Git URL of the repository. Default: the `origin` remote - `--commit SHA`, Commit to pin, as a full 40-character SHA. Default: HEAD - `--setup CMD`, Setup command to use instead of the inferred one; repeat the flag for several steps - `--verify CMD`, Verify command to use instead of the inferred one - `--tier xsmall|small|medium|large-16|large|xlarge|2xlarge`, Size of the sandboxes this snapshot runs in. Default: medium - `--force`, Overwrite an existing `promigence.toml` - `--print`, Print what would be written, without writing anything - `--json`, Print the result as JSON, even in a terminal ### `promigence examples` Lists public snapshots you can start sandboxes from right away, with no build of your own; if none are published, it shows the built-in `promigence/base`. It needs no API key. - `--limit N`, How many snapshots to list. Default: 20 - `--bundle`, Write each public snapshot to a `.promigence` file in the current directory (none are published yet) - `--json`, Print the result as JSON, even in a terminal ### `promigence templates` The templates: ready-made starting points to fork (no auth). - `--json`, Force the JSON envelope ### `promigence templates show NAME` One template: everything it has installed, and its versions (no auth). - `--packages`, List every installed package, not only the count - `--json`, Force the JSON envelope ### `promigence agent-guide` Prints a short guide to the CLI, about 1,200 tokens, for an AI agent to read before it uses Promigence. `--section commands|errors|cost` prints the full command list, the error codes or the prices instead. - `--section commands|errors|cost`, Print one section instead of the core guide: every command, every error code, or the prices - `--code C`, Print the entry for one error code, with its fix - `--format md|json`, Output format, Markdown or JSON. Default: md - `--install`, Add a short Promigence section to `AGENTS.md` or `CLAUDE.md`, and write the guide into `.claude/skills` and `.cursor/rules` - `--create`, With `--install`: create `AGENTS.md` if there is neither `AGENTS.md` nor `CLAUDE.md` - `--check`, Show what `--install` would change without writing anything; exits 13 if anything would change ### `promigence mcp` Runs an MCP (Model Context Protocol) server over standard input and output, so AI agents that support MCP can create and use sandboxes. Add it with `claude mcp add promigence -- promigence mcp`; on Windows, end the command with `-- cmd /c promigence mcp` instead. - `--read-only`, Offer only the tools that read: listing, reading a file, fetching output and reports. They still return what a sandbox holds, so this limits what the agent can change, not what it can see - `--root PATH`, Keep the file tools to this directory of the sandbox (commands the agent runs are not limited to it) - `--allow-tools A,B`, Offer only these tools, given as comma-separated names - `--cap USD`, The most each sandbox or batch it starts may spend, in USD. Default: `PROMIGENCE_SPEND_CAP`, then your organization's default cap - `--keep`, Leave the sandboxes this session created running when the server stops (by default they are ended) ### `promigence status` Shows whether the service is up, the state of each service, and how much of your concurrency limit is in use. Without an API key it shows the service status only. - `--json`, Print the result as JSON, even in a terminal ### `promigence billing usage` Shows your organization's spending this month: plan, usage by sandbox size, credits used and the next invoice (owners only). Any key can list its own project's charges with `--ledger`. - `--ledger`, Also list the individual charges for your current key's project - `--limit N`, With `--ledger`: how many charges to list. Default: 20 - `--cursor C`, With `--ledger`: the `next_cursor` from an earlier page, to get the next page - `--json`, Print the result as JSON, even in a terminal ### `promigence billing history` Credits and payments, newest first (owners). - `--kind K`, All | credits | payments (default all) - `--limit N`, How many (default 50, at most 100) - `--cursor C`, The next_cursor of an earlier page - `--json`, Force the JSON envelope ### `promigence referrals` Shows your organization's referral code, the offer that comes with it, and how your referrals stand. A friend signs up with your code by running `promigence login --ref CODE`. - `--json`, Print the result as JSON, even in a terminal ### `promigence referrals apply ` Applies a friend's referral code to your organization; its credit comes when you pay your first plan invoice. Only an owner can apply a code, and only before the first paid invoice. - `--json`, Print the result as JSON, even in a terminal ### `promigence pricing` Shows the live price list: per-second rates, the price of each sandbox size, limits and free credit. With an API key you see your organization's prices; without one, the published list. - `--new-account`, Show the published list instead of your own prices - `--json`, Print the result as JSON, even in a terminal ### `promigence credits` Shows your free-credit offer: whether it can be claimed, how much it is, when it expires and the campaign it came from, if any. - `--json`, Print the result as JSON, even in a terminal ### `promigence credits claim` Opens the page where you accept the terms and claim your free credit, and prints its link. The link works once and expires after 15 minutes. - `--no-open`, Print the link without opening a browser - `--json`, Print the result as JSON, even in a terminal ### `promigence billing portal` Prints a link to the billing portal, where you can change the card on file and see past invoices (owners only). - `--json`, Print the result as JSON, even in a terminal ## Snapshots Build a verified environment once. Everything after this is a fork of it. ### `promigence snapshot create` Builds a snapshot from an image, a Dockerfile, a `devcontainer.json`, a git repository or a local directory, running your setup steps and then your verify command. Nothing is stored if the verify command fails. - `--repo R`, The repository to build: owner/name for a connected GitHub repository, or a git URL - `--ref R`, With `--repo` owner/name: the branch, tag or commit SHA to build. Default: the default branch - `--commit SHA`, The exact commit to build, as a full 40-character SHA; a branch name is refused - `--image REF`, The image to build from: a tag, which is pinned to its digest for you, or `REF@sha256:D` - `--dockerfile PATH`, A Dockerfile to build the snapshot from - `--context DIR|URL@SHA`, The Dockerfile's build context: a local directory, or a git URL pinned to a full commit SHA. Default: the Dockerfile's directory - `--devcontainer PATH`, A `devcontainer.json` to build from. Default: the one in this directory - `--no-devcontainer`, Ignore the repository's `devcontainer.json` - `--dir PATH`, Build from a local directory, uploading only the files git tracks there - `--from SNAP`, With `--repo` owner/name or `--dir`: the snapshot the build starts from. Default: `promigence/base` - `--track`, With `--repo` owner/name: rebuild on every push to the branch and move `--alias` to the new snapshot; each rebuild is billed per second while it runs - `--setup CMD`, A setup command; repeat the flag for more steps, which run in order - `--verify CMD`, A command that must exit 0, or nothing is stored - `--start CMD`, A command started at build time and already running in every sandbox made from the snapshot - `--tier xsmall|small|medium|large-16|large|xlarge|2xlarge`, The size of the build and of every sandbox started from the snapshot - `--alias N`, A name for the snapshot, unique in your organization - `--grade CMD`, The snapshot's default grader: a command that scores a run's work in a clean copy of the environment - `--fresh`, Do not reuse the answer to the same command from the last 10 minutes; identical inputs still reuse their existing snapshot - `--wait`, Wait for the build to finish, for at most `--wait-timeout` (default 100s) - `--wait-timeout DUR`, How long `--wait` waits; when it runs out, the command exits with code 11 and a build in progress keeps going. Default: 100s - `--idempotency-key K`, A key you choose; repeating the command with the same key within 24 hours returns the first result and starts nothing new - `--json`, Print the result as JSON, even in a terminal ### `promigence snapshot status ` Shows the state of a snapshot build, by its build ID. With `--wait`, it waits for the build to finish. - `--wait`, Wait for the build to finish, for at most `--wait-timeout` (default 100s) - `--wait-timeout DUR`, How long `--wait` waits; when it runs out, the command exits with code 11 and the build keeps going. Default: 100s - `--log N`, Also print the last N lines of the build log - `--json`, Print the result as JSON, even in a terminal ### `promigence snapshot list` Lists the snapshots in your organization, with each one's alias, tier and source. - `--json`, Print the result as JSON, even in a terminal ### `promigence snapshot inspect ` Shows a snapshot's record: where it came from, its tier, its verify command and whether it is verified. - `--json`, Print the result as JSON, even in a terminal ### `promigence snapshot verify ` Runs a snapshot's recorded verify command again, in a new sandbox started from it, to check that the snapshot still works. It prints the most the check can cost, and exits with code 6 if the check fails. - `--json`, Print the result as JSON, even in a terminal ### `promigence snapshot export ` Writes a portable `.promigence` bundle that identifies a snapshot exactly, with where it came from and how it was verified, for you to commit, cite or send. Anyone can check the file offline, and `--snapshot` accepts it in place of an ID. - `--out FILE`, The file to write. Default: `.promigence`; `-`, or piping the output, writes the bundle to stdout - `--json`, Print the result as JSON, even in a terminal ### `promigence image resolve REF` Pins an image tag such as `python:3.12` to its exact digest (`REF@sha256:…`), without a container runtime on your machine. Pass the result to `snapshot create --image`. - `--registry-secret NAME`, A stored secret holding `user:password` for a private registry - `--json`, Print the result as JSON, even in a terminal ### `promigence github connect` Connects GitHub through the console: it opens the console's page for connecting GitHub in your browser and waits until the connection is made, declined or expired. After that, `snapshot create --repo owner/name` can build from the repositories you gave it, private ones included. - `--no-open`, Print the console page's link instead of opening a browser - `--no-wait`, Print the console page's link and return without waiting - `--wait-timeout DUR`, How long to wait for the connection; when it runs out, the command exits with code 11. Default: 10m - `--json`, Print the result as JSON, even in a terminal ### `promigence github status` Shows your GitHub connection: the connected accounts, installs GitHub has not confirmed yet, and the branches that rebuild a snapshot on every push. - `--json`, Print the result as JSON, even in a terminal ### `promigence github disconnect ` Disconnects a GitHub account, named by its installation ID or account name: nothing more is built from it and its tracked branches stop rebuilding. The App stays installed on GitHub until you uninstall it there. - `--json`, Print the result as JSON, even in a terminal ### `promigence github untrack ` Stops a tracked branch, named by its track ID or by the alias it moves, from rebuilding its snapshot on every push. The snapshot itself is kept. - `--json`, Print the result as JSON, even in a terminal ### `promigence repos` Lists the repositories your GitHub or GitLab connection can read; pass one to `snapshot create --repo`. - `--page N`, Which page to show, 100 repositories a page. Default: 1 - `--provider NAME`, `github` (the default) or `gitlab` - `--connection ID`, With `--provider gitlab`: one GitLab connection, by its `glc_…` ID - `--json`, Print the result as JSON, even in a terminal ### `promigence gitlab connect` Connect GitLab read-only in the console; waits. - `--no-open`, Print the page, open nothing - `--no-wait`, Print the page and return - `--wait-timeout DUR`, For the connection (10m); expiry = exit 11 - `--json`, Force the JSON envelope ### `promigence gitlab status` GitLab users, pending confirmations, tracks. - `--json`, Force the JSON envelope ### `promigence gitlab disconnect ` Revoke a GitLab connection. - `--json`, Force the JSON envelope ### `promigence gitlab untrack ` Stop rebuilding on commits (snapshot stays). - `--json`, Force the JSON envelope ### `promigence snapshot delete ` Deletes one of your snapshots, by ID or alias. It is refused while any sandbox started from the snapshot is still running; finished runs keep their reports. - `--json`, Print the result as JSON, even in a terminal ### `promigence snapshot builds` Lists your snapshot builds, newest first. A rejected build keeps the reason it was rejected. - `--limit N`, How many builds to list. Default: 20 - `--state S`, Only builds in this state: `queued`, `running`, `verified`, `rejected` or `failed` - `--cursor C`, The `next_cursor` of an earlier page, to list the page after it - `--json`, Print the result as JSON, even in a terminal ### `promigence snapshot alias [NAME]` Gives a snapshot a name (an alias) to use instead of its ID, or removes it with `--clear`; with no NAME, it shows the current alias. An alias is unique within your organization. - `--clear`, Remove the snapshot's alias instead of setting one - `--json`, Print the result as JSON, even in a terminal ## Runs Quote, cap, fork N copies, execute, and read which copies were valid. ### `promigence run -- CMD` Starts N sandboxes from a snapshot, runs CMD in each, and prints the validity report when they finish. Each sandbox ends when CMD exits, unless you pass `--keep`. - `--snapshot H`, The snapshot to start from: an ID, an alias or `alias@commit7`, or a `./env.promigence` file. Default: `promigence/base` - `--image REF`, Start from an image (a tag or `REF@sha256:D`) instead of `--snapshot`; the first time, its snapshot is built and the build counts toward --cap - `--count N` **(required)**, How many sandboxes to start; commands in each get `PROMIGENCE_INDEX` (0..N-1) and `PROMIGENCE_SEED` - `--timeout DUR`, How long each sandbox may run. Default: 15m - `--cap USD` **(required)**, The most the run may spend, in USD; a run quoted above it is refused (exit 5) - `--allow-partial`, If the cap cannot cover every sandbox, start as many as it allows and mark the rest `not_started` - `--secret NAME`, Give the sandboxes a stored secret as an environment variable of the same name (repeatable) - `--verify-each`, Re-run the snapshot's verify command in each sandbox before CMD runs - `--network none|egress`, Outbound network access: `egress` (allowed) or `none` (no network). Default: `egress` - `--allow HOST`, Let the sandboxes reach only these hosts (repeatable, or comma-separated; not with `--network` none) - `--optimize-for start|compute`, What to favour: `start` (fast, wide starts) or `compute` (raw speed for long, memory-heavy jobs on tiers of 15 GiB or more). Default: `start` - `--label K=V`, A label of your own as K=V, returned with the run (repeatable) - `--wait-timeout DUR`, How long to wait for the run; when it runs out, the command exits with code 11 and the run keeps going. Default: 100s - `--grade CMD`, A command that scores the work in a clean copy of the environment after CMD ends - `--holdout CMD`, A second, held-out test command; the report shows the gap between the two pass rates - `--grade-score M`, How the grader's result is read: `exit` (exit 0 passes), `last_line_json` (a last line such as `{"score":0.8,"pass":true}`) or `tap` (TAP output). Default: `exit` - `--grade-timeout DUR`, Time limit for each grader. Default: 10m - `--grade-output`, Keep the last 16 KiB of the grader's output for the report (never the held-out grader's) - `--fail-on task|env|none`, Which failures make the command exit non-zero: `task` (all of them), `env` (all except task failures) or `none`. Default: `task` - `--keep`, Keep the sandboxes running after CMD ends; they are billed until killed or their --timeout - `--stream`, Show each sandbox's output live (the default in a terminal) - `--no-stream`, Turn live output off and print one result at the end, even in a terminal - `--max-output BYTES`, The most output kept from each of CMD's output streams. Default: 64k - `--idempotency-key K`, A key you choose; repeating the command with the same key within 24 hours returns the first result and starts nothing new - `--verbose`, Also show start-up timing percentiles and outcome totals in the text summary ### `promigence run quote` Prices a run before you start it: the most it can cost for the number of sandboxes and the timeout you give. It starts nothing and spends nothing. - `--snapshot H`, The snapshot to price: an ID, an alias or `alias@commit7`, or a `./env.promigence` file. Default: `promigence/base` - `--count N` **(required)**, How many sandboxes to price - `--timeout DUR`, How long each sandbox may run. Default: 15m - `--tier T`, The tier to price at; it must match the snapshot's assigned tier - `--cap USD`, Check the quote against this spend cap, in USD; nothing is spent - `--json`, Print the result as JSON, even in a terminal ### `promigence run report ID` Shows a run's validity report: each sandbox's outcome, whether a failure came from the environment or from your task and how to fix it, and what the run cost. - `--json`, Print the result as JSON, even in a terminal - `--sandboxes all|failed`, Which sandboxes to list: `all`, or only the `failed` ones. Default: the summary plus the sandboxes that did not complete - `--sandbox SID`, Show this one sandbox in full - `--repro`, With `--sandbox`: also print a command that runs exactly that sandbox again - `--limit N`, How many sandboxes the text lists before saying how many more there are; 0 lists them all, and `--json` is never cut. Default: 50 ### `promigence run status ID` Shows a run's state and how many of its sandboxes are in each state. With `--wait`, it waits for the run to finish. - `--wait`, Wait for the run to finish, for at most `--wait-timeout` (default 100s) - `--wait-timeout DUR`, How long `--wait` waits; when it runs out, the command exits with code 11 and the run keeps going. Default: 100s - `--json`, Print the result as JSON, even in a terminal ### `promigence run cancel ID` Cancels the sandboxes of a run that are still queued. Sandboxes that already started keep running; `run kill` ends those too. - `--json`, Print the result as JSON, even in a terminal ### `promigence run kill ID` Ends every sandbox of a run, including any still queued. The run's report still shows what each sandbox did before the kill. - `--json`, Print the result as JSON, even in a terminal ### `promigence run replay ID` Runs the environment failures of a run again, in new sandboxes. A replay happens only when you ask for one, and it is reported apart from the run's own success figures. - `--sandbox SID`, Replay only this sandbox (repeatable) - `--env K=V`, A value for each variable the run's command was started with (runs keep names, never values) - `--json`, Print the result as JSON, even in a terminal ### `promigence run open ID` Reopens a failed sandbox as a new, live sandbox in the state it was in when it failed, so you can look around. It has its own ID and is billed from the moment it opens. - `--sandbox SID`, Which failed sandbox to reopen. Default: the only one - `--cap USD`, The most the reopened sandbox may spend, in USD - `--timeout DUR`, How long the reopened sandbox may run. Default: the run's timeout - `--json`, Print the result as JSON, even in a terminal ### `promigence run captures ID` Lists the failed sandboxes of a run whose state was kept so that `run open` can reopen them, and when each one expires. - `--delete SNAPSHOT_ID`, Delete the capture with this SNAPSHOT_ID now, before it expires - `--json`, Print the result as JSON, even in a terminal ### `promigence run list` Lists your runs, newest first, with each one's state, number of sandboxes and snapshot. - `--limit N`, How many runs to list. Default: 20 - `--state S`, Only runs in this state: `running`, `completed`, `cap_killed` or `aborted` - `--cursor C`, The `next_cursor` of an earlier page, to list the page after it - `--json`, Print the result as JSON, even in a terminal ## Sandboxes Long-lived sandboxes you drive command by command: exec, files, pause, resume, fork. ### `promigence fork` Starts N sandboxes from a snapshot under a spend cap and waits until they are ready. Each sandbox gets its snapshot's size (`small` for the base); for another size, build a snapshot with `promigence snapshot create --image REF --tier T`. - `--snapshot H`, The snapshot to start from: `snap_`, an alias (`alias@commit7` pins a commit) or a bundle file such as `./env.promigence`. Default: `promigence/base` - `--count N` **(required)**, How many sandboxes to start - `--timeout DUR`, How long each sandbox may run. Default: 15m - `--cap USD` **(required)**, The most the run may spend, in USD; a run quoted above it is refused (exit 5) - `--allow-partial`, If the cap cannot cover every sandbox, start as many as it allows and mark the rest `not_started` - `--secret NAME`, Give the sandboxes a stored secret as an environment variable of the same name (repeatable) - `--verify-each`, Re-run the snapshot's verify command in each sandbox before it is handed over - `--network none|egress`, Outbound network access: `egress` (allowed) or `none` (no network). Default: `egress` - `--allow HOST`, Let the sandboxes reach only these hosts (repeatable, or comma-separated; not with `--network none`) - `--optimize-for start|compute`, What to favour: `start` (fast, wide starts) or `compute` (raw speed for long, memory-heavy jobs on tiers of 15 GiB or more). Default: `start` - `--label K=V`, A label of your own as K=V, returned with the run (repeatable) - `--wait-timeout DUR`, How long to wait for the sandboxes to be ready; when it runs out, the command exits with code 11 and nothing is killed. Default: 100s - `--no-wait`, Return as soon as the run is created, without waiting for the sandboxes to be ready - `--fresh`, Always start new sandboxes; by default, the same command repeated within the same 10-minute window returns the earlier sandboxes - `--stream`, Show output live (the default in a terminal) - `--no-stream`, Turn live output off and print one result at the end, even in a terminal - `--idempotency-key K`, A key you choose; repeating the command with the same key within 24 hours returns the first result and starts nothing new - `--verbose`, Also show start-up timing percentiles and outcome totals in the text summary - `--json`, Print the result as JSON, even in a terminal ### `promigence exec -- CMD` Runs a command (everything after `--`) in one sandbox with `--sandbox SID`, or in every ready sandbox of a run with `--run ID --all`. - `--sandbox SID`, Run in this sandbox; prints the command's own output (JSON only with `--json` or `PROMIGENCE_OUTPUT=json`) and exits with its exit code: 127 if the command is not found, 125 if Promigence itself fails - `--run ID`, The run to target, with `--all`; sandboxes still queued are reported as skipped unless you pass `--wait` - `--all`, With `--run`, run in every ready sandbox of that run; exits with code 0 if every command exits 0, otherwise 4 - `--no-passthrough`, Exit with a Promigence exit code (0–12) instead of the command's own - `--background`, With `--sandbox`, start the command in the background, print its `exec_id` and return at once - `--stdin`, With `--background`, keep the command's stdin open so you can write to it with `promigence exec stdin` - `--secret NAME`, Give the command this stored secret as an environment variable of the same name (repeatable) - `--stream`, Show output live (the default in a terminal) - `--no-stream`, Turn live output off and print one result at the end, even in a terminal - `--max-output BYTES`, The most output kept from each of the command's output streams; past it the rest is cut, and text output exits with code 12. Default: 64k, or 32m (the maximum) into a pipe or file - `--timeout DUR`, How long the command may run. Default: 15m - `--wait`, With `--run --all`, first wait for sandboxes that are not ready yet, for at most `--wait-timeout` (default 100s) - `--wait-timeout DUR`, How long `--wait` waits; when it runs out, the command exits with code 11 and nothing is killed. Default: 100s - `--idempotency-key K`, A key you choose; repeating the command with the same key within 24 hours runs it only once and returns the first result ### `promigence exec output EXEC_ID` Prints the output of a command by its exec id. For a background command (an id starting with `x_`), name its sandbox with `--sandbox`, and add `--follow` to stream the output until the command exits. - `--range A-B`, Only this byte range: 0-based, with B included; `A-` reads to the end - `--sandbox SID`, Look for the command in this sandbox; required for a background command (`x_…`) - `--run ID`, Look for the command in this run - `--stderr`, Print the command's stderr instead of its stdout - `--follow`, For a background command, stream its output until it exits, then exit with its exit code - `--json`, Print the result as JSON, even in a terminal ### `promigence exec ps` Lists a sandbox's background commands (those started with `exec --background`), with their state and exit code. - `--sandbox SID` **(required)**, The sandbox to list - `--json`, Print the result as JSON, even in a terminal ### `promigence exec stdin EXEC_ID` Writes input to a background command's stdin. The command must have been started with `exec --background --stdin`. - `--sandbox SID` **(required)**, The sandbox the command runs in - `--data TEXT`, Write this text. Default: read standard input to EOF and write that - `--file P`, Write the bytes of this local file - `--eof`, Close the command's stdin after writing (the default when the input is piped in) - `--no-eof`, Keep the command's stdin open after writing piped input - `--json`, Print the result as JSON, even in a terminal ### `promigence exec kill EXEC_ID` Sends a signal to a background command, SIGKILL unless you choose another with `--signal`. - `--sandbox SID` **(required)**, The sandbox the command runs in - `--signal SIG`, The signal to send: `TERM`, `INT`, `HUP`, `KILL` or a signal number. Default: SIGKILL - `--forget`, Then also drop the command's handle and the output kept for it - `--json`, Print the result as JSON, even in a terminal ### `promigence files put SRC DST` Copies a local file SRC into a sandbox at DST, an absolute path in the sandbox. Add `--recursive` to copy a whole directory. - `--sandbox SID` **(required)**, The sandbox to copy into - `--recursive`, Copy a directory: SRC is a local directory and DST a directory in the sandbox (needs `tar` on this machine) - `--json`, Print the result as JSON, even in a terminal ### `promigence files get SRC DST` Copies a file out of a sandbox: SRC is an absolute path in the sandbox, and DST a local path, or `-` for stdout. Add `--recursive` to copy a whole directory. - `--sandbox SID` **(required)**, The sandbox to copy from - `--recursive`, Copy a directory: SRC is a directory in the sandbox and DST a local directory - `--exclude GLOB`, With `--recursive`, leave out paths that match this pattern, e.g. `.git` (repeatable) - `--keep-links`, With `--recursive`, keep symbolic links that point outside DST (by default they stop the copy) - `--json`, Print the result as JSON, even in a terminal ### `promigence files ls [PATH]` Lists a directory in a sandbox (default `/`), with each entry's type, permissions, size and modification time. Symbolic links are listed as links, not followed. - `--sandbox SID` **(required)**, The sandbox to look in - `--recursive`, List everything below PATH, not just one level - `--depth N`, With `--recursive`, how many levels to go down - `--limit N`, Stop after N entries; the output says when it was cut short - `--no-hidden`, Leave out dotfiles (they are listed by default) - `--json`, Print the result as JSON, even in a terminal ### `promigence files search [PATH]` Finds files under PATH in a sandbox (default `/`) by name pattern, by text inside them, or both. Text matches print as `path:line: text`. - `--sandbox SID` **(required)**, The sandbox to search - `--name GLOB`, Match file names against this pattern, e.g. `'*.py'` - `--contains TEXT`, Find this text, taken literally, inside the matching files - `--ignore-case`, Ignore upper and lower case for `--contains` - `--limit N`, Stop after N matches; the output says when it was cut short - `--no-hidden`, Skip dotfiles and dot-directories - `--json`, Print the result as JSON, even in a terminal ### `promigence files mkdir PATH` Creates a directory at PATH, an absolute path in a sandbox. - `--sandbox SID` **(required)**, The sandbox to create it in - `--parents`, Like `mkdir -p`: create missing parent directories, and do not fail if it already exists - `--mode OCTAL`, Permissions in octal, e.g. `755` - `--json`, Print the result as JSON, even in a terminal ### `promigence files mv SRC DST` Moves or renames a file or directory inside a sandbox; SRC and DST are absolute paths. - `--sandbox SID` **(required)**, The sandbox the paths are in - `--overwrite`, Replace DST if it already exists - `--json`, Print the result as JSON, even in a terminal ### `promigence files cp SRC DST` Copies a file or directory to another place in the same sandbox; SRC and DST are both absolute paths in the sandbox. - `--sandbox SID` **(required)**, The sandbox the paths are in - `--recursive`, Copy a directory and everything under it - `--overwrite`, Replace DST if it already exists - `--json`, Print the result as JSON, even in a terminal ### `promigence files chmod PATH` Changes the permissions, owner or group of a path in a sandbox; give at least one of `--mode`, `--uid` or `--gid`. - `--sandbox SID` **(required)**, The sandbox the path is in - `--mode OCTAL`, New permissions in octal, e.g. `755` - `--uid N`, New owner, as a numeric user id - `--gid N`, New group, as a numeric group id - `--recursive`, Apply to the directory and everything under it - `--json`, Print the result as JSON, even in a terminal ### `promigence agent start claude|codex|opencode` Starts a coding agent (`claude`, `codex` or `opencode`) in a new sandbox, with its model key taken from a stored secret. With `--prompt` it works on a task in the background; otherwise it prints the command that opens its terminal, or `--attach` opens it now. - `--key-secret NAME[=VAR]`, The stored secret that holds the model key; NAME=VAR gives it to the agent as VAR. Default: `ANTHROPIC_API_KEY` (`OPENAI_API_KEY` for codex) - `--key-from-env VAR`, First store the key from this environment variable, so it never appears on the command line - `--snapshot H`, Start from this snapshot; the agent is installed if it is missing. Default: `promigence/base` - `--image REF@sha256:D`, Start from this container image instead of `--snapshot` - `--repo URL`, Clone this public repository and start the agent in it - `--prompt TEXT`, Have the agent work on this task headless, in the background - `--model M`, The agent's model (opencode: provider/model, e.g. xai/grok-4-0709) - `--attach`, Open the agent's terminal now - `--timeout DUR`, How long the sandbox lives. Default: 1h - `--cap USD`, Spend cap in US dollars. Default: `PROMIGENCE_SPEND_CAP`, or else the org's default cap - `--wait-timeout DUR`, How long to wait for the sandbox to be ready; when it runs out, the command exits with code 11 and nothing is killed. Default: 100s - `--json`, Print the result as JSON, even in a terminal ### `promigence sandbox kill SID` Ends one sandbox, which stops its billing. - `--json`, Print the result as JSON, even in a terminal ### `promigence sandbox network SID` Shows what a sandbox may reach on the network and, when it has an allow-list, the hosts it was refused. `--cut` turns off its outbound access for good. - `--cut`, Cut this sandbox's outbound access now; it cannot be turned back on - `--json`, Print the result as JSON, even in a terminal ### `promigence sandbox shell SID [-- CMD]` Opens an interactive terminal in a sandbox; keys such as Ctrl-C reach the sandbox and the size follows your window. Anything after `--` runs instead of the login shell. - `--cmd CMD`, Run this command instead of the login shell (through `sh -c`) - `--cwd DIR`, Start in this directory - `--env K=V`, Set an environment variable, K=V (repeatable) - `--secret NAME[=VAR]`, Put a stored secret in the terminal's environment; NAME=VAR puts it in the variable VAR (repeatable) ### `promigence sandbox ssh SID [-- CMD]` Logs you in to a sandbox over SSH, with the key and access set up for you; `scp`, `sftp` and port forwarding with `-L` work too. Anything after `--` runs as a remote command. - `--config`, Print an SSH config block instead of logging in, for an IDE, `scp`, `sftp` or `rsync` - `--print`, Print the connection details (the `ssh` command to run) instead of logging in - `--key PATH`, Use this key pair instead of making one (its `.pub` file must sit beside it) - `--ttl S`, How long the access lasts, in seconds. Default and maximum: 3600 - `--idle S`, Close a session after this many seconds with no activity - `--proxy`, Carry one connection over stdin and stdout; `ssh` itself uses this - `--list`, List the keys that have access, then exit - `--revoke KEY_ID`, End one key's access, then exit - `--json`, Print the result as JSON, even in a terminal ### `promigence port expose PORT` Publishes a port of a sandbox at a preview URL. Anyone with the URL can reach the port until you revoke it. Preview URLs are not enabled yet: until they are, the command answers that previews are not enabled. - `--sandbox SID` **(required)**, The sandbox whose port to publish - `--json`, Print the result as JSON, even in a terminal ### `promigence port list` Lists a sandbox's preview URLs and the ports they publish. - `--sandbox SID` **(required)**, The sandbox whose preview URLs to list - `--json`, Print the result as JSON, even in a terminal ### `promigence port revoke TOKEN|PORT` Takes preview URLs down: give a token to remove that one URL, or a port to remove every URL for it. - `--sandbox SID` **(required)**, The sandbox the preview URL belongs to - `--json`, Print the result as JSON, even in a terminal ### `promigence secrets set NAME` Stores a secret under NAME, reading the value from an environment variable, a file or stdin; a value typed on the command line is refused. Give it to sandboxes with `--secret NAME`. - `--from-env VAR`, Read the value from this environment variable - `--from-file P`, Read the value from this file - `--host HOST`, Bind the secret to a host: requests sent to the address this command prints for HOST are authenticated for you, and the value stays out of the sandbox unless a run asks for it (see `--no-raw`) (repeatable) - `--header NAME`, With `--host`, the request header that carries the key (repeatable). Default: the usual API-key headers - `--no-raw`, With `--host`, never give the value itself to a sandbox - `--list`, List the names of stored secrets; values are never shown - `--delete`, Delete the secret NAME - `--json`, Print the result as JSON, even in a terminal ### `promigence sandbox list` Lists your sandboxes, newest first. Filter by state or by run label, and use `--cursor` to page through. - `--limit N`, How many to show. Default: 50 - `--state S`, Only sandboxes in these states, comma-separated: `queued`, `awaiting_capacity`, `ready`, `running`, `paused`, `ended` (repeatable) - `--label K=V`, Only sandboxes whose run carries every label given (repeatable) - `--cursor C`, Show the next page: pass the `next_cursor` of an earlier page - `--json`, Print the result as JSON, even in a terminal ### `promigence sandbox pause SID` Pauses a sandbox: while paused it is not billed by the second and does not count against your concurrency limit. Commands started with `exec --background` are ended; anything else you started keeps running when it resumes. A paused sandbox is kept for 30 days, and resuming it starts the 30 days again; after that it is deleted (its `pause_expires_at` says when). - `--json`, Print the result as JSON, even in a terminal ### `promigence sandbox resume SID` Brings a paused sandbox back and starts its clock again, for billing and for its timeout. A sandbox that was paused because its run reached its spend cap goes on only with a higher cap (`--cap`). - `--optimize-for start|compute`, `start` or `compute`, as for `fork`. Default: what the sandbox was created with - `--cap USD`, For a sandbox paused at its run's spend cap: the run's new, higher cap, in USD - `--json`, Print the result as JSON, even in a terminal ### `promigence sandbox snapshot SID` Takes a snapshot of a running sandbox without stopping it, so new sandboxes can start from this point. Commands started with `exec --background` are ended to take it. - `--json`, Print the result as JSON, even in a terminal - `--alias NAME`, Give the snapshot this alias - `--move-alias`, Take the alias from the snapshot that has it now - `--force`, Take it even though the sandbox was given a secret; the snapshot, and every sandbox started from it, can then contain that value ### `promigence secrets list` Lists your stored secrets by name, with the hosts any of them are bound to; values are never shown. - `--json`, Print the result as JSON, even in a terminal ### `promigence secrets delete NAME` Deletes a stored secret. - `--json`, Print the result as JSON, even in a terminal ### `promigence sandbox info SID` Shows one sandbox: its state, tier, time left, cost so far and the commands it has run. - `--json`, Print the result as JSON, even in a terminal ### `promigence sandbox extend SID` Gives a live sandbox more time by setting a longer total timeout. It is refused (exit 5) if the extra time would take the run past its spend cap. - `--timeout DUR` **(required)**, The sandbox's new total timeout, e.g. `30m` - `--json`, Print the result as JSON, even in a terminal ### `promigence sandbox autopause SID` Makes a sandbox pause itself once it has been idle for `--after`, or turns that off with `--off`. With no flag, shows the rule the sandbox is under. - `--after DUR`, Pause the sandbox once it has been idle this long. Minimum: 2s - `--off`, Never pause it for being idle; only its timeout ends it - `--mode MODE`, What counts as idle: `requests` (the default) means no API requests; `activity` also requires no CPU use, no network traffic and no open connection inside the sandbox - `--json`, Print the result as JSON, even in a terminal ### `promigence sandbox probe SID` Checks whether a sandbox's files still match the verified snapshot it started from, using the paths the snapshot recorded or the ones you name with `--path`. Exits with code 3 if they differ. - `--path P`, Check these paths instead (repeatable); where the snapshot recorded none (the base, or one built with `--image` or from a connected repository), give each as `PATH=blake3:` - `--json`, Print the result as JSON, even in a terminal ### `promigence files rm PATH` Deletes a file or directory at PATH, an absolute path in a sandbox. - `--sandbox SID` **(required)**, The sandbox the path is in - `--recursive`, Delete a directory and everything under it - `--json`, Print the result as JSON, even in a terminal ## Ops Accounts, keys, billing, organisations, connections and CI runners. ### `promigence bench burst` Starts N sandboxes at once and reports how many came up within the timeout and percentiles of how long they took to be ready. The sandboxes are ended once measured, unless you pass `--keep`. - `--snapshot H` **(required)**, The snapshot to start from: an ID, an alias, `alias@commit7` or `promigence/base` - `--count N` **(required)**, How many sandboxes to start at once - `--timeout D`, Each sandbox's timeout. Default: 120s, as in the public burst benchmark - `--cap USD`, Spend cap for the burst, in USD; required unless `PROMIGENCE_SPEND_CAP` is set - `--keep`, Leave the sandboxes running afterwards; by default they are ended once measured - `--json`, Print the result as JSON, even in a terminal ### `promigence runners github` Runs your GitHub Actions jobs in sandboxes: jobs with `runs-on: promigence` are picked up until you press Ctrl-C. Its GitHub token comes from the environment and needs Actions read and Administration write (with `--org`: Self-hosted runners write), or `repo` (plus `admin:org`) on a classic token. - `--repo OWNER/REPO`, Take the jobs of this repository - `--org ORG`, Or take the jobs of every repository in this organization - `--runner-group NAME`, With `--org`: the runner group the runners join. Default: `Default` - `--token-env VAR`, The environment variable holding a GitHub token. Default: `GH_TOKEN`, then `GITHUB_TOKEN` - `--labels A,B`, The `runs-on` labels this pool takes, comma-separated; `promigence-small`, `promigence-medium` and `promigence-large` also pick a size. Default: `promigence` - `--tier small|medium|large`, The size for a job whose labels name no size. Default: small - `--warm N`, Keep N runners waiting so jobs start at once; they are billed while idle - `--max M`, The most sandboxes running at once. Default: 10 - `--cap USD`, The most one job may cost, in USD. Default: what its full timeout costs at its size - `--timeout DUR`, The longest a job may run. Default: the longest sandbox your plan allows - `--idle-timeout DUR`, Stop a runner started on demand if no job takes it within this time. Default: 90s - `--kill-on-exit`, On Ctrl-C, cancel running jobs instead of waiting for them - `--prepare`, Build the runner snapshot for the `--tier` size, then exit - `--yes`, Build a missing runner snapshot without asking; each size's build is billed per second while it runs - `--github-api URL`, The API URL of your GitHub Enterprise Server. Default: `https://api.github.com` - `--json`, Print the result as JSON, even in a terminal ### `promigence runners gitlab` Runs your GitLab CI jobs in sandboxes, as a runner with the tags you gave it in GitLab, until you press Ctrl-C. The runner token (`glrt-…`) comes from the environment and jobs on this runner can read it, so use it only for projects whose CI code you trust. - `--url URL`, The address of your GitLab. Default: `https://gitlab.com` - `--token-env VAR`, The environment variable holding the runner authentication token. Default: `GITLAB_RUNNER_TOKEN` - `--executor docker|shell`, Run each job in a container (`docker`) or directly in the sandbox (`shell`). Default: `docker` - `--default-image REF`, With `docker`: the image for a job that sets no `image:`. Default: `ubuntu:24.04` - `--pool N`, How many runners to keep running; they are billed while idle. Default: 1 (0 with `--api-token-env`) - `--api-token-env VAR`, The environment variable holding a GitLab token with `read_api`; with it, runners start only when jobs are pending - `--max M`, The most sandboxes running at once. Default: 10 - `--tier small|medium|large`, The runner size. Default: small - `--cap USD`, The most one job may cost, in USD. Default: what its full timeout costs at its size - `--timeout DUR`, The longest a job may run. Default: the longest sandbox your plan allows - `--idle-timeout DUR`, With `--api-token-env`: how long a runner waits for a job before it stops. Default: 90s - `--kill-on-exit`, On Ctrl-C, cancel running jobs instead of waiting for them - `--prepare`, Build the runner snapshot for the `--tier` size, then exit - `--yes`, Build a missing runner snapshot without asking; the build is billed per second while it runs - `--json`, Print the result as JSON, even in a terminal --- Page: https://www.promigence.ai/docs/reference/api # API reference The 129 routes of the published API contract, generated from it. The CLI and the TypeScript SDK call the same routes, so anything you can do from them you can do over HTTP. ## Basics - Base URL: `https://api.promigence.ai`. Requests and answers are JSON unless a route says otherwise. - Authentication: `Authorization: Bearer `. Create a key with `promigence keys create` or in the console; `promigence login` stores one for the CLI and the SDK. - Errors: an answer that is not a success carries `{"error": {...}}` with a stable `code`, a `message`, a `fix`, the CLI `exit` code, its `category`, `retryable` and a `request_id`. [Every error code](https://www.promigence.ai/docs/errors) - Retries: send an `Idempotency-Key` header with a create, and a retry of the same request starts, and bills, once. - The contract itself, the document this page is generated from, as OpenAPI 3.1 for client generators and tools: [/openapi.json](https://www.promigence.ai/openapi.json) Two sandboxes, one command each, capped at $1 bash ``` curl -s https://api.promigence.ai/v1/runs \ -H "Authorization: Bearer $PROMIGENCE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"snapshot": "promigence/base", "count": 2, "spend_cap": 1, "exec": {"sh": "python3 -c \"print(6*7)\""}}' ``` ## Meta [All 4 in full](https://www.promigence.ai/docs/reference/api/meta) - [GET /status The same data rendered as a self-contained HTML page by the API itself.](https://www.promigence.ai/docs/reference/api/meta#get-status) - [GET /v1/health Liveness, and whether the service can start sandboxes.](https://www.promigence.ai/docs/reference/api/meta#get-v1-health) - [GET /v1/llms.txt The agent guide as text/plain — the same document promigence agent-guide prints.](https://www.promigence.ai/docs/reference/api/meta#get-v1-llms-txt) - [GET /v1/status 24 hours of synthetic check results plus service health, as JSON.](https://www.promigence.ai/docs/reference/api/meta#get-v1-status) ## Snapshots [All 13 in full](https://www.promigence.ai/docs/reference/api/snapshots) - [POST /v1/images/resolve Turn an image tag into a digest.](https://www.promigence.ai/docs/reference/api/snapshots#post-v1-images-resolve) - [GET /v1/snapshots List snapshots, newest first.](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-snapshots) - [POST /v1/snapshots Build and verify a snapshot.](https://www.promigence.ai/docs/reference/api/snapshots#post-v1-snapshots) - [GET /v1/snapshots/{id} One snapshot by id or alias.](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-snapshots-id) - [DELETE /v1/snapshots/{id} Remove one of your own snapshots from your catalogue.](https://www.promigence.ai/docs/reference/api/snapshots#delete-v1-snapshots-id) - [PUT /v1/snapshots/{id}/alias Move the snapshot's alias.](https://www.promigence.ai/docs/reference/api/snapshots#put-v1-snapshots-id-alias) - [GET /v1/snapshots/{id}/manifest The manifest: what a .promigence bundle is built from.](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-snapshots-id-manifest) - [POST /v1/snapshots/{id}/verify Re-run the snapshot's own verify command in a fresh fork.](https://www.promigence.ai/docs/reference/api/snapshots#post-v1-snapshots-id-verify) - [GET /v1/snapshots/builds List your org's builds.](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-snapshots-builds) - [GET /v1/snapshots/builds/{id} One build. ?wait_ms=N long-polls until the build reaches a terminal state, capped at 30 s server-side.](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-snapshots-builds-id) - [GET /v1/snapshots/builds/{id}/build-log The tail of the build log.](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-snapshots-builds-id-build-log) - [GET /v1/templates The templates: ready-made starting points to fork (languages, app starters, agent tools, benchmarks).](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-templates) - [GET /v1/templates/{name} One template: its setup steps, everything it has installed (each package and its version, by package manager, and each tool's version), and every version with what changed.](https://www.promigence.ai/docs/reference/api/snapshots#get-v1-templates-name) ## GitHub [All 7 in full](https://www.promigence.ai/docs/reference/api/github) - [GET /v1/integrations/github Your organization's GitHub connections, the ones still being finished, and the snapshots that follow a branch.](https://www.promigence.ai/docs/reference/api/github#get-v1-integrations-github) - [POST /v1/integrations/github/connect Start connecting a GitHub account: a link to install the platform's GitHub App on it, valid for 15 minutes.](https://www.promigence.ai/docs/reference/api/github#post-v1-integrations-github-connect) - [DELETE /v1/integrations/github/installations/{installation_id} Disconnect a GitHub account: nothing is built from it any more and the snapshots that followed its branches stop following them.](https://www.promigence.ai/docs/reference/api/github#delete-v1-integrations-github-installations-installation-id) - [GET /v1/integrations/github/repos The repositories your GitHub connections can read, one page at a time ( page , per_page up to 100).](https://www.promigence.ai/docs/reference/api/github#get-v1-integrations-github-repos) - [POST /v1/integrations/github/requests Start connecting a GitHub account in the console, for yourself: a one-time ticket (5 minutes) and the console page that uses it ( connect_url ).](https://www.promigence.ai/docs/reference/api/github#post-v1-integrations-github-requests) - [GET /v1/integrations/github/requests/{request_id} How a GitHub connection request you started ended: pending , then connected , updated (already connected; its repository access changed), pending_provider_approval (an owner of the account must approve it on GitHub first), declined , other_org , needs_admin , not_installer , wrong_user , expired or failed , with a sentence that says what happened and what to do next.](https://www.promigence.ai/docs/reference/api/github#get-v1-integrations-github-requests-request-id) - [DELETE /v1/integrations/github/tracks/{track_id} Stop a snapshot following its branch.](https://www.promigence.ai/docs/reference/api/github#delete-v1-integrations-github-tracks-track-id) ## GitLab [All 7 in full](https://www.promigence.ai/docs/reference/api/gitlab) - [GET /v1/integrations/gitlab Your organization's GitLab connections (each with the URL and token of an optional project webhook that makes tracked branches build at once), the ones waiting for an owner to confirm, and the snapshots that follow a branch.](https://www.promigence.ai/docs/reference/api/gitlab#get-v1-integrations-gitlab) - [POST /v1/integrations/gitlab/connect Start connecting a GitLab user: a link to authorize the platform's GitLab application, read-only ( read_api read_repository ), valid for 15 minutes.](https://www.promigence.ai/docs/reference/api/gitlab#post-v1-integrations-gitlab-connect) - [DELETE /v1/integrations/gitlab/connections/{connection_id} Disconnect a GitLab user: the authorization is revoked on GitLab, nothing is built from it any more and the snapshots that followed branches through it stop following them.](https://www.promigence.ai/docs/reference/api/gitlab#delete-v1-integrations-gitlab-connections-connection-id) - [GET /v1/integrations/gitlab/repos The projects a GitLab connection can read (the oldest working one unless connection_id names another), one page at a time ( page , per_page up to 100).](https://www.promigence.ai/docs/reference/api/gitlab#get-v1-integrations-gitlab-repos) - [POST /v1/integrations/gitlab/requests Start connecting a GitLab user in the console, for yourself: a one-time ticket (5 minutes) and the console page that uses it ( connect_url ).](https://www.promigence.ai/docs/reference/api/gitlab#post-v1-integrations-gitlab-requests) - [GET /v1/integrations/gitlab/requests/{request_id} How a GitLab connection request you started ended: pending , then connected , already_connected , declined , wrong_user , expired or failed , with a sentence that says what happened and what to do next.](https://www.promigence.ai/docs/reference/api/gitlab#get-v1-integrations-gitlab-requests-request-id) - [DELETE /v1/integrations/gitlab/tracks/{track_id} Stop a snapshot following its GitLab branch.](https://www.promigence.ai/docs/reference/api/gitlab#delete-v1-integrations-gitlab-tracks-track-id) ## Runs [All 12 in full](https://www.promigence.ai/docs/reference/api/runs) - [DELETE /v1/captures/{id} Destroy a preserved failure now.](https://www.promigence.ai/docs/reference/api/runs#delete-v1-captures-id) - [GET /v1/runs List your org's runs, newest first.](https://www.promigence.ai/docs/reference/api/runs#get-v1-runs) - [POST /v1/runs Fork N sandboxes from one snapshot, optionally running a command in each.](https://www.promigence.ai/docs/reference/api/runs#post-v1-runs) - [GET /v1/runs/{id} One run and its sandboxes.](https://www.promigence.ai/docs/reference/api/runs#get-v1-runs-id) - [DELETE /v1/runs/{id} Cancel the queue and kill every live sandbox of the run.](https://www.promigence.ai/docs/reference/api/runs#delete-v1-runs-id) - [POST /v1/runs/{id}/cancel Stop what is still queued.](https://www.promigence.ai/docs/reference/api/runs#post-v1-runs-id-cancel) - [GET /v1/runs/{id}/captures What is preserved of this run's failures, and when each goes.](https://www.promigence.ai/docs/reference/api/runs#get-v1-runs-id-captures) - [POST /v1/runs/{id}/open Reopen a preserved failure as a new, live sandbox — the state the sandbox was in when it broke, not a re-run from the start.](https://www.promigence.ai/docs/reference/api/runs#post-v1-runs-id-open) - [POST /v1/runs/{id}/replay Re-fork the sandboxes whose outcome was an environment failure.](https://www.promigence.ai/docs/reference/api/runs#post-v1-runs-id-replay) - [GET /v1/runs/{id}/report The validity report: every sandbox, its outcome, and whether the failure was the environment's or the task's.](https://www.promigence.ai/docs/reference/api/runs#get-v1-runs-id-report) - [GET /v1/runs/{id}/sandboxes Only the sandboxes of a run.](https://www.promigence.ai/docs/reference/api/runs#get-v1-runs-id-sandboxes) - [POST /v1/runs/quote Price a run without starting one.](https://www.promigence.ai/docs/reference/api/runs#post-v1-runs-quote) ## Sandboxes [All 10 in full](https://www.promigence.ai/docs/reference/api/sandboxes) - [GET /v1/sandboxes List your org's sandboxes, newest first.](https://www.promigence.ai/docs/reference/api/sandboxes#get-v1-sandboxes) - [GET /v1/sandboxes/{id} One sandbox, with its execs.](https://www.promigence.ai/docs/reference/api/sandboxes#get-v1-sandboxes-id) - [PATCH /v1/sandboxes/{id} Extend a live sandbox's total lifetime, and set when it parks itself.](https://www.promigence.ai/docs/reference/api/sandboxes#patch-v1-sandboxes-id) - [DELETE /v1/sandboxes/{id} Kill it now. The answer's outcome says how it ended: aborted_by_client for a sandbox that had started, billed for the seconds it used; not_started for one still queued, which is not billed; or, when its command had already returned, that command's own outcome.](https://www.promigence.ai/docs/reference/api/sandboxes#delete-v1-sandboxes-id) - [GET /v1/sandboxes/{id}/network Read the network policy a live sandbox is running under.](https://www.promigence.ai/docs/reference/api/sandboxes#get-v1-sandboxes-id-network) - [POST /v1/sandboxes/{id}/network Cut a live sandbox's egress.](https://www.promigence.ai/docs/reference/api/sandboxes#post-v1-sandboxes-id-network) - [POST /v1/sandboxes/{id}/pause Park the sandbox: it does not count against your concurrency limit, and paused time is not billed.](https://www.promigence.ai/docs/reference/api/sandboxes#post-v1-sandboxes-id-pause) - [POST /v1/sandboxes/{id}/probe Re-check the sandbox's files against what the verified snapshot recorded.](https://www.promigence.ai/docs/reference/api/sandboxes#post-v1-sandboxes-id-probe) - [POST /v1/sandboxes/{id}/resume Bring a paused sandbox back where it was, and restart the billing clock.](https://www.promigence.ai/docs/reference/api/sandboxes#post-v1-sandboxes-id-resume) - [POST /v1/sandboxes/{id}/snapshot Snapshot a running sandbox without stopping it, and get back an ordinary snapshot id you can fork.](https://www.promigence.ai/docs/reference/api/sandboxes#post-v1-sandboxes-id-snapshot) ## Execs [All 7 in full](https://www.promigence.ai/docs/reference/api/execs) - [GET /v1/execs/{id} One exec by id alone, without knowing its sandbox or run.](https://www.promigence.ai/docs/reference/api/execs#get-v1-execs-id) - [GET /v1/sandboxes/{id}/execs List this sandbox's background execs.](https://www.promigence.ai/docs/reference/api/execs#get-v1-sandboxes-id-execs) - [POST /v1/sandboxes/{id}/execs Run a command. Buffered by default; Accept: text/event-stream streams it; background: true returns 202 with a handle instead of waiting.](https://www.promigence.ai/docs/reference/api/execs#post-v1-sandboxes-id-execs) - [GET /v1/sandboxes/{id}/execs/{exec_id} Read a background exec.](https://www.promigence.ai/docs/reference/api/execs#get-v1-sandboxes-id-execs-exec-id) - [DELETE /v1/sandboxes/{id}/execs/{exec_id} SIGKILL the background exec and drop its handle and buffered output.](https://www.promigence.ai/docs/reference/api/execs#delete-v1-sandboxes-id-execs-exec-id) - [POST /v1/sandboxes/{id}/execs/{exec_id}/signal Signal a background exec.](https://www.promigence.ai/docs/reference/api/execs#post-v1-sandboxes-id-execs-exec-id-signal) - [POST /v1/sandboxes/{id}/execs/{exec_id}/stdin Write to a running command's standard input, and close it.](https://www.promigence.ai/docs/reference/api/execs#post-v1-sandboxes-id-execs-exec-id-stdin) ## Files [All 12 in full](https://www.promigence.ai/docs/reference/api/files) - [GET /v1/sandboxes/{id}/files Stream a file out. ?path= .](https://www.promigence.ai/docs/reference/api/files#get-v1-sandboxes-id-files) - [PUT /v1/sandboxes/{id}/files Write a file in. ?path= ; the body is the bytes.](https://www.promigence.ai/docs/reference/api/files#put-v1-sandboxes-id-files) - [DELETE /v1/sandboxes/{id}/files Delete a path. Idempotent: a missing path answers existed: false , not 404.](https://www.promigence.ai/docs/reference/api/files#delete-v1-sandboxes-id-files) - [POST /v1/sandboxes/{id}/files/archive Pack a directory into a tar **inside the sandbox** and answer with where it landed and how big it is.](https://www.promigence.ai/docs/reference/api/files#post-v1-sandboxes-id-files-archive) - [POST /v1/sandboxes/{id}/files/chmod Change permissions and ownership.](https://www.promigence.ai/docs/reference/api/files#post-v1-sandboxes-id-files-chmod) - [POST /v1/sandboxes/{id}/files/copy Copy a file, or a whole tree with recursive .](https://www.promigence.ai/docs/reference/api/files#post-v1-sandboxes-id-files-copy) - [POST /v1/sandboxes/{id}/files/extract Unpack a tar that is already inside the sandbox.](https://www.promigence.ai/docs/reference/api/files#post-v1-sandboxes-id-files-extract) - [GET /v1/sandboxes/{id}/files/list List a directory. ?path= , plus ?recursive=1 , ?depth=N , ?limit=N and ?hidden=0 .](https://www.promigence.ai/docs/reference/api/files#get-v1-sandboxes-id-files-list) - [POST /v1/sandboxes/{id}/files/mkdir Create a directory. parents is mkdir -p and makes an existing directory a success; without it a missing parent is a 404 and an existing path is a conflict, which is what a caller using the call as a lock wants.](https://www.promigence.ai/docs/reference/api/files#post-v1-sandboxes-id-files-mkdir) - [POST /v1/sandboxes/{id}/files/move Rename or move a path.](https://www.promigence.ai/docs/reference/api/files#post-v1-sandboxes-id-files-move) - [GET /v1/sandboxes/{id}/files/search Find files under ?path= .](https://www.promigence.ai/docs/reference/api/files#get-v1-sandboxes-id-files-search) - [GET /v1/sandboxes/{id}/files/stat Size, mode, mtime and kind for one path.](https://www.promigence.ai/docs/reference/api/files#get-v1-sandboxes-id-files-stat) ## Ports and terminal [All 8 in full](https://www.promigence.ai/docs/reference/api/ports-and-terminal) - [GET /v1/sandboxes/{id}/ports List this sandbox's preview URLs.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#get-v1-sandboxes-id-ports) - [POST /v1/sandboxes/{id}/ports Mint a preview URL for a port in the sandbox.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#post-v1-sandboxes-id-ports) - [DELETE /v1/sandboxes/{id}/ports/{token_or_port} Revoke one URL by its token, or every URL for a port by the port number.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#delete-v1-sandboxes-id-ports-token-or-port) - [GET /v1/sandboxes/{id}/pty A WebSocket terminal, relayed byte for byte.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#get-v1-sandboxes-id-pty) - [GET /v1/sandboxes/{id}/ssh The keys this sandbox will accept over SSH, and for how long.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#get-v1-sandboxes-id-ssh) - [POST /v1/sandboxes/{id}/ssh Authorise an ssh-ed25519 public key for this sandbox and mint the short-lived credential an SSH connection to it uses.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#post-v1-sandboxes-id-ssh) - [DELETE /v1/sandboxes/{id}/ssh/{key_id} Revoke one key by id or fingerprint, and the access credential issued with it.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#delete-v1-sandboxes-id-ssh-key-id) - [GET /v1/sandboxes/{id}/ssh/connect A WebSocket carrying the SSH byte stream, relayed byte for byte.](https://www.promigence.ai/docs/reference/api/ports-and-terminal#get-v1-sandboxes-id-ssh-connect) ## Secrets [All 3 in full](https://www.promigence.ai/docs/reference/api/secrets) - [GET /v1/secrets The calling key's project's secret names and shapes, and for a bound secret its urls and env as POST /v1/secrets answers them.](https://www.promigence.ai/docs/reference/api/secrets#get-v1-secrets) - [POST /v1/secrets Store a secret in the calling key's project (the same name may hold a different value in another project).](https://www.promigence.ai/docs/reference/api/secrets#post-v1-secrets) - [DELETE /v1/secrets/{name} Remove a secret.](https://www.promigence.ai/docs/reference/api/secrets#delete-v1-secrets-name) ## Organisation [All 24 in full](https://www.promigence.ai/docs/reference/api/organisation) - [GET /v1/invites Invites waiting for your verified email address, from any organization.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-invites) - [POST /v1/invites/{invite_id}/accept Accept an invite and join the organization.](https://www.promigence.ai/docs/reference/api/organisation#post-v1-invites-invite-id-accept) - [POST /v1/invites/{invite_id}/decline Decline an invite sent to your verified email address.](https://www.promigence.ai/docs/reference/api/organisation#post-v1-invites-invite-id-decline) - [GET /v1/me Who you are, what your limits are, what you have spent, and what trial credit is left.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-me) - [GET /v1/me/ledger The rows behind spend: usage recorded while each sandbox runs and when it ends.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-me-ledger) - [GET /v1/me/outcomes What the organization got this month, measured from its own runs and sandboxes: runs and sandboxes started, the median time to ready, failures on our side that were not billed and what was given back, hours paused and what they would have cost running, failed sandboxes kept to reopen, and for runs of two or more sandboxes how many times faster than one after another and the time not spent waiting.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-me-outcomes) - [GET /v1/orgs The organizations you belong to, your role in each, and which one is your default.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-orgs) - [POST /v1/orgs Create an organization.](https://www.promigence.ai/docs/reference/api/organisation#post-v1-orgs) - [PATCH /v1/orgs/{org} Rename an organization.](https://www.promigence.ai/docs/reference/api/organisation#patch-v1-orgs-org) - [DELETE /v1/orgs/{org} Delete an organization.](https://www.promigence.ai/docs/reference/api/organisation#delete-v1-orgs-org) - [GET /v1/orgs/{org}/audit The organization's audit log, newest first: keys minted and revoked, invites, role changes, removals, projects, billing events, suspension, and what support did to the organization (shown as Promigence support ).](https://www.promigence.ai/docs/reference/api/organisation#get-v1-orgs-org-audit) - [POST /v1/orgs/{org}/default Make this organization the one a sign-in and the CLI use when none is named.](https://www.promigence.ai/docs/reference/api/organisation#post-v1-orgs-org-default) - [GET /v1/orgs/{org}/invites Pending invites to an organization.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-orgs-org-invites) - [POST /v1/orgs/{org}/invites Invite an email address.](https://www.promigence.ai/docs/reference/api/organisation#post-v1-orgs-org-invites) - [DELETE /v1/orgs/{org}/invites/{invite_id} Revoke a pending invite.](https://www.promigence.ai/docs/reference/api/organisation#delete-v1-orgs-org-invites-invite-id) - [POST /v1/orgs/{org}/invites/{invite_id}/resend Send a pending invite's email again: the same invite, its 14 days counted again from now.](https://www.promigence.ai/docs/reference/api/organisation#post-v1-orgs-org-invites-invite-id-resend) - [GET /v1/orgs/{org}/members The members of an organization and their roles.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-orgs-org-members) - [PATCH /v1/orgs/{org}/members/{user_id} Change a member's role.](https://www.promigence.ai/docs/reference/api/organisation#patch-v1-orgs-org-members-user-id) - [DELETE /v1/orgs/{org}/members/{user_id} Remove a member (owners, signed in), or leave (your own user id, or me ).](https://www.promigence.ai/docs/reference/api/organisation#delete-v1-orgs-org-members-user-id) - [GET /v1/orgs/{org}/projects An organization's projects, each with what it was billed this calendar month (UTC): month and month_spend_usd , the figure its monthly cap is checked against.](https://www.promigence.ai/docs/reference/api/organisation#get-v1-orgs-org-projects) - [POST /v1/orgs/{org}/projects Create a project.](https://www.promigence.ai/docs/reference/api/organisation#post-v1-orgs-org-projects) - [PATCH /v1/orgs/{org}/projects/{project} Rename a project, set its monthly cap, or both.](https://www.promigence.ai/docs/reference/api/organisation#patch-v1-orgs-org-projects-project) - [DELETE /v1/orgs/{org}/projects/{project} Delete a project with no working keys, no snapshots, no builds running, no failure captures and no sandbox that has not ended.](https://www.promigence.ai/docs/reference/api/organisation#delete-v1-orgs-org-projects-project) - [POST /v1/orgs/{org}/projects/{project}/move Move a project to another organization: its snapshots and secrets go with it, its past runs stay with the organization that paid for them, in its default project, and every key of the project is revoked (mint new ones there).](https://www.promigence.ai/docs/reference/api/organisation#post-v1-orgs-org-projects-project-move) ## Billing [All 10 in full](https://www.promigence.ai/docs/reference/api/billing) - [GET /v1/billing Plan, card on file, this month's usage, and the upcoming invoice preview.](https://www.promigence.ai/docs/reference/api/billing#get-v1-billing) - [POST /v1/billing/checkout Start a card-setup checkout.](https://www.promigence.ai/docs/reference/api/billing#post-v1-billing-checkout) - [GET /v1/billing/history Your billing history, newest first: every credit you received, with what is left of it and when it expires, and every payment (invoices paid, payments that failed, refunds).](https://www.promigence.ai/docs/reference/api/billing#get-v1-billing-history) - [POST /v1/billing/portal A link to the billing portal.](https://www.promigence.ai/docs/reference/api/billing#post-v1-billing-portal) - [POST /v1/credits/claim The claim the page sends: the link's token, the accepted terms version and the page's browser check.](https://www.promigence.ai/docs/reference/api/billing#post-v1-credits-claim) - [POST /v1/credits/claim-link A single-use link (15 minutes) to the page where the free credit is claimed ( promigence credits claim opens it).](https://www.promigence.ai/docs/reference/api/billing#post-v1-credits-claim-link) - [GET /v1/credits/offer Your account's free credit: claimable (and how much, until when), claimed, being checked, needs a card, or none.](https://www.promigence.ai/docs/reference/api/billing#get-v1-credits-offer) - [GET /v1/pricing Your organization's price list, read live on every call from what billing charges: the per-second rates, every sandbox shape on sale and its price (a snapshot build is billed at its tier's), the limits, the free credit and the plan they come from ( scope: organization ).](https://www.promigence.ai/docs/reference/api/billing#get-v1-pricing) - [GET /v1/referrals Your referral code and its offer ("Give $X, get $Y"), your referrals by status, what they earned you, the referral you came through, and your credit that expires.](https://www.promigence.ai/docs/reference/api/billing#get-v1-referrals) - [POST /v1/referrals/apply Apply a referral code to your organization: before its first paid invoice and within the offer's window after the organization was created.](https://www.promigence.ai/docs/reference/api/billing#post-v1-referrals-apply) ## Keys and sign-in [All 12 in full](https://www.promigence.ai/docs/reference/api/keys-and-sign-in) - [GET /v1/auth/claim The page where the free credit is claimed, in a browser: the offer, the terms to accept, and the Claim button.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#get-v1-auth-claim) - [GET /v1/auth/cli-callback The page a browser lands on after sign-in; in headless mode it shows the code to paste back.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#get-v1-auth-cli-callback) - [POST /v1/auth/cli/requests Start promigence login through the console: register the sign-in request (the PKCE S256 challenge, the state, the local port the CLI listens on or none to paste the code, the computer's name and the new key's name) and get the authorize page to open for it.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#post-v1-auth-cli-requests) - [POST /v1/auth/cli/token Finish promigence login after you authorized the CLI in the browser: exchange the one-time code the authorize page gave the CLI, with the PKCE verifier whose S256 challenge the CLI sent there, for an API key ( api_key , in this answer only).](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#post-v1-auth-cli-token) - [GET /v1/auth/config What promigence login needs to start a sign-in: the identity domain, client id and scopes, and the console page where you authorize the CLI ( console_authorize_url , when it is offered).](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#get-v1-auth-config) - [POST /v1/auth/invite Redeem an invite code for one sign-in attempt, before the sign-in starts ( promigence signup does it for you).](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#post-v1-auth-invite) - [POST /v1/auth/invite/release Give back the place a redeemed invite code holds for a sign-in attempt that ended without an account (it timed out or was cancelled), so the next attempt can redeem the code at once ( promigence signup does it for you).](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#post-v1-auth-invite-release) - [POST /v1/auth/session Exchange an identity token for a Promigence API key.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#post-v1-auth-session) - [GET /v1/keys List your org's keys: with an API key, its own project's; with an identity token, every project's.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#get-v1-keys) - [POST /v1/keys Mint a key. api_key is in the 201 response and is never retrievable again.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#post-v1-keys) - [DELETE /v1/keys/{key_id} Revoke a key, and every key it minted (and every key those minted): also_revoked lists them.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#delete-v1-keys-key-id) - [POST /v1/orgs/{org}/keys Mint a key in an organization you belong to, in one of its projects.](https://www.promigence.ai/docs/reference/api/keys-and-sign-in#post-v1-orgs-org-keys) [The same operations from the CLI](https://www.promigence.ai/docs/cli) · [from TypeScript](https://www.promigence.ai/docs/sdk) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/sdk # TypeScript SDK The SDK is `@promigence/sdk` (import or require, Node.js 20 or newer; the `promigence` CLI package carries the same SDK), with two surfaces: a native client, and a compatibility `Sandbox` class with the familiar sandbox calls, so most existing code keeps working after a one-line import change. Terminal ``` npm i @promigence/sdk ``` Using Python? See the [Python SDK](https://www.promigence.ai/docs/sdk-python). ## The native client Three calls cover a run: quote, fan out, read the report. Quote, run, report TypeScript ``` import { PromigenceClient } from "@promigence/sdk"; const client = new PromigenceClient(); // reads PROMIGENCE_API_KEY, or the key signup stored // 1, know the ceiling first (the snapshot from the quickstart) const quote = await client.runs.quote({ snapshot: "myapp", count: 20 }); console.log(quote.max_cost); // 0.828: 20 small sandboxes for their whole 15 minutes // 2, fan out under a hard cap const run = await client.runs.start({ snapshot: "myapp", count: 20, spendCap: 1, exec: { sh: "cd /work/repo && npm test" }, }); // 3, the number about your environments await client.runs.waitDone(run.run_id); const report = await client.runs.report(run.run_id); console.log(report.totals.env_verified); console.log(report.totals.env_failed); // ← ours console.log(report.totals.task_failed); // ← yours console.log(report.cost?.charged); // what was billed, never more than the cap ``` ## Drop-in compatibility Reimplemented from published typings. No third-party source, nothing proxied: migrating should be an import change, not a project. Existing sandbox call sites TypeScript ``` // Familiar sandbox calls keep working: create, commands.run, files and kill // behave as you expect, so a migration is one import line and an API key, // not a rewrite. import { readFile } from "node:fs/promises"; import { Sandbox } from "@promigence/sdk"; // A snapshot, not a template: the environment was built and verified once, and // this is that exact environment. `spendCap` sets the ceiling; without it your // organisation's default applies. const sandbox = await Sandbox.create("myapp", { spendCap: 1 }); const patch = await readFile("fix.diff", "utf8"); // your diff await sandbox.files.write("/tmp/patch.diff", patch); const res = await sandbox.commands.run("cd /work/repo && git apply /tmp/patch.diff && npm test"); console.log(res.exitCode, res.stdout); await sandbox.kill(); // the clock stops here: billing is per second ``` Where a method would hand you an unverified box, the SDK throws and names the alternative rather than quietly doing something else. sandbox.probe() asks whether the verified files are still as they were built, on a snapshot that recorded them: the same check that decides whether a failure was ours or yours, asked before you spend the episode. A snapshot built from an image or from a connected repository records none yet, so probe has nothing to compare there; name a file with its digest instead (PATH=blake3:). ## Errors carry a fix Every error has a stable code, an HTTP status, an exit code and a `fix` string. An error an agent cannot act on becomes a retry loop. Structured failure TypeScript ``` import { PromigenceError } from "@promigence/sdk"; try { await client.runs.start({ snapshot: "myapp", count: 20, spendCap: 0.5 }); } catch (e) { if (e instanceof PromigenceError) { console.error(e.code); // "cap_exceeded" console.error(e.message); // "quote $0.83 exceeds remaining spend cap $0.50" console.error(e.fix); // every error carries a fix, it is not optional console.error(e.exitCode); // 5 } } ``` [Every error code, what it means, and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/sdk-python # Python SDK The `promigence` package on PyPI, version 0.1.0b7, for Python 3.9 or newer. It has two parts: a `Sandbox` class for working in one sandbox, and the `Promigence` client for everything else the API does. Each has an async twin. Terminal ``` pip install promigence ``` It brings one dependency with it, `httpx`. Using TypeScript instead? The TypeScript SDK has the same two parts. [TypeScript SDK](https://www.promigence.ai/docs/sdk) ## Sign in The SDK finds your API key the way the CLI does, and the first match wins: the `api_key=` argument, then the `PROMIGENCE_API_KEY` environment variable, then the key `promigence login` saved on this machine. Terminal ``` export PROMIGENCE_API_KEY=... # or sign in once with: promigence login ``` Every run has a spend cap in US dollars: `spend_cap=`, else `PROMIGENCE_SPEND_CAP`, else your organization's default. ## Start a sandbox, run a command `Sandbox.create()` starts a sandbox from the built-in `promigence/base` snapshot. Pass a snapshot ID or alias, or a template's name, to start from another. One sandbox, one command Python ``` from promigence import Sandbox with Sandbox.create(spend_cap=1) as sb: # starts from promigence/base result = sb.commands.run("python3 -c 'print(6 * 7)'") print(result.stdout) # 42 print(result.exit_code) # 0 # leaving the block ends the sandbox ``` A command that exits non-zero raises `CommandExitError`; pass `throw_on_exit=False` to get its result instead. Each command takes a `timeout_ms`, and every duration in the SDK is in milliseconds. To start from a container image, name it with a tag or a digest and pass `allow_build=True`. The first use builds a snapshot of the image, billed per second at its size's rate while it builds. Later sandboxes reuse it. From an image Python ``` sb = Sandbox.create(image="python:3.12", allow_build=True, spend_cap=1) ``` ## Files Write, read, list, remove Python ``` sb.files.write("/work/notes.txt", "hello\n") print(sb.files.read("/work/notes.txt")) # hello print([e.name for e in sb.files.list("/work")]) sb.files.remove("/work/notes.txt") ``` `files.read` returns text. For binary files, pass `format="bytes"`. ## Pause and resume Python ``` sb.pause() # not billed by the second while paused sb.resume() # back where it was sb.set_auto_pause(300) # or let it pause itself after 5 idle minutes ``` A paused sandbox keeps its files and is not billed by the second. Commands left running in the background end at the pause. [How long a paused sandbox is kept](https://www.promigence.ai/docs/limits) ## Fork `Sandbox.fork(snapshot, count=N)` starts N identical sandboxes from one snapshot and returns when all of them are ready. To fork a sandbox as it is now, save it as a snapshot first. Five copies of a sandbox Python ``` from promigence import Promigence, Sandbox with Promigence() as client: saved = client.sandboxes.snapshot(sb.sandbox_id, alias="my-env") copies = Sandbox.fork(saved["snapshot_id"], count=5, spend_cap=2) for copy in copies: print(copy.commands.run("ls /work").stdout) copy.kill() ``` ## End a sandbox `sb.kill()` ends a sandbox and stops its bill, and returns `False` if it had already ended. Leaving a `with` block calls it for you. `set_timeout(timeout_ms)` changes how long a sandbox may run. ## Errors Everything the SDK raises on purpose is a `PromigenceError`. It carries a stable `code`, a `message`, a `fix` and a `docs` link to the code's row on the errors page, plus the HTTP `status` and `request_id` when the API answered, and the CLI's `exit_code`. Its subclasses name the cases you are likely to catch: `AuthError`, `NotFoundError`, `RateLimitError` (with `retry_after_ms`), `SpendCapError`, `PromigenceTimeoutError` and `InvalidArgumentError`. `EnvFailedError` means the environment failed, which is ours and never counted against your code. `CommandExitError` is a command that failed, and `CommandTimeoutError` one that ran past its `timeout_ms`. Your failure or ours Python ``` from promigence import CommandExitError, PromigenceError, Sandbox try: with Sandbox.create(spend_cap=1) as sb: sb.commands.run("cd /work && pytest -q") except CommandExitError as e: print("the tests failed with exit code", e.exit_code) except PromigenceError as e: print(e.code, e.fix, e.docs) ``` [Every error code, what it means, and whether it was billed](https://www.promigence.ai/docs/errors) ## Async `AsyncSandbox` and `AsyncPromigence` have the methods of `Sandbox` and `Promigence`. Await them. Python ``` import asyncio from promigence import AsyncSandbox async def main(): async with await AsyncSandbox.create(spend_cap=1) as sb: result = await sb.commands.run("echo hi") print(result.stdout) asyncio.run(main()) ``` The SDK calls the same routes as the CLI. The API reference lists every one, with its parameters and answers. [API reference](https://www.promigence.ai/docs/reference/api) --- Page: https://www.promigence.ai/docs/errors # Errors and exit codes Every failure is attributed. An environment failure is ours: kept out of your result and retried once before hand-over. It is not billed before the sandbox reaches you; after that, when our side shows the failure was ours, the work since its last snapshot (or since it started), up to 24 hours, is credited back. A task failure is yours: billed, because the environment worked. ## Exit codes | Exit | Meaning | Billing | |---|---|---| | 0 | Success | billed | | 1 | Our own failure, or a command this version of the CLI does not implement | not billed | | 2 | Usage error: bad or missing arguments, or an unknown command | not billed | | 3 | Environment failure: the environment failed, not your command | not billed before hand-over; after it, credited back when our side shows it was ours | | 4 | Task failure: your command failed | billed | | 5 | Refused by a spend cap or an account limit; nothing started | not billed | | 6 | The snapshot is not verified | a build its checks refused: the time it ran, unless the failure was ours; otherwise not billed | | 7 | Not signed in, or not allowed yet: a missing, invalid or expired API key, an account that must finish its setup questions first, or a blocked account | not billed | | 8 | Not found: no such snapshot, run or sandbox | not billed | | 9 | The API could not be reached | not billed | | 10 | Rate limited (the CLI honours Retry-After), or the monthly data-out cap is reached | not billed | | 11 | A wait expired. Nothing was killed | unchanged | | 12 | Partial: some sandboxes did not start, or were stopped at the spend cap, at their timeout, or by Promigence support | billed for what ran | | 13 | `agent-guide --check` only: the files would change; nothing was written | not billed | | 125 | `exec --sandbox` only: our own failure. Otherwise your command's own exit code passes through (a command that is not found exits 127) | unchanged | | 130 | Interrupted by the client (Ctrl-C or a signal); the sandboxes are killed unless `--keep` | billed for what ran | ## Error codes An HTTP status of 0 marks a code the CLI or the SDK makes itself; the API never sends it. | Code | Category | HTTP | Exit | Billed | Meaning | Fix | |---|---|---|---|---|---|---| | fork_failed | env | 502 | 3 | no | The sandbox could not be started. | Not billed. A run with a command is retried once automatically; otherwise re-run. If it repeats, re-verify the snapshot: `promigence snapshot verify {snapshot_id}`. | | start_timeout | env | 502 | 3 | no | The sandbox did not answer its first command within {deadline_ms} ms. | Not billed. A run with a command is retried once automatically; otherwise start it again. If it keeps happening, tell support@promigence.ai the run id. | | readiness_failed | env | 502 | 3 | no | The sandbox failed its readiness check. | Not billed: the sandbox was set aside before it was handed to you. A run with a command is retried once automatically; otherwise start it again. If it keeps failing, re-verify the snapshot: `promigence snapshot verify {snapshot_id}`. | | verify_too_slow | env | 502 | 3 | no | The snapshot's verify step took longer in this sandbox than its limit allows. | Not billed. A run with a command is retried once automatically; otherwise start it again. If it keeps happening, re-verify the snapshot: `promigence snapshot verify {snapshot_id}`. | | verify_each_failed | env | 502 | 3 | no | Verify_each run failed in the fork (exit {exit_code}, digest {digest}). | Not billed. A run with a command is retried once automatically. If it repeats, the snapshot no longer reproduces: rebuild with `promigence snapshot create ...`. | | toolchain_mismatch | env | 502 | 3 | no | Toolchain check `{argv}` in the fork gave digest {got}, the verified snapshot recorded {expected}. | The fork's toolchain differs from the verified snapshot; not billed. Re-run; if it repeats, rebuild the snapshot. | | sandbox_unresponsive | env | 502 | 3 | yes, unless ours | The sandbox stopped responding. | Billed for the time used, unless our side shows the cause was ours: then it is credited back (after a review if many are credited in one day), as the run report shows. Not retried automatically once your command has started. To run it again: `promigence run replay {run_id} --sandbox {sandbox_id}`. If you think the cause was ours, tell support@promigence.ai the run id. | | oom_within_tier | env | 502 | 3 | no, credited back | The sandbox stopped on our side while within the tier's {tier_mib} MiB. | Our fault, not yours: credited back (at least the work lost since your last snapshot of this sandbox, up to 24 hours; a sandbox under 24 hours with no snapshot is not charged), after a review if many are credited in one day. Replay: `promigence run replay {run_id} --sandbox {sandbox_id}`. | | disk_full_within_tier | env | 502 | 3 | no, credited back | The sandbox stopped on our side while within its {tier_disk_gib} GiB of disk. | Our fault, not yours: credited back (at least the work lost since your last snapshot of this sandbox, up to 24 hours; a sandbox under 24 hours with no snapshot is not charged), after a review if many are credited in one day. Replay: `promigence run replay {run_id} --sandbox {sandbox_id}`. | | sandbox_interrupted | env | 502 | 3 | no, credited back | The sandbox was interrupted by a platform event. | Not caused by your work, and credited back: at least the work since your last snapshot of this sandbox, up to 24 hours; a sandbox under 24 hours with no snapshot is never charged. To run it again: `promigence run replay {run_id}`. | | integrity_mismatch | env | 502 | 3 | yes, unless ours | The environment differs from the verified snapshot at {path}. | Not billed when we confirm the stored snapshot itself differs at that path; otherwise (only this sandbox's copy changed, or the check could not be made) the time used is billed. To run it again: `promigence run replay {run_id} --sandbox {sandbox_id}`; if it happens again, rebuild the snapshot. | | egress_unavailable | env | 502 | 3 | yes, unless ours | The sandbox's outbound network was unavailable. | Not billed when we confirm the outage on our side, after a review if many are credited in one day; otherwise the time used is billed. To run it again: `promigence run replay {run_id}`. | | service_timeout | env | 504 | 3 | yes, unless ours | The service's own time limit ({deadline_ms} ms) was reached before your command's timeout. | When the cause was ours (our service restarted), it is credited back: at least the work since your last snapshot of this sandbox, up to 24 hours. Otherwise the time used is billed. For long commands, set `timeout_ms`. To run it again: `promigence run replay {run_id} --sandbox {sandbox_id}`. | | preempted | preempt | 502 | 3 | no, credited back | The preemptible sandbox was stopped early, as preemptible runs can be. | Our doing, not yours: credited back (at least the work lost since your last snapshot of this sandbox, up to 24 hours; a sandbox under 24 hours with no snapshot is never charged). This run asked to be preemptible, which is priced below the standard rate for exactly this reason. To run it again: `promigence run replay {run_id} --sandbox {sandbox_id}`; or run it without `preemptible` to pay the standard rate and not be stopped early. | | verify_did_not_cover | snapshot | 422 | 4 | yes | `{path}` is missing but was not under a verified path; the snapshot's verify did not cover it. | Billed: the environment matched what `verify` checked. Broaden `verify` (or `setup`) so the path is produced and covered, then `promigence snapshot create ...`. | | grader_failed | grader | 422 | 3 | yes, unless ours | The grade could not be computed ({kind}). | Not a task failure. The time your grader ran is billed like the sandbox's own; a grade that failed on our side is not. Check that `grade.cmd` exits within `grade.timeout_ms` and that its output matches `grade.score` (exit \| last_line_json \| tap), then re-run. | | nonzero_exit | task | 422 | 4 | yes | Command exited {exit_code}. | The environment was verified; the command failed. Inspect: `promigence exec output {exec_id}`. | | grade_not_passed | task | 422 | 4 | yes | The task completed and its grade did not pass (the grader exited {exit_code}). | Your grader failed the work; the task's command succeeded. | | task_timeout | task | 422 | 4 | yes | Command exceeded timeout_ms={timeout_ms}. | Raise `--timeout` (billed per second used, so a longer timeout only costs what runs) or shorten the task. | | oom_over_tier | task | 422 | 4 | yes | The process was killed for exceeding the tier's {tier_mib} MiB of memory. | Rebuild the snapshot on a larger tier (`promigence snapshot create … --tier medium\|large`; see `promigence agent-guide --section cost`) or reduce the task's memory. | | disk_over_tier | task | 422 | 4 | yes | The sandbox ran out of its {tier_disk_gib} GiB of disk. | Pick a larger tier or write less; the disk is sized to the tier quota. | | shutdown_by_task | task | 422 | 4 | yes | The sandbox shut itself down ({kind}). | Billed as the task's outcome: a command in the sandbox shut it down. Keep the task from doing that; if nothing in it should have, check what the agent ran. | | modified_by_task | task | 422 | 4 | yes | `{missing}` was removed or changed inside the sandbox; the snapshot's copy is intact. | Billed as the task's outcome: the sandbox started verified and something it ran deleted or changed `{path}`. Keep the task from modifying verified paths, or recreate what it needs first. | | cap_killed | cap | 402 | 12 | yes | Sandbox killed when its accrued spend reached the spend cap ({spend_cap}). | The seconds it ran are billed, up to the cap. Raise `--cap` or `PATCH /sandboxes/:id` earlier. | | cap_exceeded | cap | 409 | 5 | no | Quote {max_cost} exceeds remaining spend cap {remaining}. | Raise `--cap`, lower `--count`/`--timeout`, or pass `--allow-partial` to launch what fits. | | cap_paused | cap | 402 | 5 | no | Sandbox {sandbox_id} is paused: its run reached its spend cap ({spend_cap}). | Its files and state are kept, and paused time is not billed. Raise the run's cap to go on: `promigence sandbox resume {sandbox_id} --cap ` (`spend_cap` on POST /v1/sandboxes/{sandbox_id}/resume). Or end it: `promigence sandbox kill {sandbox_id}`. | | credits_paused | cap | 402 | 5 | no | Sandbox {sandbox_id} is paused: the organization's credits ran out. | Its files and state are kept, and paused time is not billed. Add a card to go on (owners: `promigence billing card`; members ask an owner), then resume it: `promigence sandbox resume {sandbox_id}`. Or end it: `promigence sandbox kill {sandbox_id}`. | | aborted_by_client | other | 200 | 130 | yes | Sandbox killed by the client. | Nothing to fix; billed for the seconds used. | | stopped_by_support | other | 200 | 12 | yes, unless ours | Stopped by Promigence support: {reason}. | Billed for the seconds it ran, as a kill is, unless support found the cause was on our side; then that time is credited back. Questions: tell support@promigence.ai the sandbox id. | | expired | other | 200 | 12 | yes | Sandbox timeout reached (counted from hand-off). | Raise `--timeout` if the task needs longer. | | not_started | other | 200 | 12 | no | Sandbox not started: outside the spend cap. | Raise `--cap`; with `--allow-partial` only what fits is launched. | | superseded | other | 200 | 0 | no | Attempt 1 superseded by a successful retry. | Nothing to fix; attempt 1 is unbilled. | | usage | other | 400 | 2 | no | {detail}. | {detail}. See `promigence {command} --help`. | | internal | other | 500 | 1 | no | Internal error. | Not your fault. Re-run; if it repeats, tell support@promigence.ai the run or sandbox id and the time. | | auth | other | 401 | 7 | no | Missing or invalid API key. | Set PROMIGENCE_API_KEY or run `promigence auth login --from-env VAR`. No key yet: `promigence login` (sign in) or https://promigence.ai. | | forbidden | other | 403 | 7 | no | {detail}. | Do what the message names: sign in (`promigence login`), use a full-access key (`promigence keys create`) or one from that org, or ask an owner. | | not_found | other | 404 | 8 | no | {kind} `{id}` not found. | Check the id; aliases resolve in your org first, then public snapshots (`promigence examples`). | | unreachable | other | 503 | 9 | no | Cannot reach {url}. | Retry in a moment. If the API answered this, the fault is ours: if it repeats, email support@promigence.ai with the sandbox or run id. If the API itself did not answer, check PROMIGENCE_API_URL and your connection. | | rate_limited | other | 429 | 10 | no | Rate limited by {host}; retry after {retry_after_s} s. | Wait `Retry-After` seconds, then retry. If the limit is an image registry's, not this API's, a `registry_secret` holding your own login for it usually raises it. Otherwise lower concurrency (see `GET /me` limits). | | timeout | other | 504 | 11 | no | Wait of {wait_timeout} expired; nothing was killed. | Run the id-based command: `{next}`. | | not_verified | other | 409 | 6 | no | Snapshot {snapshot_id} is not verified (build {build_id}: {state}). | Wait for the build: `promigence snapshot status {build_id} --wait`. | | snapshot_incompatible | other | 409 | 6 | no | Snapshot {snapshot_id} can no longer run on the platform. | Nothing was started or billed. Rebuild it from the same source: POST /v1/snapshots (`promigence snapshot create`). | | storage_limit_reached | other | 409 | 5 | no | {detail}. | Nothing was stored or charged, and nothing already stored was removed: delete what you no longer need, or move to a plan that keeps more. | | resume_unavailable | env | 503 | 3 | no | Sandbox {sandbox_id} is safe and still paused; it could not be resumed right now. | Your files are kept and nothing was billed. Retry in a minute. If it keeps happening, email support@promigence.ai with the sandbox id. | | sandbox_unreachable | env | 503 | 3 | no | Sandbox {sandbox_id} could not be reached just now; nothing was changed. | Not billed for this call, and the sandbox is as it was. Retry in a few seconds. If it keeps happening, email support@promigence.ai with the sandbox id. | | capacity_busy | env | 503 | 3 | no | No capacity free right now. | Not billed, and nothing was started. Nothing was free in time: start it again in a few minutes, or lower `--count` to need fewer at once. | | region_at_capacity | env | 503 | 3 | no | Capacity is full right now. | Not billed, and nothing was started. Retry shortly, or lower `--count`. | | builder_unavailable | env | 503 | 3 | no | New snapshots cannot be built right now. | Not billed, and nothing was stored. Nothing here can build at all, so this is not a busy queue and does not clear itself by waiting, and a smaller run does not help. Snapshots you have already built still run, so re-use one (`promigence snapshot list`). If you asked for a specific CPU, drop that and retry; otherwise retry shortly, and tell support@promigence.ai the time if it keeps happening. | | builder_busy | env | 503 | 3 | no | Snapshot builds are backed up; retry after {retry_after_s} s. | Not billed, and nothing was stored. Other builds are ahead of this one: submit it again in {retry_after_s} s. Builds already accepted keep their place in the queue and finish on their own (`promigence snapshot status --wait`). | | overloaded | env | 503 | 3 | no | The API is at capacity; retry in {retry_after_s} s. | Not billed, and nothing was started. Send the same request again in {retry_after_s} s; the SDKs and the CLI do this for you. | | tier_unavailable | env | 503 | 3 | no | The {tier} tier ({vcpus} vCPU / {mem_gib} GiB) is not available yet. | Not billed. Use a smaller tier (`promigence snapshot create … --tier`; a fork runs on its snapshot's), or write to support@promigence.ai to have {tier} enabled for your account. | | snapshot_unavailable | env | 409 | 3 | no | Snapshot {snapshot_id} is no longer available: it could not be saved. | Not billed, and nothing was started. It cannot be started again: take a new snapshot of a running sandbox (`promigence sandbox snapshot `) or build it again (`promigence snapshot create ...`), then remove this one: `promigence snapshot delete {snapshot_id}`. | | capacity_limit | env | 409 | 3 | no | {requested} {tier} sandboxes at once is more than one run can start at once; at most {max_at_once}. | Not billed; nothing started. Run at most {max_at_once} at once (lower `--count`), or use a smaller tier. | | build_timeout | other | 422 | 4 | yes | The build ran past its {limit_min}-minute limit. | Nothing was stored; the {limit_min} minutes it ran are billed. Shorten `setup` (at most 64 steps, {limit_min} minutes in all) or bake the slow part into the image. | | dockerfile_build_failed | other | 400 | 2 | yes | Your image could not be built from the Dockerfile: {detail}. | Nothing was stored; the time the build ran is billed. Fix the Dockerfile (the lines above are the end of your own build output) and run `promigence snapshot create --dockerfile PATH ...` again. | | image_unresolvable | other | 422 | 2 | no | `{image}` could not be resolved to a digest: {detail}. | Nothing was stored and nothing was billed. Check the name and tag; a private image needs `registry_secret` naming a stored secret that holds `user:password` (`promigence secrets set`). You can also pass the image already pinned as NAME@sha256:. | | registry_unavailable | env | 503 | 3 | no | `{image}` could not be resolved to a digest because its registry did not answer usably: {detail}. | Not billed, and nothing was stored. Your image is not at fault: submit it again in {retry_after_s} s. Snapshots you have already built from it still run (`promigence snapshot list`). | | enoent | other | 404 | 8 | no | `{argv0}` not found in the sandbox. | Check the command name; install the program in the image or in a setup step; for a shell builtin or a pipeline, run it through a shell: `-- sh -c '...'`. | | trial_credits_exhausted | cap | 402 | 5 | no | Trial credits left ({remaining}) do not cover this ({needed}). | Add a card to keep going (owners: `promigence billing card`, or POST /v1/billing/checkout; members ask an owner). Remaining credits are used first; running sandboxes finish. | | credit_unclaimed | other | 402 | 5 | no | This account has free credit waiting to be claimed. | Claim it in your browser: `promigence credits claim` (owners; members ask an owner). Or add a card: `promigence billing card`. Nothing was started or charged. | | setup_required | other | 403 | 7 | no | Finish setting up your account before starting new work. | Open {setup_url} and answer the setup questions (under a minute), then run this again. Nothing was started or charged. | | card_required | other | 402 | 5 | no | A card is required for new work since {effective_at}. | Add a card (owners: `promigence billing card`, or POST /v1/billing/checkout; members ask an owner). Your trial credits are kept and used first; reads and results stay available. | | billing_unavailable | other | 503 | 5 | no | Card payments are not open yet. | Nothing was charged. Your trial credits are kept and used first; for more credits, email support@promigence.ai. | | concurrency_limit | other | 409 | 5 | no | {live} live + {requested} requested sandboxes is over your limit of {limit}. | Wait for sandboxes to end or lower `--count` (`--allow-partial` covers the spend cap only); a retry of the same request fails the same way. Trial orgs get {trial_limit}; to raise it, email support@promigence.ai. | | egress_cap_reached | other | 403 | 5 | no | Monthly data-out cap reached: {used_gb} of {cap_gb} GB. | Use `--network none` (still allowed) or wait for the 1st (UTC). For more data out a month, email support@promigence.ai. | | project_cap_reached | cap | 403 | 5 | no | Project {project} has {remaining} of its {limit} monthly cap left; this needs {needed}. | Ask for less (`--count`, `--cap`, a shorter extension), wait for the 1st (UTC), or have an owner raise it: `promigence project cap {project} `. | | spend_limit_reached | cap | 402 | 5 | no | Today's spend limit {limit} has {remaining} left; this needs {needed}. | Running sandboxes finish. The limit resets at 00:00 UTC and grows with each paid invoice; ask for less, or email support@promigence.ai. | | billing_hold | other | 402 | 5 | no | New work is on hold: {reason}. | Running sandboxes finish. Owners: update the card with `promigence billing portal`; the hold lifts once the invoice is paid. For a disputed payment, write to support@promigence.ai. | | tier_over_plan | other | 403 | 2 | no | The {tier} tier ({vcpus} vCPU) is over the {limit} vCPU per-sandbox limit of your {plan} plan. | Use a tier of at most {limit} vCPU (`promigence snapshot create … --tier {max_tier}` is the largest; a fork runs on its snapshot's), or move to a plan that allows it: `promigence billing portal`. | | network_host_refused | other | 403 | 9 | no | {host} is not on this sandbox's allowed list, so the connection was refused. | Add it when you start the sandbox — `--allow {host}` — or drop `--allow` to let the sandbox reach anything. `promigence sandbox network ` lists everything that has been refused. | | network_policy_unsupported | env | 502 | 3 | no | This sandbox asked to reach only {allow}, and that could not be applied. | Nothing ran and nothing was billed: the sandbox was discarded rather than started without the restriction you asked for. Re-run; if it repeats, tell support@promigence.ai the run id. | | secrets_in_snapshot | other | 409 | 2 | no | Sandbox {sandbox_id} was given a secret's value, so a snapshot of it can contain that value. | To take it anyway, pass `force: true` (`promigence sandbox snapshot {sandbox_id} --force`): that snapshot, and every sandbox started from it, can then contain the secret. Otherwise snapshot a sandbox that was never given a secret, and name the secret on the runs you start from it. | | secrets_unavailable | env | 503 | 3 | no | Secrets cannot be used right now. | Not billed, and nothing that names a secret was started. Runs, commands and terminals that name no secret are unaffected, and stored secrets can still be listed and deleted. Retry shortly; if it keeps happening, tell support@promigence.ai the time. | | secret_binding_unsupported | env | 502 | 3 | no | A secret bound to a host could not be set up for this sandbox. | Nothing ran, nothing was billed, and the value never entered the sandbox. Re-run; if it repeats, tell support@promigence.ai the run id. | | idempotency_key_reused | other | 409 | 2 | no | This Idempotency-Key was used for a different request. | Nothing was started. Use a new key for a new request; send the original request again to get its original answer. | | idempotency_key_in_use | env | 409 | 3 | no | A request with this Idempotency-Key is still running. | Not billed; nothing new was started. Send the same request again in {retry_after_s} s for the first one's answer; the SDKs do this for you. | | repo_credentials_not_supported | other | 400 | 2 | no | Credentials in repository URLs are not accepted ({field}). | Nothing was built or billed. A repository URL never carries a credential. For a private repository, connect its host once for your organization (`promigence github connect` or `promigence gitlab connect`) and name it as `--repo owner/name` (`--repo gitlab:group/project`); a public one is named by its plain https:// URL, with no user name, password, token, query string or fragment in it. | | account_exists | other | 409 | 7 | no | This email address has an account that signs in with {sign_in_with}. | Nothing was created. Sign in with {sign_in_with} instead: `{sign_in_command}`. If the browser signs you in with the method you just used, open the sign-in link in a private window. If you did not create that account, write to support@promigence.ai. | | invite_invalid | other | 403 | 7 | no | This invite code is not valid. | Nothing was created. Check the code and try `promigence signup` again, or ask the person who invited you for a new code. | | invite_required | other | 403 | 7 | no | New accounts need an invite code right now. | Nothing was created. Run `promigence signup` and enter your invite code when asked. If you already have an account, sign in with the method you used before (`promigence login`). | | key_expired | other | 401 | 7 | no | This API key expired at {expired_at}. | Create a new key (`promigence keys create`, or sign in again with `promigence login`) and replace this one wherever it is used. | | account_blocked | other | 401 | 7 | no | This account is blocked. | Write to support@promigence.ai to have it reviewed. | | invalid_argument | other | 0 | 2 | no | An argument the SDK refused before sending it. | Nothing was sent or billed. The message names the argument and the form it takes: change it and call again. From the CLI, `promigence --help` lists every flag. | | unsupported | other | 0 | 2 | no | Not available in this version or on this deployment. | Nothing was sent or billed. The fix in the error names what to use instead. | | not_released | other | 0 | 1 | no | Not released in this version. | Nothing was sent or billed. Update the CLI or SDK once a release implements it (support@promigence.ai has the latest). | | task_failed | task | 0 | 4 | yes | The command exited non-zero (the SDK's CommandExitError). | The environment was verified and the command failed: read stdout and stderr on the error, or pass `throwOnExit: false` to get the result instead. A run's report calls the same failure `nonzero_exit`. | | env_failed | env | 0 | 3 | no | The sandbox ended before hand-over. | Ours, not billed. The run's report names the failure's own code (`promigence run report RUN`); start the sandbox again. | | snapshot_rejected | other | 0 | 6 | yes, unless ours | A build guard refused it; nothing was stored. | The time the build ran is billed, unless it ended on our side. Read the build log (`promigence snapshot status BUILD --log 80`): the guard named in the error says what to change (verify exited non-zero, a setup step failed, a time or size bound), then build again. | | build_failed | env | 0 | 3 | no | The build could not finish; nothing was stored. | Not charged. Build again; if it repeats, email support@promigence.ai with the build id. | | service_restart | env | 0 | 3 | no | A service restart stopped the command while its output was streaming. | Not billed: the time the command ran is credited back. The sandbox kept running; the command may have done part of its work before it stopped: run it again if that is safe. | | not_connected | other | 0 | 7 | no | The connection request ended without connecting anything. | Nothing was connected. Do what the message names, then run the connect command again; `promigence github status` (or `gitlab status`) lists what is connected. | | snapshot_failed | snapshot | 0 | 4 | yes, unless ours | A build ended with no snapshot, or the snapshot did not hold. | A build: read its log (`promigence snapshot status BUILD --log 80`), fix what it names, build again. A run: the sandbox's own failure code says what (usually `verify_did_not_cover`: broaden `verify`). | --- Page: https://www.promigence.ai/docs/reference/api/meta [API reference](https://www.promigence.ai/docs/reference/api) # Meta 4 routes of the published API contract, generated from it. ### GET/status Auth: none The same data rendered as a self-contained HTML page by the API itself. #### Answer 200 · string · text/html ### GET/v1/health Auth: none Liveness, and whether the service can start sandboxes. The cheapest call there is; use it as a readiness check. #### Answer 200 · Health · application/json build_shastring The commit this build came from; empty for a local build. Answered to a caller with a key; absent for one without. locationstring | null Where sandboxes run, in plain words (for example "US East Coast"). Absent when the service does not say. okrequiredboolean readyboolean | null Whether new sandboxes can start right now. Answered to a request made with a key; absent without one. servingboolean | null Whether the service can start new sandboxes right now. versionrequiredstring The API's version. ### GET/v1/llms.txt Auth: none The agent guide as `text/plain` — the same document `promigence agent-guide` prints. #### Answer 200 · string · text/plain ### GET/v1/status Auth: none 24 hours of synthetic check results plus service health, as JSON. This is what the status page reads. #### Answer 200 · StatusSummary · application/json checksrequiredCheckWindow The last 24 hours of synthetic checks: totals, latency percentiles, fifteen-minute buckets and the most recent failures. generated_atrequiredstring RFC 3339. servicerequiredstring servicesrequiredServiceStatus[] `api`, then `sandboxes`. versionrequiredstring [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/reference/api/snapshots [API reference](https://www.promigence.ai/docs/reference/api) # Snapshots 13 routes of the published API contract, generated from it. ### POST/v1/images/resolve Auth: API key Turn an image tag into a digest. `python:3.12` comes back as `python@sha256:…`, ready for `POST /v1/snapshots`, and you need no container tooling installed to ask. A reference that is already pinned is answered without contacting the registry. For a tag that names several architectures the answer pins what a pull of that tag would fetch and reports the `linux/amd64` build beside it; a tag with no `linux/amd64` build is refused here rather than at build time. `registry_secret` names a stored secret holding `user:password` for a private registry. #### Request body ImageResolve · application/json imagerequiredstring An image reference, a tag or a digest. registry_secretstring | null A stored secret holding the registry credentials. #### Answer 200 · ImageResolved · application/json already_pinnedrequiredboolean True when the reference was already pinned and no registry was asked. digestrequiredstring The digest `image` carries — the index's, for a tag that names several architectures, which is what a pull of that tag fetches. imagerequiredstring The pinned reference: your own name with `@sha256:…` on the end. media_typerequiredstring The media type at that digest. msrequirednumber The round trip to the registry, in milliseconds. okrequiredboolean platformrequiredstring `linux/amd64`. platform_digeststring | null The `linux/amd64` build beside the index; `null` when the tag names a single manifest. platformsrequiredstring[] Every `os/arch` the index offers. Empty for a single manifest. registryrequiredstring registry_secretstring | null The stored secret the registry was asked with, as it was named in the request. repositoryrequiredstring tagstring | null `null` when the reference named a digest rather than a tag. ### GET/v1/snapshots Auth: none List snapshots, newest first. With a key: your org's plus every public one. Without a key: the public ones only — this is what `promigence examples` calls before you have signed in. Pages are `?limit=N` (1..=500, default 50) and `?cursor=`; echo back `next_cursor` and stop when it is `null`. #### Parameters cursorquery · string limitquery · integer #### Answer 200 · SnapshotList · application/json limitrequiredinteger The page size that was applied. next_cursorstring | null Pass back as `?cursor=` for the next page; `null` on the last page. snapshotsrequiredSnapshotView[] ### POST/v1/snapshots Auth: API key Build and verify a snapshot. Returns 202 with a `build_id`; poll it. A build is billed per second at its tier's rate while it runs, for at most `max_seconds`: `build_price` is the most it can cost. If `verify` exits non-zero nothing is stored, and the time the build ran is billed. Honours `Idempotency-Key`. A private repository is built through your GitHub or GitLab connection: `repo: "github:owner/name"` or `repo: "gitlab:group/project"` (subgroups too) with an optional `ref` (branch, tag or sha; default the default branch), `from` (the snapshot it starts from, default `promigence/base`) and `track` (with an `alias`: every push to the branch builds it again, each a normal build). A repository URL with credentials in it (a user name, password, token, query string or fragment) is refused with `repo_credentials_not_supported`. #### Parameters Idempotency-Keyheader · string Makes a retried create safe: send the same key on every attempt of ONE create and it starts, and bills, once. Kept 24 hours per org. The same key with the same request (method, path and JSON body) answers with the first answer — same status, same ids — marked `Idempotent-Replayed: true`. The same key with a different request is refused with 409 `idempotency_key_reused`. A repeat that arrives while the first is still running waits for its answer, or gets 409 `idempotency_key_in_use` with `Retry-After`. Only an answer that started something is kept: a create refused before anything started leaves the key free. The SDKs send one for every create they make. #### Request body SnapshotCreate · application/json · optional aliasstring | null A name for it, unique in the project. commitstring | null The full 40-character commit sha to build (the repository form). dockerfileDockerfileSource | null Build from a Dockerfile. envmap of string Image and Dockerfile forms: environment variables for every command, terminal and SSH session in sandboxes from this snapshot (and for its own `setup`, `verify` and `start`), set over the image's own `ENV` as `docker run -e` sets them. A value may build on a variable the image sets with `${containerEnv:NAME}`, or `${containerEnv:NAME:default}` when the image may not set it: `"PATH": "${containerEnv:PATH}:/opt/tools/bin"`. fromstring | null `github:` repositories: the snapshot the build starts from, by id or alias. Default `promigence/base`. gradeGradeSpec | null The snapshot's default grader for runs that name none. grade_outputboolean Runs that use this default grader keep what it prints, as `grade_output` on `POST /v1/runs` does, unless the run says otherwise. Needs `grade`. imagestring | null A container image, `REF@sha256:`; a tag is resolved to its digest first. refstring | null `github:` repositories: a branch, a tag or a commit sha, resolved to the commit it names when the build is accepted. Default: the repository's default branch. registry_secretstring | null A stored secret holding the registry credentials for a private `image`. repostring | null A public git URL (the repository form), or `github:owner/name`: a repository the organization's GitHub connection can read (`GET /v1/integrations/github/repos`). setupOneOrMany | null Commands run once, in order, before `verify`. setup_userstring | null Image and Dockerfile forms: the user its `start`, `setup` and `verify` run as (for example the snapshot's own `user`). Default: `root`. sourcesSourceRequest[] Extra repositories cloned before `setup` (repository form only, at most 8). startstring | null A command that keeps running in every sandbox (image and Dockerfile forms). tierstring | null The sandbox size it is built and forked at. trackboolean `github:` repositories with a branch `ref` and an `alias`: every push to the branch builds the snapshot again and moves the alias to it. Each automatic build is a normal build, charged to the organization. userstring | null Image and Dockerfile forms: the user commands, terminals and SSH sessions in its sandboxes run as when they name none. A user name or uid, with an optional `:group` or `:gid`, as an image's `USER` takes it; `root` for root. Default: the image's own `USER`, as `docker run` does (root when it sets none). verifyVerifyRequest | null The command that must exit 0 for the snapshot to be stored. Required in the repository form. #### Answer 200 · SnapshotCreated · application/json ### GET/v1/snapshots/{id} Auth: API key One snapshot by id or alias. `unavailable` is set, with the reason, when this snapshot can no longer be started; it is absent while it can. #### Parameters idrequiredpath · string #### Answer 200 · SnapshotView · application/json aliasstring | null The mutable name. The id and the hash behind it are not mutable. build_idrequiredstring The build that produced it. commitrequiredstring created_atrequiredstring RFC 3339. files_digeststring | null `blake3:` of the snapshot's files and the record of what built them. The same for as long as the snapshot exists. Only on `GET /v1/snapshots/{id}`; absent when the snapshot records no file digests. historystring[] What happened to it, one line per event, oldest first: built and verified, and each time it was verified again (files unchanged). Only on `GET /v1/snapshots/{id}`. last_verified_atstring | null RFC 3339. reporequiredstring setuprequiredstring[] The commands run to prepare the workspace. snapshot_idrequiredstring sourcerequiredobject What it was built from: a repository and commit, an image and digest, or a Dockerfile and the digest of its context. The `kind` field says which. templateSnapshotTemplateRef | null The template this snapshot is, or was made from, and whether a newer version of it is out. Absent when it comes from no template. tierrequiredstring tier_assignedrequiredstring The tier it was built and verified at. Forking it at another shape is refused. unavailablestring | null Set when this snapshot can no longer be started, and why: it could not be saved. A fork of it is refused `snapshot_unavailable`. Absent while it can be started. userstring | null The user commands, terminals and SSH sessions in its sandboxes run as when they name none: its image's own `USER`, or the `user` it was created with. Absent: root. verificationrequiredobject What the verification command did when it last ran. verifiedrequiredboolean True when a verification command was recorded, which is what makes the snapshot reproducible rather than merely saved. verifyrequiredVerifyCmd visibilityrequiredstring `private` | `public`. warningsstring[] Things whoever forks this snapshot should know, one `code: sentence` per line. Absent when there are none. ### DELETE/v1/snapshots/{id} Auth: API key Remove one of your own snapshots from your catalogue. The record goes and the space is reclaimed; finished runs keep their reports, so last month's numbers stay readable. Refused while a sandbox forked from it is still running — kill those first. #### Parameters idrequiredpath · string #### Answer 200 · SnapshotDeleted · application/json aliasstring | null deletedrequiredboolean okrequiredboolean snapshot_idrequiredstring ### PUT/v1/snapshots/{id}/alias Auth: API key Move the snapshot's alias. The alias is mutable; the snapshot id and its hash are not. #### Parameters idrequiredpath · string #### Request body SnapshotAliasSet · application/json aliasrequiredstring | null #### Answer 200 · SnapshotView · application/json aliasstring | null The mutable name. The id and the hash behind it are not mutable. build_idrequiredstring The build that produced it. commitrequiredstring created_atrequiredstring RFC 3339. files_digeststring | null `blake3:` of the snapshot's files and the record of what built them. The same for as long as the snapshot exists. Only on `GET /v1/snapshots/{id}`; absent when the snapshot records no file digests. historystring[] What happened to it, one line per event, oldest first: built and verified, and each time it was verified again (files unchanged). Only on `GET /v1/snapshots/{id}`. last_verified_atstring | null RFC 3339. reporequiredstring setuprequiredstring[] The commands run to prepare the workspace. snapshot_idrequiredstring sourcerequiredobject What it was built from: a repository and commit, an image and digest, or a Dockerfile and the digest of its context. The `kind` field says which. templateSnapshotTemplateRef | null The template this snapshot is, or was made from, and whether a newer version of it is out. Absent when it comes from no template. tierrequiredstring tier_assignedrequiredstring The tier it was built and verified at. Forking it at another shape is refused. unavailablestring | null Set when this snapshot can no longer be started, and why: it could not be saved. A fork of it is refused `snapshot_unavailable`. Absent while it can be started. userstring | null The user commands, terminals and SSH sessions in its sandboxes run as when they name none: its image's own `USER`, or the `user` it was created with. Absent: root. verificationrequiredobject What the verification command did when it last ran. verifiedrequiredboolean True when a verification command was recorded, which is what makes the snapshot reproducible rather than merely saved. verifyrequiredVerifyCmd visibilityrequiredstring `private` | `public`. warningsstring[] Things whoever forks this snapshot should know, one `code: sentence` per line. Absent when there are none. ### GET/v1/snapshots/{id}/manifest Auth: none The manifest: what a `.promigence` bundle is built from. Reachable without a key for public snapshots only. #### Parameters idrequiredpath · string #### Answer 200 · SealedManifestView · application/json cached_atrequiredstring When this copy of the manifest was taken, RFC 3339. manifestrequiredSealedManifest The manifest as the API returns it: the sections that describe *how* the environment runs are replaced by their digests under `sealed`; identity, provenance and verification are unchanged. A sealed manifest still names exactly one environment: `manifest_hash` is the full hash of the content keys, and `sealed.*` are the section digests a full bundle would carry, so a `.promigence` built from it can be cited, committed and handed back to the API. snapshot_idrequiredstring ### POST/v1/snapshots/{id}/verify Auth: API key Re-run the snapshot's own verify command in a fresh fork. Costs one sandbox's worth of seconds; it is a real run under the hood. #### Parameters idrequiredpath · string wait_msquery · integer Idempotency-Keyheader · string Makes a retried create safe: send the same key on every attempt of ONE create and it starts, and bills, once. Kept 24 hours per org. The same key with the same request (method, path and JSON body) answers with the first answer — same status, same ids — marked `Idempotent-Replayed: true`. The same key with a different request is refused with 409 `idempotency_key_reused`. A repeat that arrives while the first is still running waits for its answer, or gets 409 `idempotency_key_in_use` with `Retry-After`. Only an answer that started something is kept: a create refused before anything started leaves the key free. The SDKs send one for every create they make. #### Request body SnapshotVerify · application/json · optional spend_capnumber | null The most it may cost, in USD. timeout_msinteger | null Milliseconds the verification may run. Default 15 minutes. #### Answer 200 · SnapshotVerifyStarted · application/json aliasstring | null countrequiredinteger How many sandboxes were asked for. idempotent_replayrequiredboolean True when this is the stored answer to an `Idempotency-Key` that was seen before, and no second run was started. idempotent_replay_age_sinteger | null Present when `idempotent_replay` is true: how many seconds ago that first answer was given, so a client can say which earlier request this repeats. last_verified_atstring | null When the snapshot was last verified before this run, RFC 3339. launchedrequiredinteger How many were started. Fewer than `count` only with `allow_partial`, and the reason is in `warnings`. per_second_usdrequirednumber preemptiblerequiredboolean True when the run was posted at the preemptible rate: its sandboxes can be stopped early, and one stopped that way bills nothing. pricerequirednumber What one full run of it may cost, in USD. quoterequiredQuote A quote, per second: `max_cost = Σ sandbox_count × seconds_per_sandbox × per_second_usd`, where `per_second_usd = vcpus × vcpu_second_usd + mem_gib × gib_second_usd`. The most the run can cost if every sandbox runs its whole timeout; billing is for the seconds actually used. run_idrequiredstring sandboxesrequiredRunSandboxRef[] secondsrequiredinteger snapshotrequiredstring The snapshot, resolved. snapshot_argrequiredstring The snapshot as you named it — an id, an alias, or a path. snapshot_idstring | null The snapshot's id, as `GET /v1/runs/{id}` and the report give it: `""` for the built-in base. Never `null` from this API; typed nullable for older answers. spend_caprequirednumber The most this run may cost, in USD. staterequiredstring `"running"`. tierrequiredstring timeout_msrequiredinteger verifyrequiredstring The verification command, as it was recorded. warningsrequiredstring[] What was **not** started and why, said when it is decided rather than discovered in the report. workspacerequiredstring The directory it runs in. ### GET/v1/snapshots/builds Auth: API key List your org's builds. #### Parameters cursorquery · string limitquery · integer statequery · string #### Answer 200 · BuildList · application/json buildsrequiredBuildView[] next_cursorstring | null Pass as `?cursor=` for the next page; `null` on the last one. ### GET/v1/snapshots/builds/{id} Auth: API key One build. `?wait_ms=N` long-polls until the build reaches a terminal state, capped at 30 s server-side. #### Parameters idrequiredpath · string wait_msquery · integer #### Answer 200 · BuildView · application/json aliasstring | null The name the snapshot holds now, or the one asked for while the build runs. `null` once the snapshot is deleted: the name may belong to another snapshot by then. billable_secondsinteger | null Once the build has ended, the seconds it is billed for: the time it ran, whether it was stored, its own `setup` or `verify` failed, or it ran to its time limit; 0 when it failed on our side. Absent while it is queued or running, and for a build priced per build. build_idrequiredstring build_pricerequirednumber The most the build can cost, in USD, as said when it was started: `max_seconds` at `per_second_usd`. What it was billed is `cost_usd`. commitrequiredstring cost_usdnumber | null Once the build has ended, what it cost in USD; 0 when nothing was charged. Absent while it is queued or running. created_atrequiredstring RFC 3339. errorobject Why it failed. `null` while it is going and for a build that worked. finished_atstring | null RFC 3339. max_secondsinteger | null The longest the build may run, in seconds: it is billed for at most this long. Absent for a build priced per build. nextrequiredstring[] What to do next, ready to run. per_second_usdnumber | null What one second of the build costs, in USD: its tier's per-second rate. Absent for a build priced per build, before builds were billed per second. reporequiredstring setuprequiredstring[] snapshot_deletedboolean `true` when the snapshot this build made has since been deleted. Absent otherwise. snapshot_idstring | null The snapshot it produced; `null` until it is finished, and for a build that failed. sourcerequiredobject What it is being built from. The `kind` field says which of the three forms it is. staterequiredstring `queued` | `running` | `verified` | `built` | `rejected` | `failed`. `built` is a finished build that stored its snapshot with no verification command to run (an image built without `verify`): done and ready to start, like `verified`, but nothing was verified. tierrequiredstring tier_assignedrequiredstring verificationobject What the verification command did. `null` until there is a snapshot to report it for. verifiedrequiredboolean True when the build finished `verified` and its verification command passed. False while it is queued or running, when it failed or was rejected, and for an image built without `verify` (state `built`: stored, but nothing was verified). Nothing is stored if the command exits non-zero; the time the build ran is billed. verifyrequiredstring The verification command, as it was given. ### GET/v1/snapshots/builds/{id}/build-log Auth: API key The tail of the build log. `?tail=N` lines. #### Parameters idrequiredpath · string tailquery · integer #### Answer 200 · BuildLogView · application/json build_idrequiredstring logrequiredstring[] The last `tail` lines of the build's output, oldest first. Empty while the build is `queued`. staterequiredstring `queued` | `running` | `verified` | `built` | `rejected` | `failed` (`built`: stored with no verification command to run). ### GET/v1/templates Auth: none The templates: ready-made starting points to fork (languages, app starters, agent tools, benchmarks). Each names the snapshot to fork, its version, what it starts from, and a count of what it has installed. No key needed. #### Answer 200 · TemplateList · application/json templatesrequiredTemplateSummary[] ### GET/v1/templates/{name} Auth: none One template: its setup steps, everything it has installed (each package and its version, by package manager, and each tool's version), and every version with what changed. A newer version, or one that fixes a security problem, is listed here first. No key needed. #### Parameters namerequiredpath · string #### Answer 200 · TemplateDetail · application/json categoryrequiredstring dependenciesTemplateDependencies | null imagerequiredstring namerequiredstring published_atstring | null setuprequiredstring[] snapshot_idrequiredstring summaryrequiredstring tierrequiredstring titlerequiredstring verifyrequiredstring versionrequiredinteger versionsrequiredTemplateVersionView[] [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/reference/api/github [API reference](https://www.promigence.ai/docs/reference/api) # GitHub 7 routes of the published API contract, generated from it. ### GET/v1/integrations/github Auth: API key Your organization's GitHub connections, the ones still being finished, and the snapshots that follow a branch. `configured: false` when GitHub connections are not available. #### Answer 200 · GithubStatus · application/json app_slugstring | null configuredrequiredboolean False when GitHub connections are not available: nothing here works then, and `message` says so. connectionsrequiredGithubConnection[] messagestring | null pendingrequiredGithubPending[] tracksrequiredGithubTrack[] ### POST/v1/integrations/github/connect Auth: API key Start connecting a GitHub account: a link to install the platform's GitHub App on it, valid for 15 minutes. Open it in a browser, choose all repositories or selected ones, and GitHub sends you back; `GET /v1/integrations/github` then lists the connection. The App reads repository contents and metadata, nothing else. Body: `{}`. #### Answer 200 · GithubConnect · application/json app_slugrequiredstring The App's name on GitHub (`github.com/apps/`). expires_atrequiredstring When the link stops working (RFC 3339): 15 minutes. install_urlrequiredstring GitHub's install page for the App, carrying a signed state that names this organization. ### DELETE/v1/integrations/github/installations/{installation_id} Auth: API key Disconnect a GitHub account: nothing is built from it any more and the snapshots that followed its branches stop following them. The App stays installed on GitHub until you uninstall it there (`uninstall_url`). #### Parameters installation_idrequiredpath · string #### Answer 200 · GithubDisconnected · application/json accountrequiredstring disconnectedrequiredboolean Always true here. installation_idrequiredinteger messagerequiredstring tracks_removedrequiredinteger Snapshots that followed a branch of this account, and follow nothing now. uninstall_urlrequiredstring The App stays installed on the GitHub account until it is uninstalled there. ### GET/v1/integrations/github/repos Auth: API key The repositories your GitHub connections can read, one page at a time (`page`, `per_page` up to 100). `full_name` is what `POST /v1/snapshots` takes as `repo: "github:"`. #### Parameters pagequery · string per_pagequery · string #### Answer 200 · GithubRepos · application/json has_morerequiredboolean pagerequiredinteger 1-based. per_pagerequiredinteger reposrequiredGithubRepo[] totalrequiredinteger Repositories across every connection. ### POST/v1/integrations/github/requests Auth: API key Start connecting a GitHub account in the console, for yourself: a one-time ticket (5 minutes) and the console page that uses it (`connect_url`). Open the page in a browser signed in to the console as you, an owner of this organization; it takes you to GitHub, and `GET /v1/integrations/github/requests/{request_id}` then says how it ended. The page starts nothing for anyone else: opened while signed in to another account, the request ends as `wrong_user`. Owners only, like `connect`. `404` where the console cannot start it for this key (no console here, or a key with no person behind it): use `POST /v1/integrations/github/connect`. Body: `{}`. #### Answer 201 · ConnectTicket · application/json connect_urlrequiredstring The console page that starts the connection: it carries the ticket and nothing else. expires_atrequiredstring When the ticket stops working (RFC 3339): 5 minutes. request_idrequiredstring The connection request it starts (`icr_` and 32 hex digits). ticket_idrequiredstring `ict_` and 32 hex digits: used once, by you only, within 5 minutes. ### GET/v1/integrations/github/requests/{request_id} Auth: API key How a GitHub connection request you started ended: `pending`, then `connected`, `updated` (already connected; its repository access changed), `pending_provider_approval` (an owner of the account must approve it on GitHub first), `declined`, `other_org`, `needs_admin`, `not_installer`, `wrong_user`, `expired` or `failed`, with a sentence that says what happened and what to do next. Only the person who started it reads it; anyone else gets `404`. #### Parameters request_idrequiredpath · string #### Answer 200 · ConnectRequest · application/json accountstring | null The account on the code host, once it is known. created_atrequiredstring RFC 3339. finished_atstring | null RFC 3339: when it ended; absent while it is pending. messagerequiredstring One or two sentences for a person: what happened, then what to do next. providerrequiredstring `github` or `gitlab`. request_idrequiredstring `icr_` and 32 hex digits. staterequiredstring `pending` while it is not finished; then how it ended: `connected`, `updated` (already connected to this organization; its repository access changed), `already_connected`, `pending_provider_approval` (an owner of the account must approve it on the code host first), `declined`, `other_org` (connected to another organization), `needs_admin`, `not_installer`, `wrong_user` (the connection page was opened signed in to another account), `expired` or `failed`. ### DELETE/v1/integrations/github/tracks/{track_id} Auth: API key Stop a snapshot following its branch. The snapshot stays; pushes no longer build it. #### Parameters track_idrequiredpath · string #### Answer 200 · GithubUntracked · application/json aliasrequiredstring branchrequiredstring reporequiredstring track_idrequiredstring untrackedrequiredboolean Always true here. [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/reference/api/gitlab [API reference](https://www.promigence.ai/docs/reference/api) # GitLab 7 routes of the published API contract, generated from it. ### GET/v1/integrations/gitlab Auth: API key Your organization's GitLab connections (each with the URL and token of an optional project webhook that makes tracked branches build at once), the ones waiting for an owner to confirm, and the snapshots that follow a branch. `configured: false` on a deployment with no GitLab application. #### Parameters claimquery · string codequery · string errorquery · string statequery · string #### Answer 200 · GitlabStatus · application/json configuredrequiredboolean False on a deployment with no GitLab application: nothing here works there, and `message` says so. connectionsrequiredGitlabConnection[] gitlab_urlstring | null messagestring | null pendingrequiredGitlabPending[] tracksrequiredGitlabTrack[] ### POST/v1/integrations/gitlab/connect Auth: API key Start connecting a GitLab user: a link to authorize the platform's GitLab application, read-only (`read_api read_repository`), valid for 15 minutes. Open it in a browser and authorize; then an owner of your organization confirms it, signed in to Promigence in that same browser. `GET /v1/integrations/gitlab` then lists the connection. Body: `{}`. #### Parameters claimquery · string codequery · string errorquery · string statequery · string #### Answer 200 · GitlabConnect · application/json authorize_urlrequiredstring GitLab's authorization page, carrying a signed state that names this organization. expires_atrequiredstring When the link stops working (RFC 3339): 15 minutes. gitlab_urlrequiredstring The GitLab the connection is made on (`https://gitlab.com`). scopesrequiredstring[] What the application asks for: read-only access. ### DELETE/v1/integrations/gitlab/connections/{connection_id} Auth: API key Disconnect a GitLab user: the authorization is revoked on GitLab, nothing is built from it any more and the snapshots that followed branches through it stop following them. #### Parameters connection_idrequiredpath · string #### Answer 200 · GitlabDisconnected · application/json connection_idrequiredstring disconnectedrequiredboolean Always true here. messagerequiredstring revokedrequiredboolean Our token was revoked on GitLab. False when GitLab did not answer: then remove the application under your GitLab user settings > Applications. tracks_removedrequiredinteger Snapshots that followed a branch through this connection, and follow nothing now. usernamerequiredstring ### GET/v1/integrations/gitlab/repos Auth: API key The projects a GitLab connection can read (the oldest working one unless `connection_id` names another), one page at a time (`page`, `per_page` up to 100). `path` is what `POST /v1/snapshots` takes as `repo: "gitlab:"`. #### Parameters claimquery · string codequery · string connection_idquery · string errorquery · string pagequery · string per_pagequery · string statequery · string #### Answer 200 · GitlabRepos · application/json has_morerequiredboolean pagerequiredinteger 1-based. per_pagerequiredinteger reposrequiredGitlabRepo[] ### POST/v1/integrations/gitlab/requests Auth: API key Start connecting a GitLab user in the console, for yourself: a one-time ticket (5 minutes) and the console page that uses it (`connect_url`). Open the page in a browser signed in to the console as you, an owner of this organization; it takes you to GitLab, and `GET /v1/integrations/gitlab/requests/{request_id}` then says how it ended. The page starts nothing for anyone else: opened while signed in to another account, the request ends as `wrong_user`. Owners only, like `connect`. `404` where the console cannot start it for this key: use `POST /v1/integrations/gitlab/connect`. Body: `{}`. #### Answer 201 · ConnectTicket · application/json connect_urlrequiredstring The console page that starts the connection: it carries the ticket and nothing else. expires_atrequiredstring When the ticket stops working (RFC 3339): 5 minutes. request_idrequiredstring The connection request it starts (`icr_` and 32 hex digits). ticket_idrequiredstring `ict_` and 32 hex digits: used once, by you only, within 5 minutes. ### GET/v1/integrations/gitlab/requests/{request_id} Auth: API key How a GitLab connection request you started ended: `pending`, then `connected`, `already_connected`, `declined`, `wrong_user`, `expired` or `failed`, with a sentence that says what happened and what to do next. Only the person who started it reads it; anyone else gets `404`. #### Parameters request_idrequiredpath · string #### Answer 200 · ConnectRequest · application/json accountstring | null The account on the code host, once it is known. created_atrequiredstring RFC 3339. finished_atstring | null RFC 3339: when it ended; absent while it is pending. messagerequiredstring One or two sentences for a person: what happened, then what to do next. providerrequiredstring `github` or `gitlab`. request_idrequiredstring `icr_` and 32 hex digits. staterequiredstring `pending` while it is not finished; then how it ended: `connected`, `updated` (already connected to this organization; its repository access changed), `already_connected`, `pending_provider_approval` (an owner of the account must approve it on the code host first), `declined`, `other_org` (connected to another organization), `needs_admin`, `not_installer`, `wrong_user` (the connection page was opened signed in to another account), `expired` or `failed`. ### DELETE/v1/integrations/gitlab/tracks/{track_id} Auth: API key Stop a snapshot following its GitLab branch. The snapshot stays; new commits no longer build it. #### Parameters track_idrequiredpath · string #### Answer 200 · GitlabUntracked · application/json aliasrequiredstring branchrequiredstring reporequiredstring track_idrequiredstring untrackedrequiredboolean Always true here. [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/reference/api/runs [API reference](https://www.promigence.ai/docs/reference/api) # Runs 12 routes of the published API contract, generated from it. ### DELETE/v1/captures/{id} Auth: API key Destroy a preserved failure now. The bytes are deleted before the answer says so. #### Parameters idrequiredpath · string #### Answer 200 · CaptureDeleted · application/json bytesrequiredinteger Bytes freed. deletedrequiredboolean deleted_atrequiredstring RFC 3339. okrequiredboolean snapshot_idrequiredstring ### GET/v1/runs Auth: API key List your org's runs, newest first. Pages are `?limit=N` (1..=500, default 50) and `?cursor=`; echo back `next_cursor` and stop when it is `null`. #### Parameters cursorquery · string limitquery · integer #### Answer 200 · RunList · application/json next_cursorstring | null Pass as `?cursor=` for the next page; `null` on the last one. runsrequiredRunView[] ### POST/v1/runs Auth: API key Fork N sandboxes from one snapshot, optionally running a command in each. Refused with 409 `cap_exceeded` before anything starts if the quote exceeds `spend_cap`. `?wait_ms=N` parks until the sandboxes are ready; honours `Idempotency-Key`. #### Parameters wait_msquery · integer Idempotency-Keyheader · string Makes a retried create safe: send the same key on every attempt of ONE create and it starts, and bills, once. Kept 24 hours per org. The same key with the same request (method, path and JSON body) answers with the first answer — same status, same ids — marked `Idempotent-Replayed: true`. The same key with a different request is refused with 409 `idempotency_key_reused`. A repeat that arrives while the first is still running waits for its answer, or gets 409 `idempotency_key_in_use` with `Retry-After`. Only an answer that started something is kept: a create refused before anything started leaves the key free. The SDKs send one for every create they make. #### Request body RunCreate · application/json allow_partialboolean Start what fits now rather than refusing the whole run. captureCaptureMode | null countrequiredinteger How many sandboxes, 1–1000. execExecCreate | null A command each sandbox runs as it starts; the sandbox's outcome is its exit. gradeGradeSpec | null Score each sandbox's work after its command. grade_outputboolean | null Keep what the grader prints: the last 16 KiB of its output, stdout and stderr together, in each graded sandbox's `grade.output` in the run report. Never a held-out grader's. Absent: the setting of the snapshot's default grader when the run uses it, otherwise off. Needs a grader (`grade`, or the snapshot's default). labelsmap of string Your own key/value labels, returned on every answer about the run. networkNetworkRequest | null optimize_forOptimizeFor | null preemptibleboolean The lower batch rate: the run's sandboxes can be stopped early. secretsSecretUse[] Stored secrets every command in the run's sandboxes receives. snapshotrequiredstring A snapshot id, alias, `alias@commit7`, or `promigence/base`. spend_capnumber | null The most the run may cost, in USD. tierstring | null The sandbox size. Default: the snapshot's. timeout_msinteger | null Each sandbox's lifetime in milliseconds. Default 15 minutes, at most 30 days. verify_eachboolean Re-run the snapshot's verification in each sandbox before it takes work. #### Answer 200 · RunCreated · application/json countrequiredinteger How many sandboxes were asked for. idempotent_replayrequiredboolean True when this is the stored answer to an `Idempotency-Key` that was seen before, and no second run was started. idempotent_replay_age_sinteger | null Present when `idempotent_replay` is true: how many seconds ago that first answer was given, so a client can say which earlier request this repeats. launchedrequiredinteger How many were started. Fewer than `count` only with `allow_partial`, and the reason is in `warnings`. preemptiblerequiredboolean True when the run was posted at the preemptible rate: its sandboxes can be stopped early, and one stopped that way bills nothing. quoterequiredQuote A quote, per second: `max_cost = Σ sandbox_count × seconds_per_sandbox × per_second_usd`, where `per_second_usd = vcpus × vcpu_second_usd + mem_gib × gib_second_usd`. The most the run can cost if every sandbox runs its whole timeout; billing is for the seconds actually used. run_idrequiredstring sandboxesrequiredRunSandboxRef[] snapshotrequiredstring The snapshot, resolved. snapshot_argrequiredstring The snapshot as you named it — an id, an alias, or a path. snapshot_idstring | null The snapshot's id, as `GET /v1/runs/{id}` and the report give it: `""` for the built-in base. Never `null` from this API; typed nullable for older answers. spend_caprequirednumber The most this run may cost, in USD. staterequiredstring `"running"`. tierrequiredstring timeout_msrequiredinteger warningsrequiredstring[] What was **not** started and why, said when it is decided rather than discovered in the report. ### GET/v1/runs/{id} Auth: API key One run and its sandboxes. `?wait_ms=N` long-polls until the run is finished, or every sandbox has ended or outlived its command (`kill_on_exit: false`, `command_outcome` set). #### Parameters idrequiredpath · string wait_msquery · integer #### Answer 200 · RunView · application/json canceledrequiredboolean capacityCapacity | null Only on `GET /v1/runs/{id}`: whether the waiting sandboxes can start, so a client that is already long-polling this route does not need a second call to find out why it is waiting. capturerequiredstring What this run does with a sandbox's state when it ends: `on_failure` | `off` | `always`. Stated on every answer, so nobody has to remember what the default was. countrequiredinteger How many sandboxes were asked for. countsobject | null How many sandboxes are in each state, keyed by state or by outcome. Only on `GET /v1/runs/{id}`. execobject The command each sandbox was created with, if any. finished_atstring | null RFC 3339; `null` while the run is still going. gradeobject The grading block this run was submitted with, if any. grade_outputboolean The run keeps what its grader prints (`grade_output`). Absent when it does not. labelsrequiredmap of string networkrequiredobject The policy as it was submitted: `"egress"` / `"none"` stay strings, an allowlist comes back as the object you sent, normalised. quoterequiredRunQuote The price a run was quoted at, frozen when it started. The same numbers `POST /v1/runs/quote` answers with, without the per-line breakdown: a run that exists has one line. run_idrequiredstring sandboxesRunSandboxRef[] | null Only on `GET /v1/runs/{id}`: one compact row per sandbox. The full records, with their timings, are `GET /v1/runs/{id}/sandboxes`. snapshotrequiredstring The snapshot this run forks from, as it was asked for. snapshot_idrequiredstring The same value under the name the validity report uses. Both are sent so a client can read either. spend_caprequirednumber The most this run may cost, in USD. started_atrequiredstring RFC 3339. staterequiredstring `queued` | `running` | `completed` | `aborted`. tierrequiredstring timeout_msrequiredinteger Each sandbox's lifetime, in milliseconds. verify_eachrequiredboolean Whether each sandbox re-ran the snapshot's own verification before taking work. ### DELETE/v1/runs/{id} Auth: API key Cancel the queue and kill every live sandbox of the run. #### Parameters idrequiredpath · string #### Answer 200 · RunKilled · application/json killedrequiredinteger How many live sandboxes were killed. Each is billed for the seconds it used. okrequiredboolean run_idrequiredstring ### POST/v1/runs/{id}/cancel Auth: API key Stop what is still queued. Live sandboxes keep running — use `DELETE /v1/runs/:id` for those. #### Parameters idrequiredpath · string #### Answer 200 · RunCanceled · application/json canceledrequiredinteger How many queued sandboxes were dropped. They were never started, so they are not billed. okrequiredboolean run_idrequiredstring ### GET/v1/runs/{id}/captures Auth: API key What is preserved of this run's failures, and when each goes. #### Parameters idrequiredpath · string #### Answer 200 · CaptureList · application/json capturesrequiredCaptureView[] okrequiredboolean run_idrequiredstring ### POST/v1/runs/{id}/open Auth: API key Reopen a preserved failure as a new, live sandbox — the state the sandbox was in when it broke, not a re-run from the start. It has its own id and its own billing clock, out of what is left of the run's cap. #### Parameters idrequiredpath · string Idempotency-Keyheader · string Makes a retried create safe: send the same key on every attempt of ONE create and it starts, and bills, once. Kept 24 hours per org. The same key with the same request (method, path and JSON body) answers with the first answer — same status, same ids — marked `Idempotent-Replayed: true`. The same key with a different request is refused with 409 `idempotency_key_reused`. A repeat that arrives while the first is still running waits for its answer, or gets 409 `idempotency_key_in_use` with `Retry-After`. Only an answer that started something is kept: a create refused before anything started leaves the key free. The SDKs send one for every create they make. #### Request body RunOpen · application/json · optional sandbox_idstring | null Which captured sandbox; required when the run has more than one capture. spend_capnumber | null timeout_msinteger | null #### Answer 200 · RunOpened · application/json coderequiredstring The original's failure code. committed_secondsrequiredinteger Billable seconds committed to the new sandbox. detailrequiredstring expires_atrequiredstring When the preserved state expires, RFC 3339. failed_atrequiredstring When the original failed, RFC 3339. max_costrequirednumber The most the new sandbox may cost, in USD. okrequiredboolean opened_fromrequiredstring The failed sandbox this one was opened from. outcomerequiredstring The original's outcome. ready_msrequirednumber Milliseconds until it was ready. run_idrequiredstring sandbox_idrequiredstring The new sandbox. snapshot_idrequiredstring The preserved state it was opened from. staterequiredstring `"ready"`. timeout_msrequiredinteger ### POST/v1/runs/{id}/replay Auth: API key Re-fork the sandboxes whose outcome was an environment failure. Each replay is a new sandbox row with `replay_of` set, billed like any other sandbox; what the failed original is billed is in the run's report (`cost`), and a failure our side shows was ours is credited back. #### Parameters idrequiredpath · string Idempotency-Keyheader · string Makes a retried create safe: send the same key on every attempt of ONE create and it starts, and bills, once. Kept 24 hours per org. The same key with the same request (method, path and JSON body) answers with the first answer — same status, same ids — marked `Idempotent-Replayed: true`. The same key with a different request is refused with 409 `idempotency_key_reused`. A repeat that arrives while the first is still running waits for its answer, or gets 409 `idempotency_key_in_use` with `Retry-After`. Only an answer that started something is kept: a create refused before anything started leaves the key free. The SDKs send one for every create they make. #### Request body RunReplay · application/json · optional envmap of string Values for the environment variables the run's command was started with. A run keeps their names, never their values, so a replay of a command that had any needs every one. sandbox_idsstring[] | null The sandboxes to replay; omitted, every one that may be replayed. #### Answer 200 · RunReplayed · application/json detailstring | null Present only when there was nothing to replay, saying so. okrequiredboolean replayedrequiredinteger run_idrequiredstring sandboxesrequiredReplayRef[] ### GET/v1/runs/{id}/report Auth: API key The validity report: every sandbox, its outcome, and whether the failure was the environment's or the task's. Run through your project's secret redactor before it is serialised. #### Parameters idrequiredpath · string #### Answer 200 · Run · application/json aliasstring | null costrequiredCost finished_atstring | null forkrequiredForkStats gradeGradeStats | null The two pass rates and the **gap** between them. Absent when the run was not graded. labelsmap of string quoterequiredQuote A quote, per second: `max_cost = Σ sandbox_count × seconds_per_sandbox × per_second_usd`, where `per_second_usd = vcpus × vcpu_second_usd + mem_gib × gib_second_usd`. The most the run can cost if every sandbox runs its whole timeout; billing is for the seconds actually used. requestedrequiredRequested run_idrequiredstring sandboxesrequiredSandbox[] schemarequiredstring snapshot_idrequiredstring spend_caprequirednumber started_atrequiredstring staterequiredRunState totalsrequiredTotals ### GET/v1/runs/{id}/sandboxes Auth: API key Only the sandboxes of a run. `?wait_ms=N` long-polls until nothing is queued any more. #### Parameters idrequiredpath · string wait_msquery · integer #### Answer 200 · RunSandboxes · application/json capacityrequiredCapacity Whether this run's sandboxes can start, in the words a waiting caller needs. Three states: `ok` — nothing is waiting; `arriving` — sandboxes are waiting and should start within `eta_s`; `blocked` — they cannot start now, and the reason is named. A block is a refusal, and it arrives at once rather than after a countdown. run_idrequiredstring sandboxesrequiredSandboxView[] ### POST/v1/runs/quote Auth: API key Price a run without starting one. No side effects, nothing reserved. Matched ahead of `/v1/runs/:id`, so a run can never be named `quote`. #### Request body RunQuoteRequest · application/json countrequiredinteger 1–1000. preemptibleboolean snapshotrequiredstring spend_capnumber | null tierstring | null timeout_msinteger | null #### Answer 200 · RunQuoteView · application/json billingrequiredstring `per_second`. breakdownrequiredQuoteLine[] countrequiredinteger credits_availablenumber | null Trial credits available, in USD; `null` when the organisation is not on a trial. egressQuoteEgress | null Data out, priced beside compute: the rate, what the month includes and what is left of it. `max_cost` does not cover it. `null` when the organisation's plan could not be read. gib_second_usdrequirednumber granularity_secondsrequiredinteger max_costrequirednumber The most the run can cost if every sandbox runs its whole timeout, in USD. mem_gibrequiredinteger min_billable_secondsrequiredinteger per_hour_usdrequirednumber per_second_usdrequirednumber preemptiblerequiredboolean quoterequiredQuote The same quote, whole — what `POST /v1/runs` and the report echo back. seconds_per_sandboxrequiredinteger `ceil(timeout_ms / 1000)`: what one full sandbox may bill. snapshotrequiredstring The snapshot as you named it. snapshot_idstring | null `null` for a snapshot this service holds no record of. spend_caprequirednumber The cap the run would be held to: the one you passed, or the organisation's default. tierrequiredstring timeout_msrequiredinteger vcpu_second_usdrequirednumber vcpusrequiredinteger warningsrequiredstring[] Anything that would make `POST /v1/runs` refuse this, said now. [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/reference/api/sandboxes [API reference](https://www.promigence.ai/docs/reference/api) # Sandboxes 10 routes of the published API contract, generated from it. ### GET/v1/sandboxes Auth: API key List your org's sandboxes, newest first. `?labels=k=v,k2=v2` returns only those whose run carries every label given, and `?state=running,ready` narrows by state: `queued` is every sandbox still waiting to start, `awaiting_capacity` only those a run answer reports as waiting for capacity. Both filters run on the server, so they find a match older than one page — which is how two copies of your service agree on one sandbox instead of each starting its own. Pages are `?limit=N` (1..=500, default 50) and `?cursor=`; echo back `next_cursor` to get the next page, and stop when it is `null`. A short page is not the end: a filter can empty a page that still has more behind it. #### Parameters cursorquery · string labelsquery · string limitquery · integer statequery · string #### Answer 200 · SandboxList · application/json labelsrequiredmap of string The label filter this list was produced with; empty when none was given. limitrequiredinteger The page size that was applied. next_cursorstring | null Pass back as `?cursor=` for the next page; `null` on the last page. A short page is not the end: a filter can empty a page that still has more behind it. sandboxesrequiredSandboxView[] staterequiredstring[] The state filter this list was produced with; empty when none was given. `queued` keeps every waiting sandbox; `awaiting_capacity` only those waiting for capacity being added. ### GET/v1/sandboxes/{id} Auth: API key One sandbox, with its execs. `auto_pause_s` and `auto_pause_mode` report the idle rule it is under — the values `PATCH` sets; `auto_pause_s` is 0 when it never pauses itself on idle. `optimize_for` is what the sandbox asked for; `optimize_for_applied` is what its latest start or resume actually got (null before the first). They can differ — the next resume asks again. #### Parameters idrequiredpath · string #### Answer 200 · SandboxView · application/json attemptrequiredinteger 1 for the first try, 2 for the first retry, and so on. auto_pause_moderequiredstring What idle means for the rule: `requests` | `activity`. auto_pause_srequiredinteger The idle rule it is under: park after this many idle seconds, 0 for never. billable_secondsinteger | null Once it has ended, the seconds it is billed for (the run report's `billable_seconds`). Present on `GET /v1/sandboxes/{id}` for an ended sandbox; absent from list rows. cost_usdnumber | null What it has cost in USD at its run's rates: once it has ended, the run report's `cost`; while it is live, the seconds billed so far (running time only). Present on `GET /v1/sandboxes/{id}` once it has started; absent from list rows. created_atrequiredstring When the sandbox was created, RFC 3339: when its run was started, or when the retry or replay that made it was asked for. e2e_msnumber | null Milliseconds from the start request, after any time queued, to the sandbox being handed over: it does not include `queued_ms`. Add `queued_ms` for the whole wait. egressrequiredEgressCounters Data out, and whether it was cut for the organisation's monthly cap. elapsed_msinteger | null Milliseconds of running time since hand-over, time spent paused excluded: what `timeout_ms` is measured against, so `timeout_ms - elapsed_ms` is the time it has left. `null` before hand-over and once it has ended. env_verifiedrequiredboolean Whether this sandbox's environment passed its checks. eta_sinteger | null Seconds until this sandbox is expected to start, with `queued_reason: capacity_arriving`. `null` with the other reasons, and once the sandbox has waited longer than the estimate it was first given; `queued_message` then says it is taking longer than expected rather than repeating a number. execsExecView[] | null The commands run in this sandbox. Present on `GET /v1/sandboxes/{id}`; absent from the rows of a list, which would otherwise carry every byte of every command's output. failureobject What went wrong, rendered against this sandbox's own evidence. `null` on success. labelsrequiredmap of string Inherited from the run. A caller that looked a sandbox up by label needs to see the labels it got back, and one that did not needs a way to learn what a sandbox is tagged with. one_timeboolean | null True when this is a one-time wait: once the waiting sandboxes can start, the rest of the run starts at once too. False otherwise. optimize_forrequiredOptimizeFor What the sandbox asked for. optimize_for_appliedOptimizeFor | null What its latest start or resume actually got; `null` before the first. outcomestring | null Why it ended; `null` while it is still alive. pause_expires_atstring | null While it is paused: when it will be deleted, with its files and state, unless it is resumed before then (RFC 3339). A paused sandbox is kept for 30 days, and resuming it starts the 30 days again. Absent while it is not paused, and for a paused sandbox that is not due to be deleted. pause_reasonstring | null Why it is paused, when a limit paused it rather than a request: `spend_cap` (its run reached its spend cap) or `credits_exhausted` (the organization's credits ran out). Its files and state are kept and paused time is not billed; it resumes once the cap is raised or credits are added. Absent otherwise. queued_messagestring | null The same, in words, ready to show a person. queued_msnumber | null Milliseconds spent waiting for capacity. queued_reasonQueuedReason | null ready_msnumber | null Milliseconds until the sandbox was ready to take work. replay_ofstring | null The sandbox this one is a replay of. retried_bystring | null The retry that replaced this sandbox, if it was retried. retry_ofstring | null The sandbox this one is a retry of. run_idrequiredstring The run this sandbox belongs to. sandbox_idrequiredstring snapshot_idrequiredstring The snapshot it was started from, as its run names it (`GET /v1/runs/{id}`): the snapshot's id, or `promigence/base` for the built-in base. staterequiredstring `queued` | `ready` | `running` | `paused` | `ended`. t_endstring | null When it ended, RFC 3339. t_handoffstring | null When the sandbox was handed over, RFC 3339. timeout_msinteger | null The lifetime this sandbox is bound to, in milliseconds of running time: time spent paused does not count. A `PATCH` with a larger `timeout_ms` extends it. verify_each_msnumber | null Milliseconds the per-sandbox verification took, when `verify_each` was asked for. warningsrequiredstring[] ### PATCH/v1/sandboxes/{id} Auth: API key Extend a live sandbox's total lifetime, and set when it parks itself. `timeout_ms` sets the total, not an offset from now; 409 `cap_exceeded` if the extra seconds do not fit the run's cap. `auto_pause_s` parks the sandbox once it has been idle that long — 0 turns it off, the minimum is 2, and a sandbox with a command, a background command, a terminal or an SSH session still open is never idle, so a long build or a dev server is safe. `auto_pause_mode` says what idle means: `requests` (the default) counts calls to the sandbox; `activity` also waits until, for the whole window, nothing inside has used CPU or sent or received a byte, and no network connection to the outside is open — for an agent that runs inside the sandbox on its own. Start such an agent in the background of a command that returns: it keeps running when the sandbox wakes. An agent still running as an open command keeps the sandbox awake in either mode, because a pause would end it. A sandbox parked by this rule wakes by itself on its next command or file call, and parked time is not billed. Any of the fields may be sent on its own. #### Parameters idrequiredpath · string #### Request body SandboxPatch · application/json · optional auto_pause_modeAutoPauseMode | null auto_pause_sinteger | null Pause after this many idle seconds; 0 turns the rule off. timeout_msinteger | null The new lifetime in milliseconds, counted from now. #### Answer 200 · SandboxPatched · application/json ### DELETE/v1/sandboxes/{id} Auth: API key Kill it now. The answer's `outcome` says how it ended: `aborted_by_client` for a sandbox that had started, billed for the seconds it used; `not_started` for one still queued, which is not billed; or, when its command had already returned, that command's own outcome. A sandbox that had already ended answers with the outcome it ended with and `already_ended: true`. #### Parameters idrequiredpath · string #### Answer 200 · SandboxKilled · application/json already_endedrequiredboolean True when the sandbox had already ended and this call changed nothing. okrequiredboolean outcomestring | null sandbox_idrequiredstring staterequiredstring `"ended"`. ### GET/v1/sandboxes/{id}/network Auth: API key Read the network policy a live sandbox is running under. #### Parameters idrequiredpath · string #### Answer 200 · SandboxNetwork · application/json networkrequiredobject `"egress"`, `"none"`, or `{"allow": [...]}` — the policy in force: as it was written, or `"none"` once the sandbox's egress has been cut. refused_connectionsobject Connections refused, counted, including those to a bare address (which have no name to list and whose addresses are not recorded). Only for a sandbox that is still running. refused_hostsrequiredobject The hosts this sandbox was refused, by name. Current while it is running, and as recorded once it is not. A connection to a bare address has no name: it is counted in `refused_connections`, not listed here. refused_lookupsobject Name lookups refused. Only for a sandbox that is still running. sandbox_idrequiredstring staterequiredstring via_secretViaSecret[] The hosts this sandbox may reach for its host-bound secrets (`secrets set --host`), each secret by name with its hosts, whatever `network` says. Absent when it has none. ### POST/v1/sandboxes/{id}/network Auth: API key Cut a live sandbox's egress. Use it to fetch dependencies first and close the network before the agent runs. One direction only: there is no call that opens egress again, so a sandbox can never widen its own access. #### Parameters idrequiredpath · string #### Request body SandboxNetworkSet · application/json networkrequiredstring `none`, the only value. #### Answer 200 · SandboxNetworkCut · application/json appliedrequiredboolean False if the sandbox was already running with no egress. networkrequiredNetworkMode A network policy named by its mode alone. sandbox_idrequiredstring staterequiredstring ### POST/v1/sandboxes/{id}/pause Auth: API key Park the sandbox: it does not count against your concurrency limit, and paused time is not billed. Background commands started with `background: true` are ended by the pause, and the answer says how many (`background_execs_killed`, only when there were any); start them again after resume. A sandbox that was given the value of a secret pauses as usual, and the answer carries a `secrets_in_saved_state` warning. #### Parameters idrequiredpath · string #### Answer 200 · SandboxPaused · application/json already_pausedboolean | null Present, and true, only when the sandbox was already paused and this call changed nothing. The fields below it are then absent. background_execs_killedinteger | null Background commands the pause ended, when there were any. A pause does not keep a running background command: start it again after resume. bytesParkedBytes | null What the parked sandbox occupies on disk while it is not running. durableboolean | null True when the parked state is kept safe from a failure on our side. `false` is not an error. okrequiredboolean paused_idstring | null An opaque name for this pause. Resume by the sandbox id; this one is for your records. recordedboolean | null False if the sandbox was parked but the change could not be written down, which is worth retrying. sandbox_idrequiredstring staterequiredstring `"paused"`. took_msinteger | null Milliseconds the pause took, from the request to the answer. warningsstring[] | null Things to know about what was parked, one `code: sentence` per line; only when there is one. Today the only one is `secrets_in_saved_state`. ### POST/v1/sandboxes/{id}/probe Auth: API key Re-check the sandbox's files against what the verified snapshot recorded. `first_bad_path` is the first path that differs. #### Parameters idrequiredpath · string #### Request body SandboxProbeRequest · application/json · optional pathsstring[] Paths to check; omitted, the whole workspace. #### Answer 200 · SandboxProbe · application/json checkedrequiredobject What was checked: the list you asked for, or the string `"verified_paths"` for the snapshot's own recorded set. first_bad_pathstring | null The first path that differs, and the only part of a failed check anyone can act on. msrequirednumber How long the check took, in milliseconds. okrequiredboolean True when every path checked still matches what was verified. sandbox_idrequiredstring ### POST/v1/sandboxes/{id}/resume Auth: API key Bring a paused sandbox back where it was, and restart the billing clock. #### Parameters idrequiredpath · string #### Request body SandboxResume · application/json · optional optimize_forOptimizeFor | null Omitted: the sandbox's own setting. spend_capnumber | null For a sandbox paused at its run's spend cap (`pause_reason: spend_cap`): the run's new cap in US dollars, above the one it reached. The sandbox goes on with what the new cap leaves, up to its own timeout. #### Answer 200 · SandboxResumed · application/json notestring | null What `restarted` means for this sandbox, in one sentence. Absent for a normal resume. okrequiredboolean paused_idrequiredstring The pause that was restored: the `paused_id` its pause answered with. recordedrequiredboolean False if the sandbox came back but the change could not be written down. restartedboolean True when the sandbox came back from its saved files only: its files are as they were when it paused, but the programs that were running then were not kept and start fresh. Absent (false) for a normal resume, where everything comes back as it was. sandbox_idrequiredstring staterequiredstring `"ready"`. took_msrequiredinteger Milliseconds the resume took, from the request to the answer. ### POST/v1/sandboxes/{id}/snapshot Auth: API key Snapshot a running sandbox without stopping it, and get back an ordinary snapshot id you can fork. Background processes are ended first and the count is in the reply. The new snapshot inherits the tier and source of the snapshot this sandbox came from. It is not marked verified: the sandbox has run your code since, so verification has to be earned again rather than inherited. A sandbox that was given the value of a secret is refused with `secrets_in_snapshot` (409), because the snapshot, and every sandbox started from it, could contain that value; `force: true` takes it anyway and the answer carries a `secrets_in_saved_state` warning. An `alias` another snapshot already has is refused unless `move_alias: true` moves it here (the other snapshot stays, unnamed). #### Parameters idrequiredpath · string #### Request body SandboxSnapshotCreate · application/json · optional aliasstring | null A name for the new snapshot, unique in the project. forceboolean Take it even though the sandbox was given a secret's value. move_aliasboolean If another snapshot has `alias`, move the name to the new one (the other stays, unnamed). Without it such an alias is refused. #### Answer 200 · SandboxSnapshot · application/json aliasstring | null background_execs_killedrequiredinteger Background processes ended to take the snapshot. Reported rather than silent: a live snapshot must not quietly cost a customer their dev server. bytesrequiredSnapshotBytes What the image occupies on disk. okrequiredboolean sandbox_idrequiredstring The sandbox that was photographed. Still yours, still running. snapshot_idrequiredstring An ordinary snapshot id, forkable by every path that forks anything else. There is deliberately no second kind of snapshot: a parallel identifier with its own rules is how two code paths drift apart. still_runningrequiredboolean Always `true` on a 200. See the type's note. tierrequiredstring took_msrequiredinteger Milliseconds the snapshot took, from the request to the answer. warningsstring[] Things the caller should know about what was taken, one `code: sentence` per line. Absent when there are none. Today the only one is `secrets_in_saved_state`: the sandbox had been given the value of a secret and the snapshot was taken with `force`, so the snapshot, and every sandbox started from it, can contain that value. [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/reference/api/execs [API reference](https://www.promigence.ai/docs/reference/api) # Execs 7 routes of the published API contract, generated from it. ### GET/v1/execs/{id} Auth: API key One exec by id alone, without knowing its sandbox or run. An exec belonging to another org is a 404, never a 403. A background command's id (`x_…`) answers as `GET /v1/sandboxes/:id/execs/:exec_id` does, with the same `?stream`, `?offset`, `?len` and `?wait_ms`; after a restart of the service that id is found only through its sandbox. #### Parameters idrequiredpath · string lenquery · integer offsetquery · integer streamquery · string untilquery · string wait_msquery · integer #### Answer 200 · ExecView · application/json argvrequiredstring[] The command, as it was run. cpu_msrequirednumber cwdstring | null The working directory it ran in. env_keysrequiredstring[] The names of the environment variables it was given. Never the values. exec_idrequiredstring exit_codeinteger | null `null` while it is still running, or if a signal killed it. max_rss_kibrequiredinteger Peak resident memory, in kibibytes. run_idrequiredstring sandbox_idrequiredstring signalinteger | null The signal that killed it, if one did. started_atrequiredstring When it started, RFC 3339. stderrrequiredstring stdoutrequiredstring terminalrequiredboolean True when this command owned the sandbox: the sandbox ends when the command does. truncatedrequiredboolean True when the output was cut: at the request's byte limit, or, in a sandbox's `execs`, to the last 64 KiB of each stream. `GET /v1/execs/{id}` returns the whole recorded output. wall_msrequirednumber ### GET/v1/sandboxes/{id}/execs Auth: API key List this sandbox's background execs. #### Parameters idrequiredpath · string #### Answer 200 · BackgroundExecList · application/json execsrequiredBackgroundExec[] sandbox_idrequiredstring ### POST/v1/sandboxes/{id}/execs Auth: API key Run a command. Buffered by default; `Accept: text/event-stream` streams it; `background: true` returns 202 with a handle instead of waiting. A sandbox parked by its `auto_pause_s` rule is woken first; one paused with `POST …/pause` is not, and answers that it is paused. `max_output_bytes` (default 64 KiB) is per stream and at most 32 MiB; output past it is cut and the reply says `truncated: true`. #### Parameters idrequiredpath · string Idempotency-Keyheader · string Optional. Makes a retried command safe: send the same key on every attempt of ONE command and it runs once. Kept 24 hours per org. The same key with the same request answers with the first answer (same `exec_id`), marked `Idempotent-Replayed: true`; the same key with a different request is refused with 409 `idempotency_key_reused`. Honoured on a buffered or background command; a streamed one (`Accept: text/event-stream`) refuses a key. At most 1 MiB of output is kept for a replay: a replay of a longer answer is cut and says so with `replay_truncated: true`. Nothing is kept unless you send a key; the SDKs send one only when you pass it. #### Request body ExecCreate · application/json · optional argvstring[] | null The program and its arguments, run without a shell. backgroundboolean Answer at once (202) with a handle to poll, instead of waiting for the command. cwdstring | null The working directory. Defaults to the snapshot's workspace. encodingstring | null `text` (the default) or `base64`: the answer's output as `stdout_b64` / `stderr_b64`, the exact bytes, for output that is not text (an archive, an image). The buffered answer only. envmap of string Extra environment variables. followboolean With `background`: the command is read as it runs, by a caller that may lose its connection and come back. The newest `max_output_bytes` of each stream are kept (8 MiB by default; older bytes are dropped, and a read that asks for them says how many in `skipped`), and the handle is freed 10 minutes after the command ends, read or not. The command never stops because a caller went away. kill_on_exitboolean | null End the sandbox when the command exits (default: the value of `terminal`). max_output_bytesinteger | null Output kept per stream, in bytes (default 64 KiB, 1 MiB for a background exec; max 32 MiB). secretsSecretUse[] Stored secrets the command receives as environment variables. shstring | null A line for `sh -c`. stdinboolean Keep the command's stdin open for `POST …/execs/{exec_id}/stdin` (background execs). terminalboolean The sandbox ends when this command exits. timeout_msinteger | null Milliseconds before the command is ended. A positive integer; omitted, 15 minutes. userstring | null The user to run as. #### Answer 200 · ExecResult · application/json cpu_msnumber | null exec_idrequiredstring exit_codeinteger | null `null` if a signal killed the command. oom_killedboolean Present (true) when the command was killed for running out of memory. reasonstring | null Why the command ended without an exit code: `timeout`, `out_of_memory` or `signal`. Absent when it exited on its own. sandbox_idrequiredstring signalinteger | null The signal that killed it, if one did. stderrstring | null stderr_b64string | null With `encoding: "base64"`: the exact bytes of standard error, base64. stdoutstring | null stdout_b64string | null With `encoding: "base64"`: the exact bytes of standard output, base64 (`stdout` is then empty). Bytes that are not UTF-8 survive here; as text they become U+FFFD. timed_outboolean Present (true) when the command was killed at its own `timeout_ms`. truncatedrequiredboolean True when the output was cut at the request's byte limit. wall_msnumber | null ### GET/v1/sandboxes/{id}/execs/{exec_id} Auth: API key Read a background exec. `?stream=stdout|stderr&offset=&len=` takes a byte range; `?wait_ms=N` parks until it exits. #### Parameters idrequiredpath · string exec_idrequiredpath · string lenquery · integer offsetquery · integer streamquery · string untilquery · string wait_msquery · integer #### Answer 200 · BackgroundExec · application/json argvstring | null The command, as one line. backgroundrequiredboolean Always true: this is the handle form of a command. datastring | null The bytes, base64. eofboolean | null True when `data` reaches the end of what is held so far. errorBackgroundExecError | null Why the command could not run; only when `state` is `failed`. exec_idrequiredstring exitBackgroundExecExit | null How the command ended; only once `state` is `exited`. followboolean | null Started with `follow`: the newest output is kept, and the handle is freed 10 minutes after the command ends. idle_hold_sinteger | null Present when the sandbox pauses itself when idle: after this command ends, the idle rule waits up to this many seconds for its result to be read before it pauses the sandbox (a pause drops the handle and its output). Reading its output once it has finished releases the hold, and so does deleting the handle (`DELETE /v1/sandboxes/{id}/execs/{exec_id}`, CLI `exec kill EXEC --forget`). idle_hold_untilstring | null When this finished command stops holding the idle rule off (RFC 3339), while it still does: absent for a running command, once its output has been read, and once the time has passed. leninteger | null Bytes in `data`. offsetinteger | null sandbox_idrequiredstring skippedinteger | null A `follow` command only: bytes between the `offset` asked for and the first byte still held, dropped to keep the newest output; `data` then starts at `offset + skipped`. started_unix_nsinteger | null Unix nanoseconds. staterequiredstring `running` | `exited` | `failed`. stderr_bytesinteger | null stderr_totalinteger | null stdin_openboolean | null True while the command's standard input can still be written to. stdout_bytesinteger | null Bytes of standard output held and readable by range. stdout_totalinteger | null Bytes of standard output the command has written in total. streaminteger | null Which stream `data` is from: 1 for stdout, 2 for stderr. truncatedboolean | null True when more was written than is held. waited_msinteger | null How long a `?wait_ms=` read waited, in milliseconds. ### DELETE/v1/sandboxes/{id}/execs/{exec_id} Auth: API key SIGKILL the background exec and drop its handle and buffered output. #### Parameters idrequiredpath · string exec_idrequiredpath · string #### Answer 200 · ExecForgotten · application/json exec_idrequiredstring forgottenrequiredboolean okrequiredboolean sandbox_idrequiredstring ### POST/v1/sandboxes/{id}/execs/{exec_id}/signal Auth: API key Signal a background exec. #### Parameters idrequiredpath · string exec_idrequiredpath · string #### Request body ExecSignal · application/json · optional signalNumberOrName | null A signal number 1–64, or a name such as `SIGTERM` or `TERM`. Default 15 (SIGTERM). #### Answer 200 · ExecSignalled · application/json already_endedboolean | null Present, and true, only when the command had already finished. deliveredrequiredboolean False when the command had already finished, which is not a failure: the process is gone, which is what a kill wanted. exec_idrequiredstring okrequiredboolean sandbox_idrequiredstring signalrequiredinteger The signal that was sent, as a number. ### POST/v1/sandboxes/{id}/execs/{exec_id}/stdin Auth: API key Write to a running command's standard input, and close it. `data` is base64 — stdin is bytes, and a JSON string cannot carry all of them. Send `data` and `eof` together for the common "write this and close". The command must have been started with `stdin: true`; a process already running on `/dev/null` cannot be handed an input later, so writing to one is an error rather than a write that goes nowhere. #### Parameters idrequiredpath · string exec_idrequiredpath · string #### Request body ExecStdin · application/json · optional datastring | null Bytes to write, base64. eofboolean Close stdin after this write. #### Answer 200 · StdinAck · application/json eofrequiredboolean This call closed the input side. exec_idrequiredstring okrequiredboolean sandbox_idrequiredstring writtenrequiredinteger Bytes handed to the child's stdin by this call. [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/reference/api/files [API reference](https://www.promigence.ai/docs/reference/api) # Files 12 routes of the published API contract, generated from it. ### GET/v1/sandboxes/{id}/files Auth: API key Stream a file out. `?path=`. #### Parameters idrequiredpath · string pathquery · string #### Answer 200 · string · application/octet-stream ### PUT/v1/sandboxes/{id}/files Auth: API key Write a file in. `?path=`; the body is the bytes. `?mode=` (octal, e.g. `755`) sets the file's permission bits; without it a file that already exists keeps its mode, as a shell `>` or an editor's save does, and a new file is `644`. A directory on the path that does not exist is created first (`mkdir -p`, mode 755). Large files are chunked by the SDKs at 16 MiB. `&offset=N` writes at byte N instead of replacing the file, so an interrupted upload resumes: its error's evidence says how many bytes were `written`. A body over the request limit is refused 413. #### Parameters idrequiredpath · string modequery · string offsetquery · integer pathquery · string #### Request body string · application/octet-stream #### Answer 200 · FileWritten · application/json bytesrequiredinteger Bytes written by this request. chunksrequiredinteger How many pieces the write was sent in. moderequiredstring The file's permission bits after the write, octal (`644`). Without `?mode=` a file that already existed keeps its own, and a new file is `644`. offsetrequiredinteger Where this request's bytes start in the file (`?offset=`, else 0). okrequiredboolean pathrequiredstring sandbox_idrequiredstring statFileStat | null The file as the sandbox describes it after the write; `null` when it could not say. ### DELETE/v1/sandboxes/{id}/files Auth: API key Delete a path. Idempotent: a missing path answers `existed: false`, not 404. `?recursive=1` for a tree. #### Parameters idrequiredpath · string pathquery · string recursivequery · string #### Answer 200 · FileDeleted · application/json deletedrequiredboolean existedrequiredboolean False when there was nothing at that path to begin with. okrequiredboolean pathrequiredstring sandbox_idrequiredstring ### POST/v1/sandboxes/{id}/files/archive Auth: API key Pack a directory into a tar **inside the sandbox** and answer with where it landed and how big it is. Download it with the ordinary chunked file read. Splitting it this way is what lets a directory of any size come out: the transfer is the byte path you already have, not a second one with its own limit. `exclude` takes name globs like `.git`. #### Parameters idrequiredpath · string #### Request body FileArchive · application/json excludestring[] Name globs left out, e.g. `[".git"]`. outstring | null Where the archive is written (absolute). Default: beside the source. pathrequiredstring #### Answer 200 · ArchiveInfo · application/json archive_pathrequiredstring Where the tar landed inside the sandbox. sandbox_idrequiredstring served_bystring | null sizerequiredinteger sourcerequiredstring The directory that was packed. ### POST/v1/sandboxes/{id}/files/chmod Auth: API key Change permissions and ownership. `mode` is a number or an octal string like `"755"`. Ownership is changed on the symlink itself, never on what it points at. #### Parameters idrequiredpath · string #### Request body FileChmod · application/json gidinteger | null modeFileMode | null pathrequiredstring recursiveboolean | null uidinteger | null #### Answer 200 · FileInfo · application/json is_dirrequiredboolean is_symlinkrequiredboolean moderequiredstring mtime_unix_nsrequiredinteger pathrequiredstring sandbox_idrequiredstring served_bystring | null sizerequiredinteger ### POST/v1/sandboxes/{id}/files/copy Auth: API key Copy a file, or a whole tree with `recursive`. A symlink is copied as a symlink, never followed. #### Parameters idrequiredpath · string #### Request body FileCopy · application/json fromrequiredstring overwriteboolean | null recursiveboolean | null torequiredstring #### Answer 200 · FileInfo · application/json is_dirrequiredboolean is_symlinkrequiredboolean moderequiredstring mtime_unix_nsrequiredinteger pathrequiredstring sandbox_idrequiredstring served_bystring | null sizerequiredinteger ### POST/v1/sandboxes/{id}/files/extract Auth: API key Unpack a tar that is already inside the sandbox. `strip` drops leading path components, like `tar --strip-components`. An entry that is absolute or contains `..` is refused. #### Parameters idrequiredpath · string #### Request body FileExtract · application/json archiverequiredstring intorequiredstring stripinteger | null Leading path components dropped from each entry, 0–32. #### Answer 200 · ExtractResult · application/json archiverequiredstring entriesinteger | null Entries written. `null` from the fallback path, which cannot count them without a second pass over the archive — and a number nobody counted is worse than no number. intorequiredstring sandbox_idrequiredstring served_bystring | null ### GET/v1/sandboxes/{id}/files/list Auth: API key List a directory. `?path=`, plus `?recursive=1`, `?depth=N`, `?limit=N` and `?hidden=0`. Entries carry name, size, mode, uid, gid, mtime and kind. A listing cut short by `limit` says `truncated: true` rather than looking like the end of the directory. #### Parameters idrequiredpath · string containsquery · string hiddenquery · string ignore_casequery · string limitquery · integer pathquery · string patternquery · string recursivequery · string #### Answer 200 · FileListing · application/json entriesrequiredDirEntry[] pathrequiredstring sandbox_idrequiredstring served_bystring | null truncatedrequiredboolean The listing stopped at `limit`. **Not** "the directory ended" — a caller that treats a truncated page as a complete one will report a file as missing when it is merely past the cut. ### POST/v1/sandboxes/{id}/files/mkdir Auth: API key Create a directory. `parents` is `mkdir -p` and makes an existing directory a success; without it a missing parent is a 404 and an existing path is a conflict, which is what a caller using the call as a lock wants. #### Parameters idrequiredpath · string #### Request body FileMkdir · application/json modeFileMode | null parentsboolean | null Create missing parents too. pathrequiredstring #### Answer 200 · FileInfo · application/json is_dirrequiredboolean is_symlinkrequiredboolean moderequiredstring mtime_unix_nsrequiredinteger pathrequiredstring sandbox_idrequiredstring served_bystring | null sizerequiredinteger ### POST/v1/sandboxes/{id}/files/move Auth: API key Rename or move a path. Works across filesystems. Without `overwrite` an existing destination is a conflict rather than something silently destroyed. #### Parameters idrequiredpath · string #### Request body FileMove · application/json fromrequiredstring overwriteboolean | null torequiredstring #### Answer 200 · FileInfo · application/json is_dirrequiredboolean is_symlinkrequiredboolean moderequiredstring mtime_unix_nsrequiredinteger pathrequiredstring sandbox_idrequiredstring served_bystring | null sizerequiredinteger ### GET/v1/sandboxes/{id}/files/search Auth: API key Find files under `?path=`. `?pattern=` is a glob over the file name (`*.py`); `?contains=` is literal text to find inside the files that match, which answers with the line number and the line. `?ignore_case=1`, `?limit=N`, `?hidden=0`. Binary files are skipped rather than printed. #### Parameters idrequiredpath · string containsquery · string hiddenquery · string ignore_casequery · string limitquery · integer pathquery · string patternquery · string recursivequery · string #### Answer 200 · SearchResult · application/json matchesrequiredSearchMatch[] notestring | null The cut in words, and how to search the rest. Absent when nothing was cut. pathrequiredstring sandbox_idrequiredstring served_bystring | null truncatedrequiredboolean truncated_bystring | null Why `truncated` is true: `entries` — a search looks at the first 10,000 entries under `path` (by name, a directory's own entries before its subdirectories') and stopped there, so files past them were not searched; `matches` — it found `limit` matches and stopped. Absent when nothing was cut. ### GET/v1/sandboxes/{id}/files/stat Auth: API key Size, mode, mtime and kind for one path. `?path=`. #### Parameters idrequiredpath · string pathquery · string #### Answer 200 · FileStatView · application/json pathrequiredstring sandbox_idrequiredstring statrequiredFileStat Size, mode, modification time and kind for one path, as the sandbox reports them. Every field is optional because the answer is the sandbox's, not ours: a path the sandbox could not describe comes back named but otherwise empty, rather than filled in with zeroes. [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/reference/api/ports-and-terminal [API reference](https://www.promigence.ai/docs/reference/api) # Ports and terminal 8 routes of the published API contract, generated from it. ### GET/v1/sandboxes/{id}/ports Auth: API key List this sandbox's preview URLs. #### Parameters idrequiredpath · string #### Answer 200 · PortList · application/json portsrequiredPort[] sandbox_idrequiredstring ### POST/v1/sandboxes/{id}/ports Auth: API key Mint a preview URL for a port in the sandbox. Anyone holding the URL can reach the port — it is a bearer token in a link, so pass `ttl_s` to make it stop working on its own rather than relying on someone remembering to revoke it. `url` is the form to use; `path_url` and `host_url` are always returned by name, so a client that needs one specifically never has to parse `url`. #### Parameters idrequiredpath · string #### Request body PortOpen · application/json portrequiredinteger 1–65535. #### Answer 200 · Port · application/json created_unix_nsinteger | null Unix nanoseconds. host_url_labelstring | null The same publication addressed by name rather than by path. Apps that emit absolute paths need this form. portinteger | null The port inside the sandbox. sandbox_idrequiredstring tokenstring | null The token the URL carries. Pass it to `DELETE /v1/sandboxes/{id}/ports/{token_or_port}` to revoke this one URL. urlstring | null The URL to open. ### DELETE/v1/sandboxes/{id}/ports/{token_or_port} Auth: API key Revoke one URL by its token, or every URL for a port by the port number. #### Parameters idrequiredpath · string token_or_portrequiredpath · string #### Answer 200 · PortsRevoked · application/json okrequiredboolean revokedrequiredstring[] The tokens that were revoked. Revoking by port number revokes every URL minted for that port, so this can hold more than one. sandbox_idrequiredstring ### GET/v1/sandboxes/{id}/pty Auth: API key · upgrades to a WebSocket A WebSocket terminal, relayed byte for byte. `?cols=&rows=&cmd=`. Authenticated by the `Authorization` header, never a query string. Its `open` event carries `resume`: send it back in the `promigence-resume` header (from a browser, as the subprotocol `promigence.resume.`), with `?received=` the output bytes you have, to pick the same terminal up where it left off after a dropped connection or a service update. If some of its output was not kept meanwhile, the `open` event's `dropped` says how many bytes. One that can no longer be picked up again answers 404. #### Parameters idrequiredpath · string cmdquery · string colsquery · integer receivedquery · integer rowsquery · integer ### GET/v1/sandboxes/{id}/ssh Auth: API key The keys this sandbox will accept over SSH, and for how long. #### Parameters idrequiredpath · string #### Answer 200 · SshAccessList · application/json host_keystring | null Absent when the sandbox has never been asked for SSH access. host_key_fingerprintstring | null idle_timeout_srequiredinteger keysrequiredSshKey[] sandbox_idrequiredstring ### POST/v1/sandboxes/{id}/ssh Auth: API key Authorise an `ssh-ed25519` public key for this sandbox and mint the short-lived credential an SSH connection to it uses. The login name is the sandbox id; the answer carries the sandbox's own host key, so a client can pin it instead of turning host verification off. #### Parameters idrequiredpath · string #### Request body SshAccessRequest · application/json idle_timeout_sinteger | null Seconds an idle connection is kept. public_keyrequiredstring An OpenSSH public key line. ttl_sinteger | null Seconds the key is accepted. #### Answer 200 · SshAccess · application/json expires_atrequiredstring When the key and the token both stop working (RFC 3339). fingerprintrequiredstring `SHA256:…` of the public key that was authorised, as `ssh-keygen -lf` prints it. hostrequiredstring The host to give `ssh`. It is an alias resolved by the tunnel, not a routable name. host_keyrequiredstring The sandbox's own host key, as a `known_hosts` line body (`ssh-ed25519 AAAA…`). Pin it instead of turning host verification off; it is minted for this sandbox and dies with it. host_key_fingerprintrequiredstring `SHA256:…` of `host_key`, which is what `ssh` prints on a first connection. idle_timeout_srequiredinteger Seconds of inactivity after which an open session is closed. key_idrequiredstring Identifier for the authorised key, for revoking it later. proxy_commandrequiredstring The `ProxyCommand` that carries the connection: `promigence sandbox ssh --proxy`. sandbox_idrequiredstring The sandbox this access is for. ssh_commandrequiredstring A complete `ssh` command line, for pasting. tokenrequiredstring The short-lived credential the tunnel authenticates with. Shown once. userrequiredstring The login name to use. It is the sandbox id: a key is authorised for one name only. ### DELETE/v1/sandboxes/{id}/ssh/{key_id} Auth: API key Revoke one key by id or fingerprint, and the access credential issued with it. Idempotent: `revoked: false` means neither existed. #### Parameters idrequiredpath · string key_idrequiredpath · string #### Answer 200 · SshRevoked · application/json key_idrequiredstring revokedrequiredboolean sandbox_idrequiredstring ### GET/v1/sandboxes/{id}/ssh/connect Auth: API key · upgrades to a WebSocket A WebSocket carrying the SSH byte stream, relayed byte for byte. Accepts either an API key or the short-lived per-sandbox credential from `POST /v1/sandboxes/:id/ssh`, in the `Authorization` header. This is what `promigence sandbox ssh --proxy` speaks; you do not call it by hand. #### Parameters idrequiredpath · string [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/reference/api/secrets [API reference](https://www.promigence.ai/docs/reference/api) # Secrets 3 routes of the published API contract, generated from it. ### GET/v1/secrets Auth: API key The calling key's project's secret names and shapes, and for a bound secret its `urls` and `env` as `POST /v1/secrets` answers them. Never values. #### Answer 200 · SecretList · application/json secretsrequiredSecretSummary[] ### POST/v1/secrets Auth: API key Store a secret in the calling key's project (the same name may hold a different value in another project). Write-only: no route ever returns a value, and only that project's sandboxes are given it. With `hosts` the secret is bound to those hosts: requests a sandbox sends to the address in the answer's `urls` (with the request's path added) are authenticated with it, a request sent straight to the host is not, and the value stays out of the sandbox unless a run asks for it with `mode: "raw"`. `raw: "refused"` means the value itself can never be given to a sandbox; `allowed` is the default. A sandbox given a secret bound to `api.openai.com` or `api.anthropic.com` also gets `OPENAI_BASE_URL` or `ANTHROPIC_BASE_URL` set to that address (the answer's `env` names each variable and its value), so those SDKs need no change. Setting a secret again keeps every binding field the request leaves out; `hosts: []` removes the binding. #### Request body SecretSet · application/json bodyboolean | null Let the secret be used in request bodies to its hosts. Not available yet: `true` is refused, `false` (the default) is accepted. headersstring[] | null Request headers the value may be sent in. hostsstring[] | null Host names the value may be sent to (never addresses). namerequiredstring A valid environment variable name. queryboolean | null Let the secret be used in query strings to its hosts. Not available yet: `true` is refused, `false` (the default) is accepted. rawSecretRaw | null Whether a command may ask for the value itself. scan_responsesboolean | null Mask the value in responses from its hosts. valuerequiredstring #### Answer 200 · SecretStored · application/json bytesrequiredinteger The length of the value that was stored, in bytes. createdrequiredboolean False when an existing secret of that name was overwritten in place. envmap of string The variables a sandbox that names this secret is also given, each set to the address in `urls` for a provider whose SDKs read their base URL from a variable (with the path those SDKs expect), such as `OPENAI_BASE_URL` for `api.openai.com` and `ANTHROPIC_BASE_URL` for `api.anthropic.com`. A variable the caller sets itself wins. Absent when there is none. hostsstring[] The hosts the secret is bound to. Absent when it is not bound, and a sandbox that names it is given the value itself. namerequiredstring nextrequiredstring[] What to do next, ready to run. placeholderstring | null What the variable holds, in place of the value, in a sandbox that names this secret. Present when `hosts` is. rawstring | null `refused` when the value itself can never be given to a sandbox, `allowed` (the default) otherwise. Present when `hosts` is. scan_responsesboolean | null Whether the value is masked out of responses from the bound hosts. Present when `hosts` is. updated_atrequiredstring RFC 3339. urlsstring[] For each of `hosts`, in the same order, the address a sandbox sends that host's requests to, with the request's path added after it. Requests sent there are authenticated with the secret; a request sent straight to the host is not. For a `*.` host, put the name in place of the `*`. Present when `hosts` is. ### DELETE/v1/secrets/{name} Auth: API key Remove a secret. #### Parameters namerequiredpath · string #### Answer 200 · SecretDeleted · application/json deletedrequiredboolean namerequiredstring [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/reference/api/organisation [API reference](https://www.promigence.ai/docs/reference/api) # Organisation 24 routes of the published API contract, generated from it. ### GET/v1/invites Auth: sign-in token Invites waiting for your verified email address, from any organization. Needs a sign-in. #### Answer 200 · InviteList · application/json invitesrequiredInviteView[] ### POST/v1/invites/{invite_id}/accept Auth: sign-in token Accept an invite and join the organization. Needs a sign-in: the identity token's own verified email must be the invited address, and the member who sent it must still be an owner. #### Parameters invite_idrequiredpath · string #### Answer 200 · OrgView · application/json card_on_filerequiredboolean A payment method is on file. created_atrequiredstring RFC 3339. defaultrequiredboolean True for the organization a sign-in and the CLI use when none is named. membersrequiredinteger namerequiredstring org_idrequiredstring projectsrequiredinteger rolerequiredstring Your role in it: `owner` or `member`. ### POST/v1/invites/{invite_id}/decline Auth: sign-in token Decline an invite sent to your verified email address. It is gone for good, and the organization may invite the address again. #### Parameters invite_idrequiredpath · string #### Answer 200 · InviteRevoked · application/json invite_idrequiredstring revokedrequiredboolean ### GET/v1/me Auth: API key Who you are, what your limits are, what you have spent, and what trial credit is left. #### Answer 200 · Me · application/json card_on_filerequiredboolean concurrencyMeConcurrency Live sandboxes now, against the organisation's limit. default_spend_caprequirednumber The cap a run gets when it names none, in USD. keyKeyRef | null The key this request was made with. limitsrequiredMeLimits The limits in force for an organisation. locationstring | null Where sandboxes run, in plain words (for example "US East Coast"), as `GET /v1/health` says it. Absent when the service does not say. location_codestring | null The same place as a short code, for example `us-east`. Only beside `location`; new codes may appear, and a code you do not know is fine to ignore. noticeTrialNotice | null A notice about a coming change to the trial rules; `null` when there is none. orgrequiredstring The organisation's name. org_idrequiredstring planstring The plan the organisation's limits and prices come from: `hobby` for a trial organisation with no plan assigned. spendnumber | null What the organisation has spent, in USD. Absent for a key that may not see the organisation's money (see `trial`). spend_detailSpendDetail | null trialTrialStatus | null The organisation's trial credit. Absent for a key that may not see the organisation's money: only an owner's key of the default project does. userUserView | null The user behind the key this request was made with; `null` for a key minted by an operator. ### GET/v1/me/ledger Auth: API key The rows behind `spend`: usage recorded while each sandbox runs and when it ends. With a project's key, that project's rows and the organization's credit grants; `spend` stays the organization's. `?limit=N`. #### Parameters cursorquery · string limitquery · integer #### Answer 200 · LedgerList · application/json entriesrequiredLedgerEntryView[] Newest first. next_cursorstring | null Pass as `?cursor=` for the next page; `null` on the last one. ### GET/v1/me/outcomes Auth: API key What the organization got this month, measured from its own runs and sandboxes: runs and sandboxes started, the median time to ready, failures on our side that were not billed and what was given back, hours paused and what they would have cost running, failed sandboxes kept to reopen, and for runs of two or more sandboxes how many times faster than one after another and the time not spent waiting. With a project's key, that project's. A figure with nothing behind it is `null`. `?period=month`. #### Parameters periodquery · string #### Answer 200 · Outcomes · application/json batch_runsrequiredinteger Finished runs of two or more sandboxes this period. batch_saved_snumber | null For those runs: seconds not spent waiting, the sum of their sandboxes' own times minus the runs' wall time; `null` without such a run. batch_speedupnumber | null For those runs: the sum of their sandboxes' own times divided by the runs' wall time (how many times faster than one after another); `null` without such a run. failures_oursrequiredinteger Sandboxes that ended on a failure on our side and were not billed for it. failures_ours_usdrequirednumber What was given back for those failures, in USD (`0` when they ended before any charge). kept_failuresrequiredinteger Failed sandboxes kept to reopen that can still be reopened. paused_hoursnumber | null Hours this period's sandboxes spent paused, which is not billed; `null` if none paused. paused_usdnumber | null What those paused hours would have cost running, in USD; `null` if none paused. periodrequiredstring `month`: the calendar month so far, UTC. ready_ms_p50number | null The median milliseconds until a sandbox was ready to take work; `null` with no sandbox. runsrequiredinteger Runs started this period. sandboxesrequiredinteger Sandboxes started this period. sincerequiredstring When the period began (RFC 3339, UTC). ### GET/v1/orgs Auth: API key The organizations you belong to, your role in each, and which one is your default. With an API key, only that key's own organization; a sign-in lists every one. #### Answer 200 · OrgList · application/json orgsrequiredOrgView[] ### POST/v1/orgs Auth: sign-in token Create an organization. You become its owner and it starts with a `default` project. It gets no trial credit — the trial belongs to the person — so add a card before its first run. #### Request body NameCreate · application/json namerequiredstring 1–40 lowercase letters, digits and dashes. #### Answer 201 · OrgView · application/json card_on_filerequiredboolean A payment method is on file. created_atrequiredstring RFC 3339. defaultrequiredboolean True for the organization a sign-in and the CLI use when none is named. membersrequiredinteger namerequiredstring org_idrequiredstring projectsrequiredinteger rolerequiredstring Your role in it: `owner` or `member`. ### PATCH/v1/orgs/{org} Auth: API key Rename an organization. Owners only. Its id never changes; anything that names it by the old name (a script, `--org`, a saved URL) must use the new one. The same rules as a new name: free, and not starting with `promigence`. #### Parameters orgrequiredpath · string #### Request body OrgPatch · application/json namerequiredstring 1–40 lowercase letters, digits and dashes. #### Answer 200 · OrgView · application/json card_on_filerequiredboolean A payment method is on file. created_atrequiredstring RFC 3339. defaultrequiredboolean True for the organization a sign-in and the CLI use when none is named. membersrequiredinteger namerequiredstring org_idrequiredstring projectsrequiredinteger rolerequiredstring Your role in it: `owner` or `member`. ### DELETE/v1/orgs/{org} Auth: API key Delete an organization. Its keys stop working, pending invites are revoked and every member leaves it; a member for whom it was the only organization gets a fresh personal one (no trial credit). Owners only, signed in. Refused while it is suspended, has a subscription (cancel it in the billing portal first), a snapshot, a build running, a failure capture or a sandbox that has not ended (a paused one included). Its secrets are deleted, the commands and output of its runs and builds and the data stored for it are erased, and its name is freed; invoices, the billing ledger and the audit log are kept. #### Parameters orgrequiredpath · string #### Request body OrgDelete · application/json confirmrequiredstring The organization's name, typed out. #### Answer 200 · OrgDeleted · application/json deletedrequiredboolean keys_revokedrequiredinteger Keys that stopped working (every key of the organization). members_rehomedrequiredinteger Members it was the last organization of, each given a fresh personal one. org_idrequiredstring ### GET/v1/orgs/{org}/audit Auth: API key The organization's audit log, newest first: keys minted and revoked, invites, role changes, removals, projects, billing events, suspension, and what support did to the organization (shown as `Promigence support`). Owners only, signed in. `?before=&limit=` (at most 100) pages back. #### Parameters orgrequiredpath · string beforequery · integer limitquery · integer #### Answer 200 · AuditList · application/json entriesrequiredAuditEntry[] org_idrequiredstring ### POST/v1/orgs/{org}/default Auth: API key Make this organization the one a sign-in and the CLI use when none is named. #### Parameters orgrequiredpath · string #### Answer 200 · OrgView · application/json card_on_filerequiredboolean A payment method is on file. created_atrequiredstring RFC 3339. defaultrequiredboolean True for the organization a sign-in and the CLI use when none is named. membersrequiredinteger namerequiredstring org_idrequiredstring projectsrequiredinteger rolerequiredstring Your role in it: `owner` or `member`. ### GET/v1/orgs/{org}/invites Auth: API key Pending invites to an organization. An invite nobody accepts is gone after 14 days. #### Parameters orgrequiredpath · string #### Answer 200 · InviteList · application/json invitesrequiredInviteView[] ### POST/v1/orgs/{org}/invites Auth: API key Invite an email address. Owners only, signed in (not with a key). Only a signed-in user whose verified email is that address can accept it. #### Parameters orgrequiredpath · string #### Request body InviteCreate · application/json emailrequiredstring rolestring | null `owner` or `member` (default). #### Answer 201 · InviteView · application/json created_atrequiredstring RFC 3339. emailrequiredstring The address invited. Only a signed-in user whose verified email is this address can accept it. invite_idrequiredstring invited_byrequiredstring The verified email of the owner who sent it, or `An owner of ` when that address is not verified. org_idrequiredstring org_namerequiredstring rolerequiredstring `owner` or `member`. ### DELETE/v1/orgs/{org}/invites/{invite_id} Auth: API key Revoke a pending invite. Owners only, signed in. #### Parameters orgrequiredpath · string invite_idrequiredpath · string #### Answer 200 · InviteRevoked · application/json invite_idrequiredstring revokedrequiredboolean ### POST/v1/orgs/{org}/invites/{invite_id}/resend Auth: API key Send a pending invite's email again: the same invite, its 14 days counted again from now. Owners only. At most once every 10 minutes and three times a day per invite. #### Parameters orgrequiredpath · string invite_idrequiredpath · string #### Answer 200 · InviteView · application/json created_atrequiredstring RFC 3339. emailrequiredstring The address invited. Only a signed-in user whose verified email is this address can accept it. invite_idrequiredstring invited_byrequiredstring The verified email of the owner who sent it, or `An owner of ` when that address is not verified. org_idrequiredstring org_namerequiredstring rolerequiredstring `owner` or `member`. ### GET/v1/orgs/{org}/members Auth: API key The members of an organization and their roles. #### Parameters orgrequiredpath · string #### Answer 200 · MemberList · application/json membersrequiredMemberView[] org_idrequiredstring ### PATCH/v1/orgs/{org}/members/{user_id} Auth: API key Change a member's role. Owners only, signed in (not with a key); an organization always keeps at least one owner. #### Parameters orgrequiredpath · string user_idrequiredpath · string #### Request body MemberRoleSet · application/json rolerequiredstring `owner` or `member`. #### Answer 200 · MemberList · application/json membersrequiredMemberView[] org_idrequiredstring ### DELETE/v1/orgs/{org}/members/{user_id} Auth: API key Remove a member (owners, signed in), or leave (your own user id, or `me`). The keys that person minted for themselves in the organization are revoked; service keys keep working. The last owner cannot leave, and nobody can leave their only organization; an owner removing someone from theirs gives them a fresh personal organization (no trial credit). #### Parameters orgrequiredpath · string user_idrequiredpath · string #### Answer 200 · MemberRemoved · application/json keys_revokedrequiredinteger Keys that person had minted for themselves in this organization, now revoked. Service keys keep working. org_idrequiredstring removedrequiredboolean user_idrequiredstring ### GET/v1/orgs/{org}/projects Auth: API key An organization's projects, each with what it was billed this calendar month (UTC): `month` and `month_spend_usd`, the figure its monthly cap is checked against. `?month=YYYY-MM` gives another month. API keys belong to a project; a project holds any number of repositories. #### Parameters orgrequiredpath · string monthquery · string #### Answer 200 · ProjectList · application/json org_idrequiredstring projectsrequiredProjectView[] ### POST/v1/orgs/{org}/projects Auth: API key Create a project. #### Parameters orgrequiredpath · string #### Request body NameCreate · application/json namerequiredstring 1–40 lowercase letters, digits and dashes. #### Answer 201 · ProjectView · application/json created_atrequiredstring RFC 3339. defaultrequiredboolean True for the project every organization starts with. It cannot be renamed or deleted. keysrequiredinteger Keys that still work. monthstring | null The calendar month (UTC, `YYYY-MM`) `month_spend_usd` is for: this month, or the one a list asked for with `?month=`. month_spend_usdnumber | null What this project's runs, data out and builds were billed in `month`, in USD: the same figure its monthly cap is checked against. monthly_cap_usdnumber | null The most this project's runs may bill in one calendar month (UTC), in USD; `null` = no cap. A run that would pass it is refused with `project_cap_reached`. Set by an owner. namerequiredstring org_idrequiredstring project_idrequiredstring ### PATCH/v1/orgs/{org}/projects/{project} Auth: API key Rename a project, set its monthly cap, or both. The `default` project keeps its name. The cap is the most the project may be billed in one calendar month (UTC) — its sandboxes, their data out and its builds — counting what its live sandboxes could still bill; a create, replay, open or extension past it is refused with `project_cap_reached` and nothing starts. Setting the cap is for owners, signed in (not with a key). #### Parameters orgrequiredpath · string projectrequiredpath · string #### Request body ProjectPatch · application/json · optional monthly_cap_usdnumber | null A monthly spending cap in USD, 0–1000000; `null` removes the cap. namestring | null #### Answer 200 · ProjectView · application/json created_atrequiredstring RFC 3339. defaultrequiredboolean True for the project every organization starts with. It cannot be renamed or deleted. keysrequiredinteger Keys that still work. monthstring | null The calendar month (UTC, `YYYY-MM`) `month_spend_usd` is for: this month, or the one a list asked for with `?month=`. month_spend_usdnumber | null What this project's runs, data out and builds were billed in `month`, in USD: the same figure its monthly cap is checked against. monthly_cap_usdnumber | null The most this project's runs may bill in one calendar month (UTC), in USD; `null` = no cap. A run that would pass it is refused with `project_cap_reached`. Set by an owner. namerequiredstring org_idrequiredstring project_idrequiredstring ### DELETE/v1/orgs/{org}/projects/{project} Auth: API key Delete a project with no working keys, no snapshots, no builds running, no failure captures and no sandbox that has not ended. Its secrets go with it; its past runs move to the `default` project. Owners only, signed in; never the `default` project. #### Parameters orgrequiredpath · string projectrequiredpath · string #### Answer 200 · ProjectDeleted · application/json deletedrequiredboolean project_idrequiredstring ### POST/v1/orgs/{org}/projects/{project}/move Auth: API key Move a project to another organization: its snapshots and secrets go with it, its past runs stay with the organization that paid for them, in its default project, and every key of the project is revoked (mint new ones there). Owners of the source only, signed in; you must belong to the target, and the target must have a card on file. Refused for the `default` project, a name the target already uses, or while any of the project's sandboxes has not ended, a build is running or a failure capture is left. #### Parameters orgrequiredpath · string projectrequiredpath · string #### Request body ProjectMove · application/json torequiredstring The target organization's id or name. #### Answer 200 · ProjectMoved · application/json from_org_idrequiredstring keys_revokedrequiredinteger project_idrequiredstring secrets_movedrequiredinteger snapshots_movedrequiredinteger to_org_idrequiredstring [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/reference/api/billing [API reference](https://www.promigence.ai/docs/reference/api) # Billing 10 routes of the published API contract, generated from it. ### GET/v1/billing Auth: API key Plan, card on file, this month's usage, and the upcoming invoice preview. #### Answer 200 · BillingStatus · application/json billing_enabledrequiredboolean False while card billing is not available. cardCardOnFile | null `null` while no card is on file. card_notestring | null A sentence to show beside the card when it does not unlock paid limits for this organization (it already pays for another one, or it is being confirmed with a $1 charge, or that charge did not go through); `null` otherwise. card_on_filerequiredboolean customerrequiredboolean True once a billing customer exists for the organisation. method_checkMethodCheckView | null The $1 that confirms the payment method on file when it has no stable payer (Apple Pay, Google Pay, Amazon Pay); `null` when it needed none. noticeTrialNotice | null org_idrequiredstring periodrequiredBillingPeriod The billing period `usage` covers. planrequiredstring suspend_reasonstring | null suspendedrequiredboolean trialrequiredTrialStatus The trial an organisation is on, and what is left of it. upcoming_invoiceUpcomingInvoice | null The payment provider's estimate of the next invoice; `null` when there is no subscription, or when the estimate could not be fetched (see `upcoming_invoice_error`). upcoming_invoice_errorstring | null usagerequiredPeriodUsage What a period cost, by what it was spent on. ### POST/v1/billing/checkout Auth: API key Start a card-setup checkout. Adding a card keeps any trial credit you have left. Owners only (with their own key). #### Answer 200 · CheckoutSession · application/json expires_atstring | null When the link stops working, RFC 3339. moderequiredstring `"setup"` — the checkout stores a card, it does not take a payment. session_idstring | null urlrequiredstring Open this. Adding a card keeps any trial credit that is left. ### GET/v1/billing/history Auth: API key Your billing history, newest first: every credit you received, with what is left of it and when it expires, and every payment (invoices paid, payments that failed, refunds). `kind` is `all` (the default), `credits` or `payments`; `limit` is up to 100 (50 by default); pass `next_cursor` back as `cursor` for older entries. Owners only (with their own key). #### Parameters cursorquery · string kindquery · string limitquery · integer #### Answer 200 · BillingHistory · application/json entriesrequiredBillingHistoryEntry[] next_cursorstring | null Pass as `cursor` for the next, older page; `null` on the last page. ### POST/v1/billing/portal Auth: API key A link to the billing portal. Owners only (with their own key). #### Answer 200 · PortalSession · application/json urlrequiredstring ### POST/v1/credits/claim Auth: none The claim the page sends: the link's token, the accepted terms version and the page's browser check. Answers the credit as it now stands: claimed, being checked (usually under 24 hours), or why there is none. Rate limited per address. #### Request body CreditClaim · application/json · optional accept_termsboolean browserstring | null powstring | null terms_versionstring | null tokenstring | null #### Answer 200 · CreditOffer · application/json campaignstring | null The giveaway this credit comes from, when it does. card_bonus_usdrequirednumber USD a first card would add, while it still would. credit_usdrequirednumber USD: what a claim gives now (`claimable`) or gave (`claimed`). expires_atstring | null When the credit expires (RFC 3339), when it does. messagerequiredstring One sentence for a person. method_check_usdnumber USD charged to confirm a payment method with no stable payer when it is added (Apple Pay, Google Pay, Amazon Pay): it is added to your credit, and the card bonus comes with it. staterequiredstring `claimable`, `claimed`, `pending_review`, `needs_card`, `not_eligible`, `offer_ended`, `denied` or `none`. ### POST/v1/credits/claim-link Auth: API key A single-use link (15 minutes) to the page where the free credit is claimed (`promigence credits claim` opens it). A service key cannot ask for one. `409` with the reason when there is nothing to claim. #### Answer 200 · ClaimLink · application/json expires_atrequiredstring RFC 3339. urlrequiredstring Open it in a browser. It works once, for 15 minutes. ### GET/v1/credits/offer Auth: API key Your account's free credit: claimable (and how much, until when), claimed, being checked, needs a card, or none. The credit is claimed in a browser, never with an API call alone. #### Answer 200 · CreditOffer · application/json campaignstring | null The giveaway this credit comes from, when it does. card_bonus_usdrequirednumber USD a first card would add, while it still would. credit_usdrequirednumber USD: what a claim gives now (`claimable`) or gave (`claimed`). expires_atstring | null When the credit expires (RFC 3339), when it does. messagerequiredstring One sentence for a person. method_check_usdnumber USD charged to confirm a payment method with no stable payer when it is added (Apple Pay, Google Pay, Amazon Pay): it is added to your credit, and the card bonus comes with it. staterequiredstring `claimable`, `claimed`, `pending_review`, `needs_card`, `not_eligible`, `offer_ended`, `denied` or `none`. ### GET/v1/pricing Auth: API key Your organization's price list, read live on every call from what billing charges: the per-second rates, every sandbox shape on sale and its price (a snapshot build is billed at its tier's), the limits, the free credit and the plan they come from (`scope: organization`). Needs an API key; without one the answer is `auth` (401). The published list prices are on the pricing page and in `promigence pricing` before you sign in. A run is billed at the rates in force when it was created. #### Answer 200 · PricingView · application/json as_ofrequiredstring When these values were read, RFC 3339. They can change at any time: read them again rather than keeping a copy. billingrequiredstring `per_second`: a sandbox bills `(vcpus × vcpu_second_usd + mem_gib × gib_second_usd) × billable seconds`, from hand-over to end, minus paused time. currencyrequiredstring `usd`. free_creditrequiredPricingFreeCredit The free credit a new account gets. An account's own credit, and whether it can still claim it, is `GET /v1/credits/offer`. granularity_secondsrequiredinteger Billable seconds are rounded up to this many. included_credits_usdrequirednumber Usage the monthly fee includes each month, USD. limitsrequiredPricingLimits The limits in force. min_billable_secondsrequiredinteger The fewest seconds a sandbox that ran is billed. monthly_fee_usdrequirednumber The plan's monthly fee, USD. monthly_minimum_usdrequirednumber A committed monthly minimum, USD; 0 for none. org_idrequiredstring The organisation these values are for. planrequiredPricingPlan The plan the prices and limits come from. ratesrequiredPricingRates The rates, USD. schemarequiredstring `promigence.pricing/v1`. scoperequiredstring `organization`: what the key's organisation pays. tiersrequiredPricingTier[] Every sandbox shape on sale, smallest first, priced at these rates. ### GET/v1/referrals Auth: API key Your referral code and its offer ("Give $X, get $Y"), your referrals by status, what they earned you, the referral you came through, and your credit that expires. The code exists while an offer runs. #### Answer 200 · ReferralStatus · application/json codestring | null Your code: a friend signs up with `promigence login --ref `. `null` while the program is off. earned_usdrequirednumber Credit your referrals have earned you, USD. expiring_creditsrequiredExpiringCredit[] Credit that expires, soonest first, with what is left of each grant. offerReferralOffer | null What your code offers now. `null` while the program is off. programrequiredstring `"on"` while an offer runs, else `"off"` (no code is handed out then). referralsrequiredReferralCounts Your referrals by status (counts only). referred_byReferredBy | null The referral this organization came through, if any. ### POST/v1/referrals/apply Auth: API key Apply a referral code to your organization: before its first paid invoice and within the offer's window after the organization was created. The credit comes with your first paid plan invoice. Owners only (with their own key). Body: `{code}`. #### Request body ReferralApply · application/json coderequiredstring The referral code, at most 64 characters. #### Answer 200 · ReferralApplied · application/json coderequiredstring detailstring | null Why the code was not applied (`not_applied` only). qualifying_plansrequiredstring[] Plans that invoice qualifies on; empty = any paid plan. reward_usdrequirednumber Compute credit this organization gets when it pays its first plan invoice, USD. statusrequiredstring `pending` (your credit comes with your first paid plan invoice), `under_review`, or — at sign-in only — `not_applied`. [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/reference/api/keys-and-sign-in [API reference](https://www.promigence.ai/docs/reference/api) # Keys and sign-in 12 routes of the published API contract, generated from it. ### GET/v1/auth/claim Auth: none The page where the free credit is claimed, in a browser: the offer, the terms to accept, and the Claim button. Opened from the single-use link `POST /v1/credits/claim-link` makes (`promigence credits claim`); the link's token is the authority. #### Parameters tquery · string #### Answer 200 · object · application/json ### GET/v1/auth/cli-callback Auth: none The page a browser lands on after sign-in; in headless mode it shows the code to paste back. #### Parameters codequery · string errorquery · string statequery · string #### Answer 200 · string · text/html ### POST/v1/auth/cli/requests Auth: none Start `promigence login` through the console: register the sign-in request (the PKCE S256 challenge, the state, the local port the CLI listens on or none to paste the code, the computer's name and the new key's name) and get the authorize page to open for it. The page shows the signed-in person what is asking, and when and from where the request was made; it refuses a request that is more than ten minutes old or was already answered. `promigence login` does this for you. #### Request body CliRequestCreate · application/json code_challengerequiredstring `base64url(sha256(code_verifier))`: the PKCE challenge (RFC 7636), 43 characters. code_challenge_methodrequiredstring `S256`, the only method accepted. devicestring | null The computer's name, shown on the page as the client reports it (at most 64 characters). key_namestring | null The new key's name (at most 64 characters; default `cli@`). portinteger | null The local port the client listens on for the code: one of `GET /v1/auth/config`'s `loopback_redirect_uris`. Absent: the page shows the code, to paste into the client. providerstring | null `github` or `google`: a browser that is not signed in goes straight to that sign-in method. refstring | null A referral code, applied if this sign-in creates the account. staterequiredstring Handed back with the code, unchanged: 8 to 128 URL-safe characters. #### Answer 201 · CliRequestCreated · application/json authorize_urlrequiredstring The authorize page for this request. expires_in_srequiredinteger Seconds the request waits to be authorized; after that the page refuses it. request_idrequiredstring `creq_…`: names the request. ### POST/v1/auth/cli/token Auth: none Finish `promigence login` after you authorized the CLI in the browser: exchange the one-time code the authorize page gave the CLI, with the PKCE verifier whose S256 challenge the CLI sent there, for an API key (`api_key`, in this answer only). A code works once, for five minutes, and only with its own verifier and the redirect it was delivered to; any other attempt uses it up. `promigence login` does this for you; `GET /v1/auth/config` names the authorize page in `console_authorize_url`. #### Request body CliTokenCreate · application/json coderequiredstring The one-time code the authorize page handed the client (single use, five minutes). code_verifierrequiredstring The PKCE verifier whose S256 challenge the client sent to the authorize page. redirect_uristring | null The loopback redirect the code was delivered to; absent for a code that was pasted. #### Answer 201 · Session · application/json api_keystring | null **The secret of the key that was minted, sent once.** Only when `mint_key` was asked for. createdrequiredboolean True when this call created the account. keyKeyView | null The key that was minted, without its secret. Only when `mint_key` was asked for. orgrequiredSessionOrg The organisation a sign-in lands in. referralReferralApplied | null Only when a first sign-in sent a referral code (`promigence login --ref`): what became of it. A code that does not apply never stops the sign-in. trialSessionTrial | null Only when the account was created: what the trial granted. userrequiredUserView A user, as the sign-in and organisation routes report one. ### GET/v1/auth/config Auth: none What `promigence login` needs to start a sign-in: the identity domain, client id and scopes, and the console page where you authorize the CLI (`console_authorize_url`, when it is offered). #### Answer 200 · AuthConfig · application/json authorize_urlrequiredstring client_idrequiredstring console_authorize_urlstring | null Where a command-line client sends the browser to have the signed-in person authorize it (`promigence login`): the client registers its request first (`POST /v1/auth/cli/requests`, which answers the page's address for it); the page shows the request and asks for a click, then hands the client a one-time code it exchanges at `POST /v1/auth/cli/token`. Absent when that page is not offered; a client then signs in through `authorize_url` as before. identity_providersrequiredmap of string The sign-in methods to offer, as name -> label (`email`, `google`, `github`). A client that asks the sign-in pages for one method passes the label as their `identity_provider`, except `email`, which is the pages' own form and needs none. invite_modeboolean True while new accounts need an invite code: a client redeems one (`POST /v1/auth/invite`) before it starts the sign-in (`promigence signup`). An existing account signs in as before either way. loopback_redirect_urisrequiredstring[] The redirect URIs a command-line client may listen on. paste_redirect_urirequiredstring Where a headless sign-in lands instead, to show a code to paste back. scopesrequiredstring[] token_urlrequiredstring ### POST/v1/auth/invite Auth: none Redeem an invite code for one sign-in attempt, before the sign-in starts (`promigence signup` does it for you). Only while `GET /v1/auth/config` says `invite_mode`: the attempt with the same login nonce may then create an account within `expires_in_s`. Every code that does not redeem gets the same `403 invite_invalid`; attempts are rate limited per address. #### Request body InviteRedeem · application/json coderequiredstring The invite code. noncerequiredstring The sign-in attempt's login nonce. #### Answer 200 · InviteRedeemed · application/json expires_in_srequiredinteger Seconds the redeemed code holds this sign-in attempt's place (0 when invite mode is off). invite_moderequiredboolean False when invite mode is off: no code is needed and none was looked at. ### POST/v1/auth/invite/release Auth: none Give back the place a redeemed invite code holds for a sign-in attempt that ended without an account (it timed out or was cancelled), so the next attempt can redeem the code at once (`promigence signup` does it for you). Only the attempt's own login nonce names its hold, and a hold that already created an account is never given back. Always `200 {released}`; rate limited per address. #### Request body InviteRelease · application/json noncerequiredstring The sign-in attempt's login nonce. #### Answer 200 · InviteReleased · application/json releasedrequiredboolean True when this attempt held a place and gave it back; false when it held nothing (it never redeemed a code, its hold had lapsed, it already created the account, or invite mode is off). ### POST/v1/auth/session Auth: sign-in token Exchange an identity token for a Promigence API key. The first call for an identity creates the user, the org, its free credit offer (claimed later in a browser, `POST /v1/credits/claim-link`) and the first key, in one transaction. One account per verified email address: a first sign-in whose address already has an account through another sign-in method creates nothing and is answered `409 account_exists`, naming the method to sign in with. While invite mode is on, a first sign-in whose attempt redeemed no invite code (`POST /v1/auth/invite`) creates nothing and is answered `403 invite_required`; an existing account is never asked for a code. #### Request body SessionCreate · application/json · optional key_namestring | null The minted key's name (default `cli`, at most 64 characters). mint_keyboolean Also mint an API key. noncestring | null The login nonce, when the sign-in was started with one. refstring | null A referral code. #### Answer 200 · Session · application/json api_keystring | null **The secret of the key that was minted, sent once.** Only when `mint_key` was asked for. createdrequiredboolean True when this call created the account. keyKeyView | null The key that was minted, without its secret. Only when `mint_key` was asked for. orgrequiredSessionOrg The organisation a sign-in lands in. referralReferralApplied | null Only when a first sign-in sent a referral code (`promigence login --ref`): what became of it. A code that does not apply never stops the sign-in. trialSessionTrial | null Only when the account was created: what the trial granted. userrequiredUserView A user, as the sign-in and organisation routes report one. ### GET/v1/keys Auth: API key List your org's keys: with an API key, its own project's; with an identity token, every project's. `?all=1` includes revoked ones. #### Parameters allquery · string #### Answer 200 · KeyList · application/json keysrequiredKeyView[] org_idrequiredstring ### POST/v1/keys Auth: API key Mint a key. `api_key` is in the 201 response and is never retrievable again. A key minted by a key stays in that key's project, and is revoked when that key is; a service key cannot mint. A key does not expire unless you give it an expiry; past it, the key answers `401 key_expired`, and the org's owners are mailed 14 and 3 days before. #### Request body KeyCreate · application/json · optional accessstring | null `full` (the default) | `run` (sandboxes, runs and builds, whose runs can use the project's stored secrets; no changes to secrets, keys or billing) | `read` (reads everything in the project, file contents and command output included; changes nothing). expires_atstring | null A date (`2027-01-31`) or a UTC time ending in `Z`. expires_in_daysinteger | null 1–3650. namestring | null Default `cli`, at most 64 characters. #### Answer 201 · KeyView · application/json accessstring What the key may do: `full`, `run` (sandboxes, runs and builds, whose runs can use the project's stored secrets; no changes to secrets, keys or billing) or `read` (reads everything in the project, file contents and command output included; changes nothing). also_revokedstring[] | null Only on the answer to `DELETE /v1/keys/{key_id}`: the key ids this revocation also revoked, because the key had minted them (directly or further down). Absent when the key replaced itself (`?reason=replaced`), which revokes nothing it minted. api_keystring | null **The secret, and the only time it is ever sent.** Only on the 201 from `POST /v1/keys`; it cannot be retrieved afterwards. created_atrequiredstring RFC 3339. created_bystring | null The user who minted it; `null` for a key minted by another key. currentboolean | null True for the key this request was made with. Absent from the answer that mints a key, which is not yet the key you are calling with. expires_atstring | null RFC 3339: when the key stops working, as chosen when it was created. `null` = it does not expire (the default). An expired key answers `key_expired`. key_idrequiredstring last_used_atstring | null RFC 3339; `null` for a key that has never been used. minted_bystring | null The key that minted this one; `null` for a key minted by a sign-in. Revoking a key revokes every key it minted, and every key those minted. namerequiredstring networksKeyNetwork[] | null The networks the key was used from, most recent first (at most 20): each an IPv4 `/24` or an IPv6 `/64`, never a full address, with when it was first and last seen there. On the key list; absent elsewhere. prefixrequiredstring The first few characters, enough to recognise a key without holding it. revokedboolean | null Only on the answer to `DELETE /v1/keys/{key_id}`. revoked_atstring | null RFC 3339; `null` while the key still works. ### DELETE/v1/keys/{key_id} Auth: API key Revoke a key, and every key it minted (and every key those minted): `also_revoked` lists them. Your own key is yours to revoke; another member's key, or any service key, needs the owner role; a service key may revoke only itself. `?reason=replaced` or `?reason=logout` from the key itself (the CLI rotating or ending its session key) revokes only that key. #### Parameters key_idrequiredpath · string reasonquery · string #### Answer 200 · KeyView · application/json accessstring What the key may do: `full`, `run` (sandboxes, runs and builds, whose runs can use the project's stored secrets; no changes to secrets, keys or billing) or `read` (reads everything in the project, file contents and command output included; changes nothing). also_revokedstring[] | null Only on the answer to `DELETE /v1/keys/{key_id}`: the key ids this revocation also revoked, because the key had minted them (directly or further down). Absent when the key replaced itself (`?reason=replaced`), which revokes nothing it minted. api_keystring | null **The secret, and the only time it is ever sent.** Only on the 201 from `POST /v1/keys`; it cannot be retrieved afterwards. created_atrequiredstring RFC 3339. created_bystring | null The user who minted it; `null` for a key minted by another key. currentboolean | null True for the key this request was made with. Absent from the answer that mints a key, which is not yet the key you are calling with. expires_atstring | null RFC 3339: when the key stops working, as chosen when it was created. `null` = it does not expire (the default). An expired key answers `key_expired`. key_idrequiredstring last_used_atstring | null RFC 3339; `null` for a key that has never been used. minted_bystring | null The key that minted this one; `null` for a key minted by a sign-in. Revoking a key revokes every key it minted, and every key those minted. namerequiredstring networksKeyNetwork[] | null The networks the key was used from, most recent first (at most 20): each an IPv4 `/24` or an IPv6 `/64`, never a full address, with when it was first and last seen there. On the key list; absent elsewhere. prefixrequiredstring The first few characters, enough to recognise a key without holding it. revokedboolean | null Only on the answer to `DELETE /v1/keys/{key_id}`. revoked_atstring | null RFC 3339; `null` while the key still works. ### POST/v1/orgs/{org}/keys Auth: API key Mint a key in an organization you belong to, in one of its projects. With an API key, only in that key's own organization; with a sign-in, in any of yours. `service: true` (owners only) makes a project's key that keeps working when the member who minted it leaves, and that cannot manage the organization; any other key is revoked with its minter's membership. #### Parameters orgrequiredpath · string #### Request body OrgKeyCreate · application/json · optional accessstring | null `full` (the default) | `run` (sandboxes, runs and builds, whose runs can use the project's stored secrets; no changes to secrets, keys or billing) | `read` (reads everything in the project, file contents and command output included; changes nothing). defaultboolean Also make this organization your default. expires_atstring | null A date or a UTC time ending in `Z`. expires_in_daysinteger | null 1–3650. expires_in_minutesinteger | null 1–1440: a short-lived key, its lifetime counted on the server's clock. namestring | null Default `cli`, at most 64 characters. projectstring | null A project id or name. Default: the calling key's project, or the default project. serviceboolean A service key: not tied to a person. #### Answer 201 · OrgKeyView · application/json accessstring What the key may do: `full`, `run` (sandboxes, runs and builds, whose runs can use the project's stored secrets; no changes to secrets, keys or billing) or `read` (reads everything in the project, file contents and command output included; changes nothing). api_keyrequiredstring **The secret, and the only time it is ever sent.** created_atrequiredstring RFC 3339. created_bystring | null The user who minted it. expires_atstring | null RFC 3339: when the key stops working, as chosen when it was created. `null` = it does not expire (the default). key_idrequiredstring namerequiredstring org_idrequiredstring prefixrequiredstring project_idrequiredstring servicerequiredboolean A service key (CI, a worker pool) keeps working when the member who minted it leaves; a member's own key is revoked with their membership. [Every route](https://www.promigence.ai/docs/reference/api) · [what each error means and whether it was billed](https://www.promigence.ai/docs/errors) --- Page: https://www.promigence.ai/docs/guides # Guides Step by step: run a coding agent, an agent framework or an eval harness in a Promigence sandbox, from installing it to reading what it did, with every command to copy. - [A GitHub Actions runner in two lines](https://www.promigence.ai/docs/guides/github-actions-runner) Move GitHub Actions jobs to Promigence sandboxes with one workflow line, on runners we host or ones you start with one command, and run GitLab CI jobs the same way with a tagged runner. - [Build an MCP server with an execute tool backed by a sandbox](https://www.promigence.ai/docs/guides/mcp-execute-tool) A complete MCP server in TypeScript and Python whose execute tool runs model-written code in a Promigence sandbox of its own per session, with no network, a spend cap and a timeout. - [Give every user of your product their own sandbox](https://www.promigence.ai/docs/guides/sandbox-per-user) Run each user's code in a sandbox of their own: a key for your backend, a project with a monthly cap, a sandbox found again by the user's id, paused when idle and capped in dollars, and the self-host question answered. - [Run AI security-testing agents against a fresh copy of your own application](https://www.promigence.ai/docs/guides/ai-pentest-fresh-target) Build your application into a Promigence snapshot once, then give your security-testing agent a fresh copy of it for every run, behind an outbound allow-list that names only your model API, with the model key kept out and a spend cap on the run. - [Run Claude Agent SDK agents in a Promigence sandbox](https://www.promigence.ai/docs/guides/claude-agent-sdk) Keep the Claude Agent SDK loop in your process and run Claude Code itself inside a Promigence sandbox, with your Anthropic key stored as a secret. - [Run Claude Code, Codex or OpenCode in a sandbox](https://www.promigence.ai/docs/guides/claude-code-and-codex) Start a coding agent in its own Promigence sandbox with one command, keep the model key off the command line, and drive sandboxes from Claude Code. - [Run Google ADK agents in a Promigence sandbox](https://www.promigence.ai/docs/guides/google-adk) Point a Google ADK agent's environment tools or code executor at a Promigence sandbox, so its commands and code run there. - [Run Harbor tasks in a Promigence sandbox](https://www.promigence.ai/docs/guides/harbor) Select Promigence in Harbor with one flag to run Terminal-Bench and other Harbor tasks in cloud sandboxes, each trial in its own copy. - [Run Inspect evals in a Promigence sandbox](https://www.promigence.ai/docs/guides/inspect-evals) Use sandbox="promigence" in Inspect to give every sample its own cloud sandbox, with Docker-style tasks running unchanged. - [Run LangChain Deep Agents in a Promigence sandbox](https://www.promigence.ai/docs/guides/langchain) Use a Promigence sandbox as the backend for a LangChain Deep Agent, or as the sandbox provider for deepagents-code. - [Run LLM-generated code safely](https://www.promigence.ai/docs/guides/run-ai-written-code-safely) Give each user or session its own sandbox, decide what it may reach on the network, cap its spend and time, keep credentials out of it, and end it when done. - [Run OpenAI Agents SDK agents in a Promigence sandbox](https://www.promigence.ai/docs/guides/openai-agents-sdk) Give an OpenAI Agents SDK SandboxAgent a Promigence sandbox, so its shell and file tools run there instead of on your machine. - [Run Strands agents in a Promigence sandbox](https://www.promigence.ai/docs/guides/strands) Give a Strands agent a Promigence sandbox, so its shell and file-editor tools run there with output streamed back as it is written. - [Run Vercel AI SDK agents in a Promigence sandbox](https://www.promigence.ai/docs/guides/vercel-ai-sdk) Pass a Promigence sandbox to the Vercel AI SDK as experimental_sandbox, or to bash-tool, so an agent's commands and files live there. - [Snapshot after npm install, then fork 10 copies](https://www.promigence.ai/docs/guides/snapshot-and-fork) Install dependencies once in a sandbox, take a snapshot of it while it runs, and start ten parallel attempts from that snapshot, in TypeScript, Python or the CLI. --- Page: https://www.promigence.ai/docs/guides/github-actions-runner # A GitHub Actions runner in two lines Move GitHub Actions jobs to Promigence sandboxes with one workflow line, on runners we host or ones you start with one command, and run GitLab CI jobs the same way with a tagged runner. Your workflow file stays almost the same. One line changes in it. The second step is turning CI on for the repository in the console, which puts its jobs on our hosted runners, or one command that starts runners from a machine of yours. The steps, caches and repository secrets stay where they are. ## Line one: the workflow ```yaml jobs: test: runs-on: promigence # was: ubuntu-latest steps: - uses: actions/checkout@v4 - uses: actions/setup-node@v4 with: node-version: 22 - run: npm ci && npm test ``` Sizes are picked in the label. `runs-on: promigence-small`, `promigence-medium` or `promigence-large` choose the size per job. A job that only says `promigence` gets the default size: medium on our hosted runners unless you set another for the repository in the console, and small with the command below unless you set `--tier`. Small has less memory than GitHub's `ubuntu-latest` on a private repository (2 vCPU and 4 GiB, where GitHub's has 2 CPUs and 8 GB), so a job that ran there belongs on `promigence-medium` (4 vCPU, 16 GiB): keep the default, or pass `--tier medium` to the command below. The runner image comes with git and Python plus a compiler toolchain, but no Node.js or other language runtime. A job that relied on a tool GitHub's own image preinstalls adds its setup step, such as `actions/setup-node` above, as it would on any self-hosted runner. ## Line two: turn CI on in the console Open **Runners** in the console and choose **Add a repository**, then pick the repository from a GitHub account you connected. Its jobs then run on runners we host, each in a fresh sandbox started for the job, and nothing has to keep running on your side. Up to 10 of the repository's jobs run at once unless you change it there, and each job is billed for the seconds it runs. ## Or run the runners yourself On any machine with the CLI and a GitHub token: ```bash export GH_TOKEN= promigence runners github --repo OWNER/REPO ``` The command picks up queued jobs with a matching `runs-on` label and runs each in its own sandbox, until you press Ctrl-C. Use `--org ORG` instead of `--repo` to take the jobs of every repository in an organization, and `--runner-group NAME` to place the runners in a group other than `Default`. ### The token The token is read from the environment: `GH_TOKEN`, then `GITHUB_TOKEN`, or the variable you name with `--token-env`. A fine-grained token needs Actions read and Administration write on the repository. With `--org` it needs Self-hosted runners write on the organization. A classic token needs `repo`, plus `admin:org` for an organization. GitHub Enterprise Server works too: pass its API address with `--github-api URL`. ### The command's first run builds the runner image Each size runs from a runner snapshot that is built the first time it is needed. The CLI asks before it builds one, because the build is billed per second at that size's rate while it runs, whether it succeeds or not ([quickstart](https://www.promigence.ai/docs/quickstart)), and every later job of that size reuses the snapshot with no further build charge. To do it ahead of time, run `--prepare`, which builds the snapshot for `--tier` and exits: ```bash promigence runners github --repo OWNER/REPO --tier medium --prepare ``` In a script where nobody can answer the prompt, `--yes` builds a missing runner snapshot without asking. ## Control the bill Hosted runners take the repository's machine size and how many of its jobs run at once from the console, and each job is billed for the seconds it runs. The command's flags set the limits: | Flag | What it controls | |---|---| | `--cap USD` | The most one job may cost (default: what its full timeout costs at its size) | | `--timeout DUR` | The longest a job may run (default: the longest sandbox your plan allows) | | `--max M` | How many sandboxes may run at once | | `--warm N` | Keep N runners waiting so a job starts the moment it is queued. They are billed while idle | | `--idle-timeout DUR` | Stop an on-demand runner that no job took | `--warm` is the one setting that costs money while nothing runs. Leave it at zero unless queue time matters more to you than idle time. On Ctrl-C the command waits for running jobs to finish. `--kill-on-exit` cancels them instead. ## GitLab CI GitLab works with runner tags instead of a `runs-on` line. For hosted runners, create a project runner in GitLab (Settings, CI/CD, Runners, New project runner) tagged `promigence`, add the project under Runners in the console and paste the runner's token there. It starts with `glrt-`, and it is not shown again once saved. Every job that says `tags: [promigence]` then runs on Promigence. For a runner of your own instead, create one in GitLab with the tags your jobs use, put its authentication token in `GITLAB_RUNNER_TOKEN`, then: ```bash export GITLAB_RUNNER_TOKEN= promigence runners gitlab ``` Jobs with those tags now run on Promigence, each in its own sandbox. A self-managed GitLab needs `--url https://gitlab.example.com`. `--executor docker` (the default) runs each job in a container, using the job's `image:` or `--default-image`. With `--executor shell` the job runs directly in the sandbox. Unless told otherwise, the command keeps one runner up, billed while idle; `--pool N` changes that. To start runners only when jobs are waiting, give it a GitLab token with `read_api`: ```bash promigence runners gitlab --api-token-env GITLAB_API_TOKEN ``` `--cap`, `--timeout`, `--max`, `--tier`, `--prepare`, `--yes` and `--kill-on-exit` work as they do for GitHub. Jobs on this runner can read the runner token. Use it only for projects whose CI code you trust. ## What changes for your jobs Not much. Each job gets a fresh sandbox, is billed for the seconds it runs and stops at its cap. Steps that call `actions/checkout`, set up a toolchain or restore a cache run as written. When a job fails, the log in GitHub or GitLab is where you read it, the same as before. ## Checklist Hosted: 1. Change `runs-on` to `promigence` (or a sized label). 2. Open Runners in the console, choose Add a repository and pick the repository. Running the runners yourself: 1. Change `runs-on` to `promigence` (or a sized label). 2. Export a token with the scopes above. 3. Run `promigence runners github --repo OWNER/REPO --prepare` once per size. 4. Start `promigence runners github --repo OWNER/REPO` and leave it running. 5. Decide on `--cap` and on `--warm`, which is billed while idle. --- Page: https://www.promigence.ai/docs/guides/mcp-execute-tool # Build an MCP server with an execute tool backed by a sandbox A complete MCP server in TypeScript and Python whose execute tool runs model-written code in a Promigence sandbox of its own per session, with no network, a spend cap and a timeout. ## The short answer Register one MCP tool, `execute`, that writes the model's code to a file inside a Promigence sandbox, runs it there and returns what happened. Give every MCP session a sandbox of its own, with no network, a spend cap and a timeout, and end the sandbox when the session ends. If you only want Claude Code or another MCP client to use sandboxes, you can skip the code: `promigence mcp` is a ready-made server. ## What you build The finished server offers a single tool. A model calls it with a program and a language, and gets back the exit code, the output streams and a flag that says whether output was cut. The rules it follows: - One sandbox per MCP session, started on the first call and reused after it, so files the code writes under `/work` are still there on the next call. - No network inside the sandbox. Model-written code cannot send your data anywhere or download anything. - A spend cap of $1 and a lifetime of 30 minutes on every sandbox, so a runaway loop has a ceiling. - A non-zero exit comes back as a normal result. The program ran and failed, and the model needs to read why. Only a timeout or a failure of the sandbox itself is reported as a tool error. - After a failure of the sandbox (its cap or timeout reached, no credit left), the server ends it and the next call starts a fresh one. Over stdio, the MCP client starts one server process per session, so one sandbox per process is one sandbox per session. Serving many users over HTTP is covered further down. ## Before you start You need a Promigence account. Sign up or sign in once with the CLI, and both SDKs read the key it stored; exporting `PROMIGENCE_API_KEY` works too. Claim the free credit before the first sandbox, or the first call stops with `credit_unclaimed`: ```bash npm i -g promigence promigence signup # or: promigence login, for an account you already have promigence credits claim ``` The TypeScript server needs Node.js 20 or newer. For Python, use 3.10 or newer, since the MCP package requires it. The code below was compiled and type-checked against `@promigence/sdk` 0.1.0-beta.7 with `@modelcontextprotocol/sdk` 1.32.1, and against `promigence` 0.1.0b7 with `mcp` 2.3.0. ## TypeScript Install the two SDKs and zod, which the MCP SDK uses for tool schemas: ```bash mkdir sandbox-execute && cd sandbox-execute npm init -y npm pkg set type=module npm install @promigence/sdk @modelcontextprotocol/sdk zod npm install -D typescript @types/node @types/express ``` A `tsconfig.json` that compiles `src/` to `build/`: ```json { "compilerOptions": { "target": "ES2022", "module": "NodeNext", "moduleResolution": "NodeNext", "outDir": "build", "rootDir": "src", "strict": true, "skipLibCheck": true, "types": ["node"] }, "include": ["src"] } ``` The tool lives in `src/execute.ts`. `createExecuteServer()` returns one session: an `McpServer` with the tool registered, and a `close` function that ends the session's sandbox. ```typescript import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; import { CommandExitError, CommandTimeoutError, PromigenceError, Sandbox } from "@promigence/sdk"; import { z } from "zod"; // How each language runs inside the sandbox. const RUNTIMES = { python: { ext: "py", run: "python3" }, javascript: { ext: "mjs", run: "node" }, bash: { ext: "sh", run: "bash" }, } as const; /** One MCP session: a server with the `execute` tool and a sandbox of its own. */ export function createExecuteServer(): { server: McpServer; close: () => Promise } { const server = new McpServer({ name: "sandbox-execute", version: "1.0.0" }); // Created on the first call and reused after it, so files the code writes // under /work are still there on the next call in this session. let sandbox: Promise | undefined; let cell = 0; const getSandbox = () => (sandbox ??= Sandbox.create({ allowInternetAccess: false, // the code gets no network at all spendCap: 1, // US dollars: the most this sandbox may spend timeoutMs: 30 * 60_000, // it ends on its own after 30 minutes })); // Forget the sandbox and end it; the next call starts a fresh one. const close = async () => { const current = sandbox; sandbox = undefined; await current?.then((s) => s.kill()).catch(() => undefined); }; server.registerTool( "execute", { title: "Execute code", description: "Run Python, JavaScript or a bash script in a remote, isolated sandbox with no network access, " + "and return its exit code along with stdout and stderr. The working directory is /work, and files written " + "there are kept for later calls in this session.", inputSchema: { code: z.string().min(1).describe("The program to run."), language: z.enum(["python", "javascript", "bash"]).default("python"), timeout_seconds: z.number().int().min(1).max(300).default(60) .describe("Stop the program if it runs longer than this."), }, outputSchema: { exit_code: z.number().int(), stdout: z.string(), stderr: z.string(), truncated: z.boolean(), }, annotations: { readOnlyHint: false, openWorldHint: false }, }, async ({ code, language, timeout_seconds }) => { const { ext, run } = RUNTIMES[language]; try { const sbx = await getSandbox(); const file = `/tmp/cell-${++cell}.${ext}`; await sbx.files.write(file, code); let result: { exitCode: number; stdout: string; stderr: string; truncated?: boolean }; try { result = await sbx.commands.run(`${run} ${file}`, { cwd: "/work", timeoutMs: timeout_seconds * 1000 }); } catch (e) { if (e instanceof CommandTimeoutError) { return { content: [{ type: "text", text: `Stopped after ${timeout_seconds} s, its timeout.` }], isError: true }; } if (!(e instanceof CommandExitError)) throw e; result = e; // a non-zero exit is an answer for the model, not a failure of the tool } const output = { exit_code: result.exitCode, stdout: result.stdout, stderr: result.stderr, truncated: result.truncated ?? false, }; return { content: [{ type: "text", text: JSON.stringify(output) }], structuredContent: output }; } catch (e) { // The sandbox could not run it: no credit, its cap or timeout reached, the sandbox gone. await close(); const text = e instanceof PromigenceError ? `${e.code}: ${e.message} ${e.fix}` : String(e); return { content: [{ type: "text", text }], isError: true }; } }, ); return { server, close }; } ``` `src/stdio.ts` serves one session over stdio and ends its sandbox when the client goes away: ```typescript import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"; import { createExecuteServer } from "./execute.js"; // Over stdio the client starts one process per session, so one server here is one session. const { server, close } = createExecuteServer(); // End the sandbox when the client disconnects or the process is stopped. async function shutdown(): Promise { await close(); process.exit(0); } process.stdin.on("end", shutdown); process.on("SIGINT", shutdown); process.on("SIGTERM", shutdown); await server.connect(new StdioServerTransport()); console.error("sandbox-execute: ready on stdio"); // stdout carries the protocol, so log to stderr ``` Compile it, then add it to Claude Code. Everything after `--` is the command that starts the server: ```bash npx tsc claude mcp add sandbox-execute -- node /absolute/path/to/sandbox-execute/build/stdio.js ``` Run `/mcp` inside a Claude Code session to check that `sandbox-execute` is connected with its one tool. ## Python The Python version uses the `MCPServer` class from the `mcp` package. Its lifespan holds the session's sandbox and ends it when the server stops, and a `ToolError` is how a tool tells the model that something went wrong. ```bash pip install mcp promigence ``` Save this as `server.py`: ```python import asyncio from collections.abc import AsyncIterator from contextlib import asynccontextmanager from dataclasses import dataclass, field from typing import Annotated, Literal from pydantic import BaseModel, Field from mcp.server import MCPServer from mcp.server.mcpserver import Context from mcp.server.mcpserver.exceptions import ToolError from promigence import AsyncSandbox, CommandExitError, CommandTimeoutError, PromigenceError # How each language runs inside the sandbox: file extension, command. RUNTIMES = {"python": ("py", "python3"), "javascript": ("mjs", "node"), "bash": ("sh", "bash")} class ExecuteResult(BaseModel): exit_code: int stdout: str stderr: str truncated: bool @dataclass class Session: """One sandbox per server process, created on the first call and reused after it.""" sandbox: AsyncSandbox | None = None cells: int = 0 lock: asyncio.Lock = field(default_factory=asyncio.Lock) async def get(self) -> AsyncSandbox: async with self.lock: if self.sandbox is None: self.sandbox = await AsyncSandbox.create( allow_internet_access=False, # the code gets no network at all spend_cap=1, # US dollars: the most this sandbox may spend timeout_ms=30 * 60_000, # it ends on its own after 30 minutes ) return self.sandbox async def drop(self) -> None: """Forget the sandbox and end it; the next call starts a fresh one.""" sandbox, self.sandbox = self.sandbox, None if sandbox is not None: try: await sandbox.kill() except PromigenceError: pass @asynccontextmanager async def lifespan(server: MCPServer) -> AsyncIterator[Session]: session = Session() try: yield session finally: await session.drop() # end the sandbox when the server stops mcp = MCPServer("sandbox-execute", lifespan=lifespan) @mcp.tool(title="Execute code") async def execute( code: Annotated[str, Field(min_length=1, description="The program to run.")], ctx: Context[Session], language: Literal["python", "javascript", "bash"] = "python", timeout_seconds: Annotated[int, Field(ge=1, le=300, description="Stop the program if it runs longer than this.")] = 60, ) -> ExecuteResult: """Run Python, JavaScript or a bash script in a remote, isolated sandbox with no network access, and return its exit code along with stdout and stderr. The working directory is /work, and files written there are kept for later calls in this session.""" session = ctx.request_context.lifespan_context ext, run = RUNTIMES[language] try: sandbox = await session.get() session.cells += 1 path = f"/tmp/cell-{session.cells}.{ext}" await sandbox.files.write(path, code) result = await sandbox.commands.run(f"{run} {path}", cwd="/work", timeout_ms=timeout_seconds * 1000) except CommandTimeoutError: raise ToolError(f"Stopped after {timeout_seconds} s, its timeout.") except CommandExitError as e: # A non-zero exit is an answer for the model, not a failure of the tool. return ExecuteResult(exit_code=e.exit_code, stdout=e.stdout, stderr=e.stderr, truncated=bool(e.result.truncated)) except PromigenceError as e: # The sandbox could not run it: no credit, its cap or timeout reached, the sandbox gone. await session.drop() raise ToolError(f"{e.code}: {e.message} {e.fix}") return ExecuteResult(exit_code=0, stdout=result.stdout, stderr=result.stderr, truncated=bool(result.truncated)) if __name__ == "__main__": mcp.run() ``` Order matters in the `except` clauses: a timeout is a kind of non-zero exit, and both are Promigence errors, so the most specific comes first. The success path can say `exit_code=0` because `commands.run` raises on any other exit. Claude Code starts it with the command after `--`. `uv run --with` builds a fresh environment with both packages, so the command works from any directory. If you added the TypeScript server above under the same name, run `claude mcp remove sandbox-execute` first: ```bash claude mcp add sandbox-execute -- uv run --with "mcp[cli]" --with promigence mcp run /absolute/path/to/server.py ``` `python server.py` starts the same server if both packages are installed where you run it. ## One sandbox per session over HTTP To offer the tool to the users of your product, serve it over Streamable HTTP. Each MCP session gets its own transport, its own server and so its own sandbox, and a session that ends takes its sandbox with it. This `src/http.ts` reuses `createExecuteServer()` from above: ```typescript import { randomUUID } from "node:crypto"; import type { Request, Response } from "express"; import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js"; import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js"; import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js"; import { createExecuteServer } from "./execute.js"; // Anyone who can call this endpoint can run code on your bill: require a token. const TOKEN = process.env.MCP_TOKEN; if (!TOKEN) throw new Error("Set MCP_TOKEN; clients send it as 'Authorization: Bearer '."); const app = createMcpExpressApp(); // binds 127.0.0.1, with DNS rebinding protection const sessions = new Map(); app.use((req, res, next) => { if (req.headers.authorization !== `Bearer ${TOKEN}`) { res.status(401).end(); return; } next(); }); app.post("/mcp", async (req, res) => { const id = req.header("mcp-session-id"); let transport = id ? sessions.get(id) : undefined; if (!transport) { if (id || !isInitializeRequest(req.body)) { res.status(400).json({ error: "Unknown session: send initialize first." }); return; } const { server, close } = createExecuteServer(); // this session's own sandbox const created = new StreamableHTTPServerTransport({ sessionIdGenerator: () => randomUUID(), onsessioninitialized: (sid) => { sessions.set(sid, created); }, }); created.onclose = () => { if (created.sessionId) sessions.delete(created.sessionId); void close(); // the session ended, so its sandbox ends too }; await server.connect(created); transport = created; } await transport.handleRequest(req, res, req.body); }); // GET opens a session's notification stream; DELETE ends the session and its sandbox. async function existingSession(req: Request, res: Response) { const transport = sessions.get(req.header("mcp-session-id") ?? ""); if (!transport) { res.status(404).end(); return; } await transport.handleRequest(req, res); } app.get("/mcp", existingSession); app.delete("/mcp", existingSession); app.listen(3000, () => console.error("sandbox-execute: http://127.0.0.1:3000/mcp")); ``` A shared token is the least you can do. A product with real users should put proper sign-in in front of the endpoint and give each user their own cap. A client that disappears without ending its session leaves a sandbox behind until its 30-minute timeout, and the $1 cap bounds what that costs. The stdio server also runs on the 2.x line of the MCP TypeScript SDK with two changes: import `McpServer` from `@modelcontextprotocol/server` and `StdioServerTransport` from `@modelcontextprotocol/server/stdio`, and wrap each schema in `z.object(...)`. It was compiled and started that way against `@modelcontextprotocol/server` 2.3.1. The HTTP example above is for the 1.x line only. ## Promigence already ships one The CLI includes an MCP server of its own. It gives an MCP client tools to create sandboxes and use them, with no code to write: ```bash claude mcp add promigence -- promigence mcp ``` On Windows, end the command with `-- cmd /c promigence mcp` instead. Its flags shape what the client may do: | Flag | What it does | |---|---| | `--read-only` | Offers only the tools that read; they still return what a sandbox holds | | `--root PATH` | Keeps the file tools to one directory of the sandbox; commands are not limited to it | | `--allow-tools A,B` | Offers only the tools you name | | `--cap USD` | The most each sandbox or batch it starts may spend | | `--keep` | Leaves the session's sandboxes running when the server stops; by default they are ended | Pick `promigence mcp` when a coding assistant on your machine should drive sandboxes for you. Write your own server when you want one narrow tool with your rules fixed in code, or when the tool is part of a product you serve to other people. ## Make it yours A few changes turn the example into something you can ship. Start from your own environment. Build a snapshot that already has your libraries, checked by a command that must exit 0, and pass its alias to `Sandbox.create`: ```bash promigence snapshot create --image python:3.12 --setup "pip install pandas" \ --verify "python3 -c 'import pandas'" --alias analysis --wait ``` Then `Sandbox.create("analysis", { ... })` starts every session from it. The build is billed per second while it runs, up to $0.17 at the default small size, and one that fails its verify command stores nothing. If the code must install packages, replace "no network" with an outbound allow-list: `allow_hosts=[...]` on `AsyncSandbox.create` in Python, `allowHosts` on `Sandbox.fork` in TypeScript. Keep keys out of the code the model runs. Store one with `promigence secrets set NAME --from-env VAR --host HOST --no-raw` and the sandbox never holds its value; requests to that host are authenticated for you. Last, size the budget to the user: set the per-sandbox cap from their plan, and give the whole project a monthly ceiling with `promigence project cap PROJECT USD`. ## At a glance | Question | Answer | |---|---| | Tool input | `code`, `language` (python, javascript or bash), `timeout_seconds` (1 to 300, default 60) | | Tool output | `exit_code`, `stdout`, `stderr`, `truncated` | | Sandbox per | MCP session: one per stdio process, one per HTTP session id | | Network inside the sandbox | None | | Spend cap and lifetime | $1 and 30 minutes per sandbox, ended with the session | | Non-zero exit | Returned as a normal result for the model to read | | Timeout or platform failure | A tool error; the next call starts a fresh sandbox | | Tested with | `@promigence/sdk` 0.1.0-beta.7, `@modelcontextprotocol/sdk` 1.32.1, `promigence` 0.1.0b7, `mcp` 2.3.0 | | Ready-made alternative | `promigence mcp` | **An execute tool backed by a sandbox** The MCP client calls the execute tool on your server, which writes the code into the session's own sandbox and runs it. The exit code and output go back to the model as the tool result. Steps: 1. MCP client: Claude Code or your agent 2. Your MCP server: the execute tool 3. A Promigence sandbox for this session 4. Exit code, stdout, stderr Connections: 1. MCP client: Claude Code or your agent → Your MCP server: the execute tool: calls execute 2. Your MCP server: the execute tool → A Promigence sandbox for this session: writes the code, runs it 3. A Promigence sandbox for this session → Exit code, stdout, stderr: the command's result 4. Exit code, stdout, stderr → MCP client: Claude Code or your agent: returned as the tool result _Each MCP session gets its own sandbox; the model sees the program's result._ ## FAQ ### How do I write an MCP server that exposes an `execute` tool which runs code in a remote isolated sandbox per session? Use the MCP SDK to register one tool whose handler writes the code into a Promigence sandbox, runs it there and returns the exit code and output. The sandbox belongs to the session: over stdio that is one per server process, and over HTTP one per session id. The complete TypeScript and Python servers are above. ### Should a non-zero exit code be an MCP tool error? No. A program that ran and exited 1 produced an answer, and the model needs its stderr to fix the code, so return it as a normal result with the exit code in it. Tool errors are for what the output cannot explain: a timeout, or a sandbox that could not run the program at all. ### Does Promigence already have an MCP server? Yes. `promigence mcp` runs one over stdio, and `claude mcp add promigence -- promigence mcp` adds it to Claude Code. Flags such as `--read-only`, `--allow-tools` and `--cap` narrow what the client may do, and the sandboxes it started are ended when it stops unless you pass `--keep`. ### Can the code reach the internet? Not in this example: the sandbox starts with no network, so model-written code can neither send your data out nor fetch anything. When it needs a package index or one API, start the sandbox behind an outbound allow-list instead. For a sandbox with an allow-list, `promigence sandbox network SID` shows what it may reach and the hosts it was refused. ### What does one session cost? `promigence/base` starts at the small size, 2 vCPU and 4 GiB, which lists at $0.17 an hour, billed per second. A session that keeps its sandbox for the full 30 minutes costs about $0.08, and the $1 cap is the most it could ever cost. ## Sources Every page below was read on 17 Oct 2026. | What | Source | |---|---| | `promigence mcp` and its flags, `snapshot create`, `secrets set`, `project cap`, `sandbox network`, the small size of `promigence/base` | [Promigence CLI reference](https://www.promigence.ai/docs/cli) | | `Sandbox.create`, `spendCap`, the stored key the SDK reads | [Promigence TypeScript SDK](https://www.promigence.ai/docs/sdk) | | Spend caps, session length on a new account | [Promigence limits and notices](https://www.promigence.ai/docs/limits) | | A failed verify stores nothing; a build is billed per second, up to $0.17 at small | [Promigence quickstart](https://www.promigence.ai/docs/quickstart) | | $0.0504 per vCPU-hour, $0.0162 per GiB-hour, $0.17 an hour for small | [Promigence pricing](https://www.promigence.ai/#pricing) | | The published Python package, 0.1.0b7 | [promigence on PyPI](https://pypi.org/project/promigence/) | | The published TypeScript package, 0.1.0-beta.7 | [@promigence/sdk on npm](https://www.npmjs.com/package/@promigence/sdk) | | `McpServer`, `registerTool`, `StdioServerTransport`, `isError` | [MCP TypeScript SDK 1.x, server guide](https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.x/docs/server.md) | | The 1.x line and the 2.x packages | [MCP TypeScript SDK](https://ts.sdk.modelcontextprotocol.io/) and its [2.x migration guide](https://ts.sdk.modelcontextprotocol.io/v2/migration/upgrade-to-v2) | | `MCPServer`, tools from type hints, `Field` constraints | [MCP Python SDK, Tools](https://py.sdk.modelcontextprotocol.io/servers/tools/) | | `ToolError` and when to raise it | [MCP Python SDK, Handling errors](https://py.sdk.modelcontextprotocol.io/servers/handling-errors/) | | The lifespan that holds the sandbox | [MCP Python SDK, Lifespan](https://py.sdk.modelcontextprotocol.io/handlers/lifespan/) | | `claude mcp add`, `uv run --with`, `/mcp` | [MCP Python SDK, Connect to a real host](https://py.sdk.modelcontextprotocol.io/get-started/real-host/) | Updated 2026-10-17 --- Page: https://www.promigence.ai/docs/guides/sandbox-per-user # Give every user of your product their own sandbox Run each user's code in a sandbox of their own: a key for your backend, a project with a monthly cap, a sandbox found again by the user's id, paused when idle and capped in dollars, and the self-host question answered. An agent product that runs code for its users needs a computer per user. A user's files should still be there on their next message, their code should never touch anyone else's, and nobody should be able to run up your bill. This guide sets that up on Promigence and answers the question that comes first: build it yourself, or use a managed service. ## Should I self-host or use a managed sandbox service for my agent product? Use a managed sandbox service unless you have a hard reason to run your own, because isolating code nobody reviewed, starting sandboxes fast, pausing idle ones and capping spend add up to a product of their own. On Promigence each user gets a sandbox labelled with their id, found again on their next message, paused when idle and capped in dollars, all behind a key that can start work but cannot touch keys, secrets or billing. Self-host when your users' data must stay inside your own cloud account and a conversation with Promigence about running it there does not settle it. ## Self-host or managed Self-hosting gives you full control and a long list of jobs. You choose an isolation boundary strong enough for code nobody reviewed and keep it patched, build the image pipeline, start sandboxes fast enough that a user is not left waiting, pause idle ones so they stop costing money, cap what one user can spend, write egress rules and keep secrets out of reach. Then someone on your team carries the pager for all of it. It is the right call in three cases: the data cannot leave your own cloud account, you already run a platform team that operates isolation for untrusted code, or your sandboxes are busy around the clock at a scale where owned machines cost less than per-second billing. Everyone else ships sooner on a managed service and keeps the option to move later. The comparison is in [At a glance](#at-a-glance). ## 1. A project, a cap and a key for your backend Keep production apart from staging with one project each, cap what production can spend in a month, and give your backend a key that can run sandboxes and cannot touch keys, secrets or billing: ```bash promigence project create myapp-prod promigence project cap myapp-prod 1000 promigence keys create --project myapp-prod --name backend --access run --expires 90d ``` Store the key your backend gets as `PROMIGENCE_API_KEY`. A project that reaches its monthly cap refuses new work, and each sandbox's own spend cap bounds what is already running. ## 2. The environment users start from Every user's sandbox starts as a fresh copy of one snapshot. Put in it what your users' code needs, and a verify command that proves it imports: ```bash promigence snapshot create --image python:3.12 \ --setup "pip install pandas matplotlib" \ --verify "python -c 'import pandas, matplotlib'" \ --alias user-env --wait --wait-timeout 10m ``` Nothing is stored if the verify command fails. The build is billed per second while it runs, whether it verifies or not, up to $0.17 at the default small size ([quickstart](https://www.promigence.ai/docs/quickstart)), and every user's sandbox then starts from this snapshot with no further build charge. ## 3. One sandbox per user, found again on the next message Label each sandbox with the user's id when you create it. When the user writes again, list by that label and reuse what you find; a paused sandbox comes back as it was. The idle rule pauses a sandbox after five minutes with no request, and paused time is not billed. In TypeScript, run as an ES module: ```typescript import { PromigenceClient, Sandbox } from "@promigence/sdk"; const client = new PromigenceClient(); // PROMIGENCE_API_KEY: the backend key from step 1 const opening = new Map>(); async function openSandbox(userId: string): Promise { const [found] = await Sandbox.list({ client, labels: { user: userId }, state: ["ready", "running", "paused"], limit: 1 }); if (found) { const sbx = await Sandbox.connect(found.sandbox_id, { client }); if (found.state === "paused") await sbx.resume(); return sbx; } const [sbx] = await Sandbox.fork("user-env", { client, count: 1, spendCap: 2, timeoutMs: 60 * 60_000, metadata: { user: userId }, allowHosts: ["pypi.org", "files.pythonhosted.org"], }); if (!sbx) throw new Error("no sandbox was started"); await sbx.setAutoPause(300); return sbx; } // One lookup per user at a time, so two quick messages never start two sandboxes. export function sandboxFor(userId: string): Promise { let p = opening.get(userId); if (!p) { p = openSandbox(userId).finally(() => opening.delete(userId)); opening.set(userId, p); } return p; } // The tool your agent calls: run the model's code in this user's sandbox, return what it printed. export async function runCode(userId: string, code: string): Promise { const sbx = await sandboxFor(userId); await sbx.files.write("/tmp/main.py", code); const r = await sbx.commands.run("python3 /tmp/main.py", { timeoutMs: 60_000, throwOnExit: false }); return r.exitCode === 0 ? r.stdout : r.stdout + r.stderr; } ``` The same in Python, for a threaded backend: ```python import threading from typing import Dict from promigence import Promigence, Sandbox client = Promigence() # PROMIGENCE_API_KEY: the backend key from step 1 locks: Dict[str, threading.Lock] = {} locks_guard = threading.Lock() def sandbox_for(user_id: str) -> Sandbox: with locks_guard: lock = locks.setdefault(user_id, threading.Lock()) with lock: # one lookup per user at a time found = Sandbox.list(client=client, labels={"user": user_id}, state=["ready", "running", "paused"], limit=1) if found: sbx = Sandbox.connect(found[0]["sandbox_id"], client=client) if found[0].get("state") == "paused": sbx.resume() return sbx sbx = Sandbox.create( "user-env", client=client, spend_cap=2, timeout_ms=60 * 60_000, metadata={"user": user_id}, allow_hosts=["pypi.org", "files.pythonhosted.org"], ) sbx.set_auto_pause(300) return sbx def run_code(user_id: str, code: str) -> str: sbx = sandbox_for(user_id) sbx.files.write("/tmp/main.py", code) result = sbx.commands.run("python3 /tmp/main.py", timeout_ms=60_000, throw_on_exit=False) return result.stdout if result.exit_code == 0 else result.stdout + result.stderr ``` Three limits stack, and each stops a different kind of runaway. A command's `timeoutMs` ends one script that never finishes. The sandbox's `spendCap` holds what one user's sandbox may spend; a sandbox that reaches it is paused with its files kept, and resumes only under a higher cap. The project's monthly cap holds everything the backend starts. The `timeoutMs` on the sandbox counts running time only, since time spent paused does not count, so a sandbox that sleeps between messages lasts for many sessions. Extend an active one with `setTimeout` (`set_timeout` in Python). `allowHosts` puts the sandbox behind an outbound allow-list: here, the Python package index, so a user can still install a package. Refused connections are recorded, and `promigence sandbox network SID` lists them. ## 4. Keep your own keys out of users' sandboxes If code in a user's sandbox calls a model API on your account, do not hand it your key. Store the key once and bind it to the API's host; its value then stays out of the sandbox, and `--no-raw` makes sure it is never given to one: ```bash promigence secrets set OPENAI_KEY --from-env OPENAI_API_KEY --host api.openai.com --no-raw ``` Give it to a user's sandbox by name, with `secrets: ["OPENAI_KEY"]` on `Sandbox.fork` in TypeScript or `secrets=["OPENAI_KEY"]` on `Sandbox.create` in Python, and have the code send its requests to the address `secrets set` prints for the host: those requests are authenticated for you. A stored secret is never written into a snapshot you build. ## 5. Clean up When a user deletes their account, end their sandbox with `kill()` (or `promigence sandbox kill SID`). A paused sandbox is kept for 30 days, and resuming it starts the 30 days again; one that reaches 30 days is deleted with its files, and the organization's owner gets an email 7 days and 1 day before. Keep anything that must last longer in your own storage. `promigence project list` shows what each project spent this month. A paused sandbox does not count against your plan's concurrency limit, so the idle rule decides how many users fit: 20 sandboxes at once on a new account, up to 100 on Pro, and up to 500 or 1,000 on Max. ## At a glance | | Self-host | Managed, on Promigence | |---|---|---| | Isolation for code nobody reviewed | You choose the boundary, harden it and keep it patched | No sandbox can see, reach or address another, yours or anyone else's | | A sandbox per user | You build the pools and the scheduling | `Sandbox.fork` or `Sandbox.create` per user, found again by label | | Idle users | Machines cost money unless you build pausing | An idle rule pauses a sandbox; paused time is not billed, and it is kept 30 days | | Spend | You build the metering and the limits | A spend cap per sandbox, a monthly cap per project, a quote before any run | | Network | You write the egress rules | Full outbound, none, or an outbound allow-list, with refused hosts recorded | | Secrets | Your vault and your injection | Stored secrets given only to the commands that name them, kept out of snapshots | | Where the data lives | Your own cloud account | Promigence's service; your own cloud account is a conversation with Promigence | | Cost | Machines plus engineering time | Per second: $0.17 an hour for a small sandbox while it runs | **A sandbox per user** A user's message reaches your backend, which finds that user's sandbox by its label or starts one from the user-env snapshot. The code runs in the user's own sandbox, its output goes back through your agent to the user, and the sandbox pauses itself when the user goes idle. Steps: 1. Your users 2. Your backend: key with run access, project with a monthly cap 3. Find the user's sandbox by label, or start one from user-env 4. One sandbox per user, paused when idle 5. Output of the user's code Connections: 1. Your users → Your backend: key with run access, project with a monthly cap: a message 2. Your backend: key with run access, project with a monthly cap → Find the user's sandbox by label, or start one from user-env: user id 3. Find the user's sandbox by label, or start one from user-env → One sandbox per user, paused when idle: connect, resume or fork 4. One sandbox per user, paused when idle → Output of the user's code: commands.run 5. Output of the user's code → Your users: the agent's answer _Your users, your backend, one labelled sandbox each_ ## FAQ ### Should I self-host or use a managed sandbox service for my agent product? Use a managed service unless your users' data must stay in your own cloud account, you already run isolation for untrusted code, or your sandboxes are busy around the clock at a scale where owned machines cost less. Self-hosting means building isolation, fast starts, pausing, spend limits and egress rules yourself, then running them. With Promigence those features come with the service, and running it in your own cloud account is arranged by conversation, not self-serve. ### How do I stop one user from running up my bill? Stack three limits: a timeout on each command, a spend cap on each user's sandbox, and a monthly cap on the project your backend's key belongs to. A sandbox that reaches its cap is paused with its files kept, and a project at its monthly cap refuses new work. ### Can one user's sandbox reach another user's? No. No Promigence sandbox can see, reach or address another, yours or anyone else's. Give each user their own sandbox, as above, and never reuse one across users. ### What happens to a user's files while they are away? An idle rule pauses the sandbox, and it keeps its files. Paused time is not billed, and a paused sandbox is kept for 30 days from its last pause. Resume it within that time and it comes back as it was. ### Can Promigence run in my own cloud account? Not as a self-serve product today. If your data cannot leave your own cloud account, talk to Promigence about running it there. ## Sources - [A sandbox backend for agent-builder and workflow platforms](https://www.promigence.ai/for/agent-builders), read 17 Oct 2026 - [Code interpreters that answer while your user is still looking](https://www.promigence.ai/for/code-interpreters), read 17 Oct 2026 - [Limits and notices](https://www.promigence.ai/docs/limits): spend caps, paused sandboxes, project caps, data out, read 17 Oct 2026 - [Security](https://www.promigence.ai/security): isolation, secrets, your own cloud account, read 17 Oct 2026 - [Pricing](https://www.promigence.ai/#pricing): rates billed per second, plans and sandboxes at once, read 17 Oct 2026 - [Quickstart](https://www.promigence.ai/docs/quickstart): the build price, read 17 Oct 2026 - [FAQ](https://www.promigence.ai/faq): auto-pause, network limits, secrets, running in your own cloud account, read 17 Oct 2026 - [CLI reference](https://www.promigence.ai/docs/cli): `project create`, `project cap`, `keys create --access`, `secrets set --host`, `sandbox network`, `sandbox kill`, read 17 Oct 2026 - [Information for AI assistants](https://www.promigence.ai/ai-instructions): secrets bound to a host, projects with a spend cap each, read 17 Oct 2026 - [TypeScript SDK](https://www.promigence.ai/docs/sdk), and [@promigence/sdk on npm](https://www.npmjs.com/package/@promigence/sdk), version 0.1.0-beta.7, read 17 Oct 2026 - [promigence on PyPI](https://pypi.org/project/promigence/): the Python SDK, version 0.1.0b7, read 17 Oct 2026 Updated 2026-10-17. --- Page: https://www.promigence.ai/docs/guides/ai-pentest-fresh-target # Run AI security-testing agents against a fresh copy of your own application Build your application into a Promigence snapshot once, then give your security-testing agent a fresh copy of it for every run, behind an outbound allow-list that names only your model API, with the model key kept out and a spend cap on the run. ## How do I run an AI pentest agent safely against a copy of my app? Build your application once as a Promigence snapshot from its Dockerfile, with the app started at build time and a health check that has to pass before anything is stored. For each test run, fork a fresh sandbox from that snapshot and run your security-testing agent inside it, beside the copy, so it tests the app on localhost. Start the sandbox behind an outbound allow-list that names only your model API, give it the model key as a secret bound to that host so the value never enters the sandbox, and set a spend cap and a timeout. When the agent is done, copy its report and logs out and delete the sandbox. The next run forks the same snapshot and meets the same application in the same state. ## Authorization Test only systems you own or have written permission to test. Here that system is a copy of your own application, inside a sandbox you started. Do not point the agent at production, at a third party, or at anything else. Promigence's Acceptable Use Policy draws the same line. It permits security testing inside your sandboxes when the targets are systems you own, systems you have written authorization to test, or deliberately vulnerable test environments, and when network access for that workload is restricted to those targets. It prohibits scanning, probing or attacking any system you do not own or are not explicitly authorized to test. What an agent does counts as done by you, even when it acted without your instruction. Testing the Promigence platform itself falls under the Vulnerability Disclosure Policy, which this guide does not cover. Keep the permission with the results. The run script below records its reference as a run label, `authorization=AUTH-142`, which comes back with the run, and `promigence sandbox list --label authorization=AUTH-142` finds every sandbox whose run carries it. ## What runs where One sandbox holds one test run. Inside it are the copy of your application, already running on test data, and your agent, which reaches the app at `http://127.0.0.1:8080` (use your app's own port). The sandbox's outbound allow-list names a single host, your model API. Other hosts it asks for are refused, and `promigence sandbox network` lists each one. No sandbox can see, reach or address another, so twenty runs at once are twenty separate copies. Give the agent nothing outside the sandbox worth reaching. The copy holds test data and no production credentials, and the one key the agent uses is bound to the model API. ## Before you start You need a Promigence account and the CLI. Sign up once: the CLI stores your key, and the SDKs read it too. Claim the free credit before anything else, because until it is claimed a first run stops with `credit_unclaimed`. ```bash npm i -g promigence promigence signup # or: promigence login, for an account you already have promigence credits claim ``` The run script in step 4 also uses `jq`. ## 1. Build the copy once ### From a Dockerfile Most applications already have a Dockerfile. Use it to build the snapshot, start the app at build time, and make the verify command wait until the app answers: ```bash promigence snapshot create --dockerfile ./Dockerfile --tier medium \ --start "cd /app && ./start.sh > /tmp/app.log 2>&1" \ --verify "timeout 120 sh -c 'until curl -fsS http://127.0.0.1:8080/health; do sleep 2; done'" \ --alias app-under-test --wait --wait-timeout 15m ``` The build context is the Dockerfile's directory unless `--context` names another directory, or a git URL pinned to a full commit SHA. `--start` takes your app's start command, the one your Dockerfile's `CMD` runs, here with its output sent to `/tmp/app.log`. It is started at build time and is already running in every sandbox made from the snapshot. `--verify` has to exit 0 or nothing is stored. Either way, the build is billed per second for the time it runs. This check waits up to two minutes for the app's health route, so a copy that cannot start never becomes a snapshot. It needs `curl` in the image; without it, call your own check script. `--tier medium` gives every sandbox started from the snapshot 4 vCPU and 16 GiB, room for the app and the agent side by side. A build that outlasts `--wait-timeout` keeps going, and `promigence snapshot status BUILD_ID --wait` picks it up again. Put the agent in the same image, under `/opt/tester` for example, with everything it needs already installed. During a run the allow-list names only the model API, so a download from anywhere else is refused. The app and the agent are then pinned together, and every run tests the same app with the same agent. Seed the image with test data only: test accounts, fixtures, a local database. Leave production credentials and customer data out of the image and out of the build context, since the agent will read and change whatever the copy holds. ### From a snapshot of a build Without a Dockerfile, build the snapshot from your repository at a pinned commit with setup steps, as the AI pentest agents page does: ```bash promigence snapshot create --image debian:12 --tier medium \ --setup "apt-get update && apt-get install -y git curl" \ --setup "git clone https://github.com/your-org/your-app /work/app && git -C /work/app checkout <40-char sha>" \ --setup "cd /work/app && ./provision.sh" \ --verify "cd /work/app && ./healthcheck.sh" \ --alias app-under-test --wait --wait-timeout 15m ``` `provision.sh` is your own script. It installs and builds the app, loads test data, installs your agent, and starts the server in the background with its output in `/tmp/app.log`, so the step can finish while the app keeps running. `healthcheck.sh` exits 0 once the app answers. Pin the commit by its full SHA: a snapshot built from a moving ref is not reproducible. A private repository builds through the GitHub connection instead (`promigence github connect`, then `promigence snapshot create --repo your-org/your-app`); the CLI reference has the details. Either way, `app-under-test` now names a verified copy of your application at one version, and building again from identical inputs reuses that snapshot. ## 2. Store the model key, bound to its host Your agent needs a model API key, and nothing running in the sandbox should be able to read it. Store it once and bind it to the model API's host: ```bash export ANTHROPIC_API_KEY=... # already set in most setups promigence secrets set ANTHROPIC_API_KEY --from-env ANTHROPIC_API_KEY \ --host api.anthropic.com --no-raw ``` The value comes from the environment, never from the command line. With `--host`, requests a sandbox sends to the address this command prints are authenticated for you, and the value stays out of the sandbox. `--no-raw` makes that permanent: no run can ask for the value itself. A sandbox given the secret also has `ANTHROPIC_BASE_URL` pointed at that address, so an agent built on Anthropic's SDK works as it is, and a key bound to `api.openai.com` gets `OPENAI_BASE_URL` the same way. A request sent straight to `https://api.anthropic.com` is not authenticated, so an agent with a base URL of its own should use the printed address. That key is the only secret a run needs. A snapshot of a sandbox that was given a secret is refused unless you force it. Leave it refused. ## 3. Price it and cap it ```bash promigence run quote --snapshot app-under-test --count 1 --timeout 1h ``` A quote is the most a run can cost: every sandbox running for its whole timeout. At medium, an hour lists at $0.46, billed per second for what actually runs. The `--cap` in the script below is a hard limit. A run quoted above it is refused before anything starts, and a sandbox that reaches it while running is paused with its files kept until you raise the cap or end it. An owner can also give the project a monthly ceiling with `promigence project cap PROJECT USD`. Tokens are billed by your model provider, separately. ## 4. Run the agent against a fresh copy This script is one complete test run. Save it as `security-test.sh`: ```bash #!/bin/bash # One security-test run against a fresh copy of your app; needs promigence and jq set -euo pipefail SNAPSHOT=app-under-test OUT="runs/$(date -u +%Y%m%dT%H%M%SZ)" mkdir -p "$OUT" # The exact snapshot this run starts from, kept with the results promigence snapshot inspect "$SNAPSHOT" --json > "$OUT/snapshot.json" SNAP_ID=$(jq -r '.snapshot.snapshot_id' "$OUT/snapshot.json") # A fresh copy behind an allow-list that names only the model API, with a $1 cap and one hour SID=$(promigence fork --snapshot "$SNAP_ID" --count 1 --cap 1 --timeout 1h \ --allow api.anthropic.com --secret ANTHROPIC_API_KEY \ --label authorization=AUTH-142 --json | jq -r '.sandboxes[0].sandbox_id') # However the script ends, the sandbox is deleted with everything the run changed in it trap 'promigence sandbox kill "$SID" > /dev/null' EXIT # Your agent, pointed at the copy; a non-zero exit is recorded and the run carries on STATUS=0 promigence exec --sandbox "$SID" --stream --timeout 50m \ -- /opt/tester/run --target http://127.0.0.1:8080 --report-dir /work/report \ > "$OUT/agent.log" 2>&1 || STATUS=$? echo "agent exited $STATUS" | tee "$OUT/status.txt" # Every host the sandbox was refused, then the report and the app's log promigence sandbox network "$SID" --json > "$OUT/network.json" promigence files get /work/report "$OUT/report" --sandbox "$SID" --recursive promigence files get /tmp/app.log "$OUT/app.log" --sandbox "$SID" ``` `fork` waits until the copy is ready and prints its sandbox id. That copy is the app as the snapshot holds it: running, seeded with test data, and untouched by any earlier run. Forking by the snapshot id rather than the alias ties the results to the exact copy they came from. `--allow api.anthropic.com` is the whole allow-list, and `--secret ANTHROPIC_API_KEY` gives the sandbox the bound key. `/opt/tester/run` stands for however your agent starts: give it the copy's address and a directory for its report. `--timeout 50m` stops the agent after fifty minutes, which leaves the last ten of the sandbox's hour for collecting results, and `--stream` writes its output to the log as it is produced. If a run looks wrong while it is going, `promigence sandbox network SID --cut` cuts the sandbox's outbound access at once. It cannot be turned back on. To run the script from CI or on a schedule, give it a key that can start work and nothing more: `promigence keys create --name security-tests --access run` makes one that can run sandboxes and builds but cannot change secrets, keys or billing. ## 5. Read the results Each run leaves a folder under `runs/`. Start with `network.json`: its refused hosts are what the agent or the app asked for and did not get. A copy that tries to call a payment or email provider shows up there, and so does an agent that wandered. `report/` and `agent.log` are your agent's own output, `app.log` is the application's side of the same run, and `status.txt` holds the agent's exit code. `snapshot.json` names the snapshot the run started from. Keep it with the report, because it is how a finding gets re-run. ## 6. Throw it away, start the next one The `trap` line ends the sandbox when the script exits, whether the agent finished, failed or ran out of time. A killed sandbox stops billing, and whatever the run changed is discarded with it. The snapshot is untouched, so the next `./security-test.sh` starts from the same copy with nothing left over from the last attempt. None of your code, your agent's outputs or your test results is used for training. To run several attempts side by side, fork with `--count N`. Each sandbox is its own fresh copy, `promigence exec --run RUN_ID --all` runs the agent in every one of them, and `promigence run kill RUN_ID` ends them all. A new account runs 20 sandboxes at once. ## From TypeScript The same run with `@promigence/sdk` (`npm i @promigence/sdk`, Node.js 20 or newer). It type-checks against 0.1.0-beta.7: ```typescript import { mkdir, writeFile } from "node:fs/promises"; import { CommandExitError, PromigenceClient, Sandbox } from "@promigence/sdk"; const SNAPSHOT = "app-under-test"; const AGENT = "/opt/tester/run --target http://127.0.0.1:8080 --report-dir /work/report"; const out = `runs/${new Date().toISOString().replace(/[:.]/g, "-")}`; await mkdir(out, { recursive: true }); const client = new PromigenceClient(); // reads PROMIGENCE_API_KEY, or the key signup stored // The exact snapshot this run starts from, kept with the results const snapshot = await client.snapshots.get(SNAPSHOT); await writeFile(`${out}/snapshot.json`, JSON.stringify(snapshot, null, 2)); // A fresh copy behind an allow-list that names only the model API, with a $1 cap and one hour const [sandbox] = await Sandbox.fork(snapshot.snapshot_id, { client, count: 1, spendCap: 1, timeoutMs: 60 * 60_000, allowHosts: ["api.anthropic.com"], secrets: ["ANTHROPIC_API_KEY"], metadata: { authorization: "AUTH-142" }, }); try { // Your agent, pointed at the copy; a non-zero exit is recorded and the run carries on const agent = await sandbox.commands.run(AGENT, { background: true, timeoutMs: 50 * 60_000 }); let exitCode = 0; try { await agent.wait(); } catch (e) { if (!(e instanceof CommandExitError)) throw e; exitCode = e.exitCode; } await writeFile(`${out}/agent.log`, `${agent.stdout}${agent.stderr}\nexit ${exitCode}\n`); // Every host the sandbox was refused, then the report and the app's log const network = await client.sandboxes.network(sandbox.sandboxId); await writeFile(`${out}/network.json`, JSON.stringify(network, null, 2)); await writeFile(`${out}/report.tar`, await sandbox.files.downloadDir("/work/report")); await writeFile(`${out}/app.log`, await sandbox.files.read("/tmp/app.log")); } finally { await sandbox.kill(); // the copy and everything the run changed in it are gone } ``` `Sandbox.fork` takes the allow-list as `allowHosts`, the secrets by name and the cap in US dollars. The agent runs as a background command, and `wait()` returns when it ends, however long it takes. `files.downloadDir` hands back the report directory as one tar archive. ## From Python The same run with `promigence` (`pip install promigence`, Python 3.9 or newer). It type-checks against 0.1.0b7: ```python import json from datetime import datetime, timezone from pathlib import Path from promigence import CommandExitError, Promigence, Sandbox SNAPSHOT = "app-under-test" AGENT = "/opt/tester/run --target http://127.0.0.1:8080 --report-dir /work/report" out = Path("runs") / datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ") out.mkdir(parents=True) client = Promigence() # reads PROMIGENCE_API_KEY, or the key signup stored # The exact snapshot this run starts from, kept with the results snapshot = client.snapshots.get(SNAPSHOT) (out / "snapshot.json").write_text(json.dumps(snapshot, indent=2)) # A fresh copy behind an allow-list that names only the model API, with a $1 cap and one hour sandbox = Sandbox.create( snapshot["snapshot_id"], client=client, spend_cap=1, timeout_ms=60 * 60_000, allow_hosts=["api.anthropic.com"], secrets=["ANTHROPIC_API_KEY"], metadata={"authorization": "AUTH-142"}, ) try: # Your agent, pointed at the copy; a non-zero exit is recorded and the run carries on agent = sandbox.commands.run(AGENT, background=True, timeout_ms=50 * 60_000) try: exit_code = agent.wait().exit_code except CommandExitError as e: exit_code = e.exit_code (out / "agent.log").write_text(f"{agent.stdout}{agent.stderr}\nexit {exit_code}\n") # Every host the sandbox was refused, then the report and the app's log network = client.sandboxes.network(sandbox.sandbox_id) (out / "network.json").write_text(json.dumps(network, indent=2)) (out / "report.tar").write_bytes(sandbox.files.download_dir("/work/report")) (out / "app.log").write_text(sandbox.files.read("/tmp/app.log")) finally: sandbox.kill() # the copy and everything the run changed in it are gone ``` In Python the allow-list is `allow_hosts` on `Sandbox.create`, and `files.download_dir` returns the report directory as tar bytes. ## At a glance | Question | Answer | |---|---| | Where the copy comes from | A snapshot built once from your Dockerfile, or from setup steps at a pinned commit | | What each run starts from | A fresh sandbox forked from that snapshot, the app already running | | How the agent reaches the app | On localhost, inside the same sandbox | | Outbound network | An allow-list naming only the model API's host; refused hosts recorded; `--cut` ends outbound access for good | | Model key | Stored once, bound to the model API's host; `--no-raw` keeps the value out of every sandbox | | Other secrets | None: the copy runs on test data | | Spend | `run quote` first, then `--cap` on the run as a hard limit; a monthly project cap on top | | Time | `--timeout` on the sandbox, `exec --timeout` on the agent | | What you keep | The agent's report and log, the app's log, the refused hosts, the snapshot id | | After the run | `sandbox kill`: the sandbox and its changes are gone, the snapshot stays | | Re-running a finding | Fork the snapshot id the run recorded | | Key for automation | `keys create --access run`: starts work, cannot change secrets, keys or billing | | Checked against | The `promigence` CLI's command list, `@promigence/sdk` 0.1.0-beta.7, `promigence` 0.1.0b7 | **One security-test run against a fresh copy** Your application is built once as a snapshot. A run forks a fresh sandbox from it with the app already running, and your security-testing agent works inside that sandbox against the copy, behind an outbound allow-list that names only your model API. The report and logs are copied out, the sandbox is deleted, and the next run forks the same snapshot. Steps: 1. Snapshot of your app, built once 2. A fresh sandbox, the app already running 3. Your testing agent: the copy on localhost, an outbound allow-list naming only the model API 4. Report and logs, copied out 5. Sandbox deleted, the snapshot kept Connections: 1. Snapshot of your app, built once → A fresh sandbox, the app already running: fork, with a spend cap 2. A fresh sandbox, the app already running → Your testing agent: the copy on localhost, an outbound allow-list naming only the model API: the agent tests the copy 3. Your testing agent: the copy on localhost, an outbound allow-list naming only the model API → Report and logs, copied out: files get 4. Report and logs, copied out → Sandbox deleted, the snapshot kept: sandbox kill 5. Sandbox deleted, the snapshot kept → Snapshot of your app, built once: next run _Every run forks the same snapshot, and its sandbox is deleted at the end._ ## FAQ ### How do I safely run an AI pentest agent against a copy of my app? Snapshot the app once from its Dockerfile, with the app started at build time and a health check as the verify command. Then fork a fresh sandbox from it for every run, behind an outbound allow-list that names only your model API, with the model key stored as a secret bound to that host and a spend cap and timeout on the run. The agent works inside the sandbox against the copy on localhost; copy its report out and delete the sandbox when it is done. Test only systems you own or have written permission to test. ### Can the agent reach anything outside the sandbox? The sandbox runs behind an outbound allow-list, which in this guide names one host: your model API. Other hosts it asks for are refused, and `promigence sandbox network SID` lists every one of them, so read that list after each run. Sandboxes cannot see, reach or address one another. If something looks wrong mid-run, `promigence sandbox network SID --cut` cuts its outbound access for good. ### Does the agent ever see the model key? Not when the key is stored with `--host` and `--no-raw`. Requests the sandbox sends to the address `secrets set` printed are authenticated for you, and the value itself is never given to a sandbox. The run needs no other secret, because the copy runs on test data. ### How do I re-run a finding against exactly the same copy? Fork the snapshot id the run recorded in `snapshot.json` rather than the alias. A snapshot is named by a hash of its contents and kept until you delete it, so the copy a finding came from can be started again later, whatever the alias names by then. `promigence snapshot export SNAPSHOT_ID` writes a portable bundle that identifies it exactly, to attach to the finding, and `--snapshot` accepts that file in place of an id. The health check ran once, when the snapshot was built; `--verify-each`, which re-runs it in every copy, needs a snapshot built from a repository with `--repo` and `--verify`, so it does not apply to this Dockerfile build. ### What does a run cost? A medium sandbox lists at $0.46 an hour, billed per second, so a run that uses its whole hour costs about $0.46, and the $1 cap is the most it can ever cost. Building the snapshot is billed at the same medium rate for the time it runs, at most an hour, whether it verifies or not. Model tokens are billed by your model provider. Every plan starts with $50 of free credit. ## Sources Every page below was read on 17 Oct 2026. | What | Source | |---|---| | A fresh copy of the target per attempt, an outbound allow-list, refused hosts recorded, egress cut at once | [Promigence for AI pentest agents](https://www.promigence.ai/for/ai-pentest) | | `snapshot create` (`--dockerfile`, `--context`, `--start`, `--verify`, `--tier`, `--alias`), `snapshot status`, `fork` (`--allow`, `--secret`, `--cap`, `--label`), `exec`, `files get`, `sandbox network --cut`, `sandbox kill`, `sandbox list --label`, `secrets set --host --no-raw`, `snapshot export`, `run quote`, `project cap`, `keys create --access run` | [Promigence CLI reference](https://www.promigence.ai/docs/cli) | | A failed verify stores nothing, a build is billed per second for the time it runs, pin the commit, claim the free credit first | [Promigence quickstart](https://www.promigence.ai/docs/quickstart) | | Spend caps and the pause at the cap, 20 sandboxes at once on a new account | [Promigence limits and notices](https://www.promigence.ai/docs/limits) | | No sandbox can see, reach or address another; secrets kept out of snapshots; run changes discarded; no training on your code or results | [Promigence security](https://www.promigence.ai/security) | | A snapshot of a sandbox given a secret is refused unless forced | [Promigence FAQ](https://www.promigence.ai/faq) | | A snapshot named by a hash of its contents and kept until you delete it; a secret bound to its host stays out of the sandbox | [Information for AI assistants](https://www.promigence.ai/ai-instructions) | | Permitted security research, prohibited uses, responsibility for your agents | [Promigence Acceptable Use Policy](https://www.promigence.ai/legal/acceptable-use) | | Testing the platform itself | [Promigence Vulnerability Disclosure Policy](https://www.promigence.ai/legal/vulnerability-disclosure) | | Medium at 4 vCPU and 16 GiB for $0.46 an hour, per-second billing, $50 of free credit | [Promigence pricing](https://www.promigence.ai/#pricing) | | `PromigenceClient` reads the stored key | [Promigence TypeScript SDK](https://www.promigence.ai/docs/sdk) | | `Sandbox.fork` with `allowHosts`, `secrets` and `spendCap`, background commands, `files.downloadDir`, `ANTHROPIC_BASE_URL` for a key bound to `api.anthropic.com` | [@promigence/sdk on npm](https://www.npmjs.com/package/@promigence/sdk) | | `Sandbox.create` with `allow_hosts`, `secrets` and `spend_cap`, `files.download_dir`, the base-URL variables of a bound key | [promigence on PyPI](https://pypi.org/project/promigence/) | Updated 2026-10-17 --- Page: https://www.promigence.ai/docs/guides/claude-agent-sdk # Run Claude Agent SDK agents in a Promigence sandbox Keep the Claude Agent SDK loop in your process and run Claude Code itself inside a Promigence sandbox, with your Anthropic key stored as a secret. The Claude Agent SDK starts Claude Code as a child process and talks to it over stdin and stdout. Its `spawnClaudeCodeProcess` option lets you replace that spawn. The `promigence-claude-agent-sdk` package gives you a function for that option, so Claude Code runs inside a Promigence sandbox while your program keeps the loop, reads the messages and decides what happens next. Anything the agent edits, installs or deletes stays in the sandbox. ## What you need - A Promigence API key, exported as `PROMIGENCE_API_KEY`. - Node.js 20 or newer. - `@anthropic-ai/claude-agent-sdk` 0.3.276 or newer. The adapter was written and tested against 0.3.276. - An Anthropic API key, stored once as a Promigence secret (below). ## Install ```bash npm install promigence-claude-agent-sdk @anthropic-ai/claude-agent-sdk promigence export PROMIGENCE_API_KEY=prom_api_... promigence secrets set ANTHROPIC_API_KEY --from-env ANTHROPIC_API_KEY ``` `promigence secrets set` reads the value from your `ANTHROPIC_API_KEY` variable and stores it write-only. From then on your code only ever names the secret. The value goes into the agent's environment inside the sandbox; it is never put on a command line or written to a file there, and the package refuses a credential passed as a plain environment value. ## A minimal example The sandbox needs Claude Code installed. The built-in base snapshot has Node.js, so one `npm install` inside the sandbox is enough. You also have to tell the SDK where the executable lives inside the sandbox, because the path it would find on your own machine does not exist there. ```ts import { query } from "@anthropic-ai/claude-agent-sdk"; import { PromigenceClient, Sandbox } from "promigence"; import { spawnInPromigence } from "promigence-claude-agent-sdk"; const client = new PromigenceClient(); const sandbox = await Sandbox.create({ client, timeoutMs: 15 * 60_000, spendCap: 5 }); await sandbox.commands.run("command -v claude || npm install -g @anthropic-ai/claude-code"); try { for await (const message of query({ prompt: "Fix the failing test in src/parser.ts", options: { pathToClaudeCodeExecutable: "/usr/local/bin/claude", spawnClaudeCodeProcess: spawnInPromigence({ client, sandboxId: sandbox.sandboxId, cwd: "/workspace", secrets: ["ANTHROPIC_API_KEY"], onStderr: (text) => process.stderr.write(text), }), }, })) { if (message.type === "result") console.error(`[${message.subtype}]`); } } finally { await sandbox.kill(); } ``` If you would rather not install Claude Code yourself, `promigence agent start claude` prepares a sandbox with Claude Code in it, binds your stored `ANTHROPIC_API_KEY`, and prints the sandbox id to pass as `sandboxId`. `spawnInPromigence` takes a few more options. `executablePath` overrides where Claude Code is inside the sandbox. `env` adds plain settings. `envForward` controls which of the SDK's own environment travels: by default only `CLAUDE_*` and `ANTHROPIC_*` settings, and never anything shaped like a credential. Put a token you do want the agent to have in `secrets` after storing it with `promigence secrets set`. ## One sandbox per query You create the sandbox and you end it. The package attaches one Claude Code process to the sandbox you name; it does not create, copy or end sandboxes on its own. The usual shape is one sandbox per task: create it, run the query, kill it in a `finally` block as above. Running two agents in the same sandbox at once needs a different `envDir` and `stderrPath` for each, since both default to fixed paths. ## Setting a spend cap Pass `spendCap` (US dollars) to `Sandbox.create`, or set `PROMIGENCE_SPEND_CAP` in the environment. Without either, your organization's default cap applies. The cap is the most that sandbox may spend; Promigence stops it rather than let it go over. ## Cleaning up `await sandbox.kill()` ends the sandbox and its billing. Put it in `finally` so a thrown error or an interrupted loop does not leave one running. `timeoutMs` is a second guard: the sandbox ends on its own when that time is up. `promigence sandbox list` shows anything still running, and `promigence sandbox kill ` ends one by hand. ## What is not supported yet - Closing the agent's stdin does not end it. A query finishes when the SDK stops the agent after its own grace period. - There is no live stderr stream. `onStderr` receives the tail once the agent exits. - The SDK's local debug file and session store do not carry across to a remote agent. - If `pathToClaudeCodeExecutable` ends in `.js` or `.mjs`, set `executable: "node"` in the SDK options and leave `executablePath` unset. - Multi-line environment values lose trailing newlines. - TypeScript only. The Python Agent SDK has no equivalent spawn hook, so there is no Python version. ## Next Read [the agent briefing](https://www.promigence.ai/agents) for what a sandbox gives an agent, or start with [the quickstart](https://www.promigence.ai/docs/quickstart). --- Page: https://www.promigence.ai/docs/guides/claude-code-and-codex # Run Claude Code, Codex or OpenCode in a sandbox Start a coding agent in its own Promigence sandbox with one command, keep the model key off the command line, and drive sandboxes from Claude Code. A coding agent with shell access will install packages, rewrite files and run whatever its plan says. On your laptop that touches your real home directory and your real credentials. In a sandbox it touches a computer you can throw away. Promigence starts Claude Code, Codex or OpenCode in a new sandbox with one command. This guide covers that command, how the model key gets in without appearing on a command line, and the other direction: letting Claude Code on your machine start and use sandboxes through MCP. ## Before you start Install the CLI and sign in: ```bash npm i -g promigence promigence login promigence doctor ``` `doctor` checks the install, the key and the connection, and says how to fix whatever fails. ## Start an agent ```bash export ANTHROPIC_API_KEY=... # already set in most setups promigence agent start claude --key-from-env ANTHROPIC_API_KEY --cap 2 ``` Three agents are supported: `claude`, `codex` and `opencode`. The agent runs in a fresh sandbox started from `promigence/base`, and it is installed there if the snapshot does not already have it. `--key-from-env VAR` stores the key from that environment variable as a Promigence secret first, so the value never appears in your shell history or a process listing. After the first time, the stored secret is enough. By default the command looks for a secret called `ANTHROPIC_API_KEY` (`OPENAI_API_KEY` for `codex`). If yours has another name, pass `--key-secret NAME`; `--key-secret NAME=VAR` hands it to the agent under the variable `VAR`. For Codex: ```bash promigence agent start codex --key-from-env OPENAI_API_KEY --cap 2 ``` ## Work on a repository `--repo URL` clones a public repository and starts the agent inside it: ```bash promigence agent start claude \ --repo https://github.com/your-org/your-public-repo \ --cap 2 --timeout 2h ``` Private code works differently. Connect GitHub once with `promigence github connect`, build a snapshot of the repository with its dependencies installed and a check that must pass, then start the agent from that snapshot: ```bash promigence snapshot create --repo your-org/app --ref main \ --setup "npm ci && npm run build" --verify "npm test" \ --alias app --wait promigence agent start claude --snapshot app --cap 2 ``` Starting from a snapshot means the agent's first command runs in a tree that is already installed and built, and every agent you start from it begins in the same verified state. The build is billed per second while it runs, whether it verifies or not, up to $0.17 at the default small size ([quickstart](https://www.promigence.ai/docs/quickstart)), and agents started from the snapshot pay no further build charge. ## Interactive or headless There are two ways to work with the agent once it is up. Without extra flags, the command prints the command that opens the agent's terminal, so you can connect when you are ready; `--attach` opens it straight away. With `--prompt`, the agent works on a task on its own, in the background: ```bash promigence agent start claude --snapshot app \ --prompt "Fix the failing date-parsing test in src/time and explain the change in NOTES.md" \ --cap 3 --timeout 1h ``` While it works, `promigence sandbox info SID` shows the sandbox's state, its time left, its cost so far and the commands it ran. When it is done, copy the results out and end the sandbox: ```bash promigence files get /work/NOTES.md ./NOTES.md --sandbox SID promigence sandbox kill SID ``` ## Limits that keep an agent in bounds Every `agent start` takes a spend cap. `--cap` is in US dollars and is the most the sandbox may spend; without it the value of `PROMIGENCE_SPEND_CAP` applies, or your organization's default cap. `--timeout` sets how long the sandbox lives (one hour unless you say otherwise). An agent that loops forever stops at whichever limit it reaches first. Want to keep the result? `promigence sandbox snapshot SID --alias after-fix` saves the sandbox as a new snapshot, and later sandboxes start from that point. A sandbox that was given a secret is refused here unless you pass `--force`, because the snapshot could then contain the secret's value. The model key counts, so think twice before forcing it. ## The other direction: Claude Code drives sandboxes Run Claude Code on your own machine and give it sandboxes as a tool: ```bash claude mcp add promigence -- promigence mcp ``` On Windows, end it with `-- cmd /c promigence mcp`. Claude Code can then start sandboxes, run commands in them and read files and reports through the MCP server. A few flags shape what it may do: | Flag | Effect | |---|---| | `--cap USD` | The most each sandbox or batch it starts may spend | | `--read-only` | Offer only the tools that read: listings, files, output, reports | | `--allow-tools A,B` | Offer only the tools you name | | `--keep` | Leave the sandboxes the session started running when the server stops | Sandboxes the session started end when the server stops, unless you pass `--keep`. To put the flags on the server, add them after `promigence mcp`: ```bash claude mcp add promigence -- promigence mcp --cap 1 ``` ## Teach the agent the CLI For the agent itself, `promigence agent-guide` prints a short guide to the CLI. With `--install`, the same command writes it into `AGENTS.md` or `CLAUDE.md` and the agent rule folders it finds, so the next session already knows the commands. Run it with `--check` first to see what it would change. ## Checklist 1. Store the model key once with `--key-from-env`, never on a command line. 2. Build a snapshot of private repositories and start agents from it. 3. Set `--cap` and `--timeout` on every agent. 4. Read progress with `sandbox info`, copy results out with `files get`. 5. End the sandbox with `sandbox kill` when the work is out. --- Page: https://www.promigence.ai/docs/guides/google-adk # Run Google ADK agents in a Promigence sandbox Point a Google ADK agent's environment tools or code executor at a Promigence sandbox, so its commands and code run there. Google ADK runs an agent's work in two places: environment tools that execute commands and edit files, and a code executor that runs the code blocks a model writes. The `promigence-google-adk` package covers both. `PromigenceEnvironment` backs `EnvironmentToolset`, and `PromigenceCodeExecutor` backs `LlmAgent(code_executor=...)`. Either way the work happens in a Promigence sandbox instead of on the machine serving the agent. ## What you need - A Promigence API key in `PROMIGENCE_API_KEY`. - Python 3.10 or newer. - `google-adk` 2.9.1. `BaseEnvironment` is marked experimental upstream, so the package pins `>=2.9,<3`. ## Install ```bash pip install promigence-google-adk export PROMIGENCE_API_KEY=prom_api_... export PROMIGENCE_SPEND_CAP=5 ``` ## Environment tools ```python from google.adk.agents import LlmAgent from google.adk.tools.environment import EnvironmentToolset from promigence_google_adk import PromigenceEnvironment agent = LlmAgent( name="coder", model="gemini-2.5-pro", tools=[EnvironmentToolset(environment=PromigenceEnvironment(image="python:3.12-slim", spend_cap=1))], ) ``` The toolset hands the model Execute, ReadFile, EditFile and WriteFile tools, all acting on the sandbox. `EnvironmentToolset` initializes the environment before it hands out the tools and closes it when the toolset closes, so the sandbox lives exactly as long as the toolset. To manage it by hand, use `async with PromigenceEnvironment(...) as env:`. ## Code executor ```python from google.adk.agents import LlmAgent from promigence_google_adk import PromigenceCodeExecutor executor = PromigenceCodeExecutor(image="python:3.12-slim", spend_cap=1) agent = LlmAgent(name="analyst", model="gemini-2.5-pro", code_executor=executor) # ... run the agent ... executor.close() ``` Each code block is written to a file in the sandbox and run with `python3` (change it with `interpreter`). Input files from ADK are written into the working directory first. Both classes take the environment the same way: pass exactly one of `image` or `snapshot`. The first time you name an image, Promigence pins its tag to a digest, builds a snapshot from it and checks it, and later sandboxes reuse that snapshot: a saved, verified environment that each sandbox starts as a fresh copy of. That build is billed per second while it runs, whether it verifies or not, up to $0.17 at the default small size ([quickstart](https://www.promigence.ai/docs/quickstart)), and the sandboxes that reuse the snapshot pay no further build charge. Both also take `tier`, `working_dir`, `env_vars`, `allow_internet_access=False` and `registry_secret` for a private image. `user` and the snapshot inputs `setup`, `verify` and `start` belong to `PromigenceEnvironment` only; the code executor ignores them. Only the code executor takes `interpreter`. ## How sandboxes map to ADK An environment is one sandbox. The code executor is stateful, with one sandbox per ADK session: a session's blocks see each other's files and installed packages, and two sessions never share one. One app process can serve many users without one user's code seeing another's files. The executor keeps the sandbox id in session state, so a restarted process reconnects to the running sandbox instead of starting another. ## Setting a spend cap `spend_cap` is the most one sandbox may spend, in US dollars. It falls back to `PROMIGENCE_SPEND_CAP`, then to your organization's default; with none of them, the adapter raises a configuration error before anything starts. `sandbox_timeout_sec` (3600 by default) bounds each sandbox's lifetime. ## Cleaning up The toolset closes its environment for you. The code executor has no shutdown hook in ADK, so call `executor.close()` yourself or use it as a context manager. It ends every session's sandbox. Each one also ends on its own when `sandbox_timeout_sec` runs out. A command that exits non-zero comes back as an `ExecutionResult` with its exit code, the way ADK expects. A failure on the Promigence side raises `PromigenceAdapterError` with `failure_class == "env"`, so it never looks like the agent's command failed. ## What is not supported yet - Streaming output. A command's output arrives when it finishes. - `output_files` from the code executor. It is always empty; read generated files with `read_file`. - The code executor cannot tell a timeout from a kill. `PromigenceEnvironment.execute` can. - The image needs `/bin/sh`, plus the interpreter you name for the code executor. ## Next Read [the agent briefing](https://www.promigence.ai/agents) for what a sandbox gives an agent, or start with [the quickstart](https://www.promigence.ai/docs/quickstart). --- Page: https://www.promigence.ai/docs/guides/harbor # Run Harbor tasks in a Promigence sandbox Select Promigence in Harbor with one flag to run Terminal-Bench and other Harbor tasks in cloud sandboxes, each trial in its own copy. Harbor runs agent tasks such as Terminal-Bench. With the Promigence environment installed, every trial gets its own sandbox instead of a local container, so you can run many trials at once without Docker on the machine that drives them. No patch to Harbor is needed: you select the environment by its import path. ## What you need Bring a Promigence API key in `PROMIGENCE_API_KEY`, or sign in once with `promigence auth login`. You need Python 3.12 or newer. The adapter was written and tested against harbor 0.23.0 and pins `harbor>=0.23,<0.24`, because Harbor's environment interface is not a stable API yet. ## Install ```bash pip install promigence-harbor export PROMIGENCE_API_KEY=... export PROMIGENCE_SPEND_CAP=5 export HARBOR_TELEMETRY=0 # optional: Harbor sends usage telemetry unless you turn it off ``` Tasks that build from a Dockerfile also need `PROMIGENCE_REGISTRY` set to a registry you can push to. Those images are built on your machine with `docker buildx`, pushed there, and pulled by Promigence. Tasks that name a `docker_image` are pulled by Promigence directly. ## A minimal run ```bash harbor run -p path/to/dataset -a claude-code -m anthropic/claude-sonnet-4-5 \ -e promigence_harbor:PromigenceEnvironment \ --ek spend_cap=5 --ek sandbox_timeout_sec=3600 -n 32 ``` To try it without a model key, run a single task with Harbor's oracle agent, which executes the task's own `solution/solve.sh`: ```bash harbor run --path ./hello-task --agent oracle \ --env promigence_harbor:PromigenceEnvironment \ --ek spend_cap=1 --ek sandbox_timeout_sec=900 --n-concurrent 1 ``` The reward lands in `jobs///result.json` as usual. ## How trials map to sandboxes Each Harbor trial gets one sandbox. Trials of the same task share one snapshot: a snapshot is a saved, verified environment, and each sandbox starts as a fresh copy of it, so one trial never sees another trial's files. An image tag is pinned to its digest before the snapshot is made, which keeps reruns on the same bytes. That build is billed per second while it runs, whether it verifies or not, up to $0.17 at the default small size ([quickstart](https://www.promigence.ai/docs/quickstart)), and the trials that reuse the snapshot pay no further build charge. Pass environment options with `--ek key=value`. The ones you will reach for first: | option | what it does | |---|---| | `spend_cap` | dollar cap per sandbox run | | `sandbox_timeout_sec` | sandbox lifetime (default 3600) | | `tier` | `small`, `medium` or `large`; otherwise picked from the task's `cpus` and `memory_mb` | | `setup` | commands baked into the snapshot | | `verify` | the snapshot is kept only if this command exits 0 | | `registry`, `registry_secret` | where Dockerfile images go, and a stored secret for private pulls | Every `--ek` value ends up in the job's `config.json`, so the adapter refuses `--ek api_key=...`. Keep the key in the environment. A task with a `docker-compose.yaml` that defines exactly one service is read and run on the sandbox. Its image or build, environment, working directory, user, resources and TCP ports carry over. Compose files with two or more services are refused by name before anything starts. ## Telling environment failures from task failures Next to each trial's result you get `promigence-.json`. It records the sandbox id, the snapshot id, the image digest, whether the snapshot was verified, and any failures, each classed as `env` (the sandbox side failed), `env_definition` (the task's image could not be built or verified), `config` or `task`. Environment failures raise their own exception type, so Harbor's `exception_info` keeps them apart from an agent that got the task wrong. ## Spend cap Every sandbox run needs a cap. Set it with `--ek spend_cap=5`, with `PROMIGENCE_SPEND_CAP`, or rely on your organization's default. A run with no cap from any of those is refused. ## Cleaning up Harbor's `stop()` always ends the sandbox, so finished trials do not linger. To look inside a running one, `attach()` opens `promigence sandbox shell `, which needs the CLI (`npm i -g promigence`). ## What is not supported Compose tasks with more than one service are refused, and so are `--extra-docker-compose` overlays. Network allowlists, and changing network policy between the agent and verifier phases, are not supported; Harbor itself refuses those tasks during validation. There are no GPUs or Windows images. Images must be `linux/amd64` and contain `/bin/sh`, plus `tar` for directory transfers. Output is not live: Harbor's callbacks receive it when the command finishes. Next: read [the agent briefing](https://www.promigence.ai/agents), or start from [the quickstart](https://www.promigence.ai/docs/quickstart). --- Page: https://www.promigence.ai/docs/guides/inspect-evals # Run Inspect evals in a Promigence sandbox Use sandbox="promigence" in Inspect to give every sample its own cloud sandbox, with Docker-style tasks running unchanged. Inspect (`inspect_ai`) runs tool-using evals inside a sandbox per sample. The `inspect-promigence` package adds a provider named `promigence`, so each sample runs in a Promigence sandbox and many samples can run at once without a Docker daemon on your machine. Tasks written for `sandbox="docker"` with a Dockerfile or a single-service compose file also run unchanged. ## What you need You need a Promigence API key in `PROMIGENCE_API_KEY`, or a one-time `promigence auth login`, and Python 3.10 or newer. The provider was written and tested against inspect_ai 0.3.264 and requires at least that version. ## Install ```bash pip install inspect-promigence openai export PROMIGENCE_API_KEY=... export PROMIGENCE_SPEND_CAP=1 ``` Installing is the whole registration step. Inspect discovers the provider through its plugin entry point, so `sandbox="promigence"` works as soon as the package is present. If your task builds from a Dockerfile, also set `PROMIGENCE_REGISTRY` to a registry you can push to: the image is built on your machine with `docker buildx` and pushed there. ## A minimal eval ```python from inspect_ai import Task, task from inspect_ai.agent import react from inspect_ai.dataset import Sample from inspect_ai.scorer import includes from inspect_ai.tool import bash from inspect_promigence import PromigenceSandboxConfig SANDBOX = ( "promigence", PromigenceSandboxConfig( image="python:3.12-slim", verify="python3 -c 'import sys; assert sys.version_info >= (3, 12)'", sandbox_timeout_sec=600, ), ) @task def hello_bash_agent() -> Task: return Task( dataset=[Sample(input="Use bash to print the Python version, then answer with it.", target="3.12")], solver=react(tools=[bash(timeout=60)]), scorer=includes(), sandbox=SANDBOX, message_limit=12, ) ``` Save it as `hello_eval.py`. The model here is OpenAI's, so set `OPENAI_API_KEY` before you run it: ```bash inspect eval hello_eval.py@hello_bash_agent --model openai/gpt-4o-mini ``` Other accepted forms are `sandbox=("promigence", "compose.yaml")`, `sandbox=("promigence", "Dockerfile")` and plain `sandbox="promigence"`, which picks up a `compose.yaml`, `Dockerfile` or `promigence.yaml` next to the task. For an existing Docker task, try `inspect eval task.py --sandbox promigence`. ## How samples map to sandboxes At task start the image is pinned to its digest and turned into one snapshot. A snapshot is a saved, verified environment; each sample's sandbox starts as a fresh copy of it, so samples never share files. If `verify` fails, the snapshot is not stored and the task stops before any sample runs, which keeps a broken environment from being scored as a model failure. The build is billed per second while it runs, whether it verifies or not, up to $0.17 at the default small size ([quickstart](https://www.promigence.ai/docs/quickstart)), and samples and later runs reuse the snapshot with no further build charge. `PromigenceSandboxConfig` also takes `setup` (commands baked into the snapshot), `start` (a background process that is already running when a sample begins), `tier` or `cpus`/`memory_mb`, `allow_internet`, `working_dir`, `user`, `env`, `registry` and `registry_secret`. You can keep the same settings in a `promigence.yaml` file instead. The sandbox config goes into every `.eval` log that Inspect writes. Values under credential-looking `env` keys (names containing KEY, TOKEN, SECRET, PASSWORD, AUTH or CREDENTIAL) are written as a `${KEY}` reference or as ``, never in the clear. Each sample's transcript carries an info event from `promigence` with the sandbox id, snapshot id, image digest, whether the snapshot was verified, and any failures classed as `env`, `env_definition`, `config` or `task`. The same record is in the sample store, so it travels with the log. ## Spend cap Set `spend_cap` on the config, or `PROMIGENCE_SPEND_CAP` in the environment, or leave both unset to use your organization's default. The cap applies to each sample's sandbox. ## Cleaning up Each sandbox ends when its sample finishes. At task end the provider ends any that missed their cleanup; with `--no-sandbox-cleanup` it prints their ids instead, and `inspect sandbox cleanup promigence ` ends one later. To open a shell in a live sample, run `promigence sandbox shell ` with the CLI (`npm i -g promigence`). ## What is not supported - Compose files with more than one service. - Images without `/bin/sh` (distroless images cannot exec). - Incremental output: command output arrives when the command exits. - Images other than `linux/amd64`. - `timeout_retry`, which exists for Docker daemon hangs, is ignored. `write_file` writes as root. - `connection()` gives the CLI command only, with no port mappings or editor attach. Next: read [the agent briefing](https://www.promigence.ai/agents), or start from [the quickstart](https://www.promigence.ai/docs/quickstart). --- Page: https://www.promigence.ai/docs/guides/langchain # Run LangChain Deep Agents in a Promigence sandbox Use a Promigence sandbox as the backend for a LangChain Deep Agent, or as the sandbox provider for deepagents-code. LangChain Deep Agents run their shell and file tools through a sandbox backend. The `langchain-promigence` package gives you `PromigenceSandbox`, a backend you pass to `create_deep_agent`, so the agent's commands and file edits happen in a Promigence sandbox. Installing it also registers a `promigence` provider for `deepagents-code`, so `dcode` can use it with no extra wiring. ## What you need - A Promigence API key in `PROMIGENCE_API_KEY`. - Python 3.11 or newer (3.12 for the `deepagents-code` provider). - `deepagents` 0.7.15. The package pins `>=0.7.15,<0.8`. The `dcode` provider was tested with `deepagents-code` 0.1.71. ## Install ```bash pip install langchain-promigence pip install "langchain-promigence[code]" # adds the deepagents-code provider export PROMIGENCE_API_KEY=prom_api_... export PROMIGENCE_SPEND_CAP=5 ``` ## A minimal example ```python from deepagents import create_deep_agent from langchain_promigence import PromigenceSandbox sandbox = PromigenceSandbox.create(image="python:3.12-slim", working_dir="/workspace", spend_cap=1) try: agent = create_deep_agent(model="anthropic:claude-sonnet-4-5", backend=sandbox) agent.invoke({"messages": [{"role": "user", "content": "run the tests and fix what fails"}]}) finally: sandbox.kill() ``` From async code, use `acreate` and `akill`. The synchronous `create` refuses to run inside an event loop and says so: ```python sandbox = await PromigenceSandbox.acreate(image="python:3.12-slim", spend_cap=1) await agent.ainvoke(...) await sandbox.akill() ``` For `deepagents-code`, pick the provider on the command line and name the image in `PROMIGENCE_IMAGE`: ```bash dcode --sandbox promigence ``` Or set it in `~/.deepagents/config.toml`. An entry there takes the place of the registered provider, so it names the provider class as well: ```toml [sandboxes.providers.promigence] class_path = "langchain_promigence.provider:PromigenceSandboxProvider" [sandboxes.providers.promigence.params] image = "ghcr.io/your-org/dev@sha256:..." spend_cap = 5 ``` Name the environment with `image` or `snapshot`. A tag is pinned to its digest for you, and the machine running the agent needs no Docker. The first use of an image builds a snapshot from it: a saved, verified environment that each sandbox starts as a fresh copy of. That build is billed per second while it runs, whether it verifies or not, up to $0.17 at the default small size ([quickstart](https://www.promigence.ai/docs/quickstart)), and the sandboxes that reuse the snapshot pay no further build charge. `setup` and `verify` let you prepare and check that snapshot. Set `working_dir`, because the adapter does not read it from the image. ## One sandbox per backend Each `PromigenceSandbox` is one sandbox. Give each agent run its own backend and the runs never see each other's files. `sandbox.id` is the id that `promigence sandbox shell ` and `dcode --sandbox-id` accept, which is handy when you want to look inside while an agent works. ## Setting a spend cap `spend_cap` is the most one sandbox may spend, in US dollars. It falls back to `PROMIGENCE_SPEND_CAP`, then to your organization's default; with none, creation fails with a configuration error. `timeout_sec` (3600 by default) bounds the sandbox's lifetime. ## Cleaning up Call `sandbox.kill()` (or `await sandbox.akill()`) when the run is over, ideally in `finally`. The sandbox also ends on its own at `timeout_sec`. Environment failures stay separate from the agent's. A command that exits non-zero comes back in `ExecuteResponse.exit_code`. A failure of the sandbox itself raises `PromigenceEnvironmentError` with `failure_class` set to `env`; that failure is not billed and is not the task's fault. A broken image raises it with `env_definition`. ## What is not supported yet - Images without `/bin/sh`, `python3` and `grep`. The Deep Agents file tools are built on them, so distroless images cannot run the agent's file tools. - Streaming output. `execute` returns once the command finishes. - `deepagents-code` snapshot names. Name the environment with `image` or `snapshot` instead. - A JavaScript package. The JS Deep Agents sandbox interface is different and needs its own work. ## Next Read [the agent briefing](https://www.promigence.ai/agents) for what a sandbox gives an agent, or start with [the quickstart](https://www.promigence.ai/docs/quickstart). --- Page: https://www.promigence.ai/docs/guides/run-ai-written-code-safely # Run LLM-generated code safely Give each user or session its own sandbox, decide what it may reach on the network, cap its spend and time, keep credentials out of it, and end it when done. The model writes the code, and anyone who can type into your product can steer the model. So treat every line it produces as untrusted input. Running it in your own server process, or in one long-lived container shared by every user, gives a prompt-injected snippet the same reach as your application. The safer shape has five parts, and each one maps to a Promigence setting. ## One sandbox per user or session Start a sandbox when a session needs to run code, and only that session uses it. Nothing one user's code writes is visible to another user's code, and a session that goes wrong is ended without touching the rest. From the CLI: ```bash promigence fork --snapshot promigence/base --count 1 --cap 1 --timeout 30m --network none --json ``` From TypeScript, the SDK's compatibility `Sandbox` class has the familiar calls: ```typescript import { Sandbox } from "@promigence/sdk"; const modelWrittenCode = "print(sum(range(10)))"; // the Python your model wrote const sandbox = await Sandbox.create("my-analysis-env", { spendCap: 1 }); await sandbox.files.write("/tmp/job.py", modelWrittenCode); const res = await sandbox.commands.run("python3 /tmp/job.py"); console.log(res.exitCode, res.stdout); await sandbox.kill(); ``` `my-analysis-env` is a snapshot you built once with the libraries your code needs, checked by a verify command. Every session starts from that same environment, so a package the model installed last time is never there the next time. Building that snapshot is billed per second while it runs, whether the verify command passes or not, up to $0.17 at the default small size ([quickstart](https://www.promigence.ai/docs/quickstart)), and the sessions that start from it pay no further build charge. ## Decide what it may reach Most generated code needs no network at all. Start those sandboxes with `--network none`. When it does need something, such as a package index or one API, list the hosts and nothing else: ```bash promigence fork --snapshot my-analysis-env --count 1 --cap 1 \ --allow pypi.org --allow files.pythonhosted.org ``` `promigence sandbox network SID` shows what a sandbox may reach and every host it was refused. A refused host in that list is worth reading: it tells you what the code tried to do. If a sandbox is misbehaving, `--cut` turns off its outbound access at once, and it cannot be turned back on. Agents that read untrusted input, such as web pages or user uploads, belong behind an allow-list too. ## Cap the spend and the time A loop the model wrote by mistake costs you whatever it runs for. Two settings bound it. `--cap` (or `spendCap` in the SDK) is the most the sandbox may spend, in US dollars. A start whose quote is above the cap is refused before anything runs. `--timeout` is how long the sandbox lives; fifteen minutes unless you say otherwise. Each command has its own limit as well: `promigence exec --timeout DUR` ends a single command that runs too long, and `--max-output BYTES` stops a command from flooding your logs. A whole project can carry a monthly cap too: `promigence project cap PROJECT USD`, set by an owner. ## Keep credentials out of the code's reach Never paste a key into the code you run, an environment file in the snapshot, or a command line. Store it once: ```bash promigence secrets set STRIPE_TEST_KEY --from-env STRIPE_TEST_KEY ``` Then name it only on the sandboxes or commands that need it, with `--secret STRIPE_TEST_KEY`. Values are never shown by `secrets list`, and they are kept out of logs and outputs. Some credentials should never be readable by generated code at all. `secrets set NAME --host api.example.com --no-raw` binds a secret to one host: the sandbox never sees the value, and requests sent to the address the command prints for that host are authenticated for you. One more rule: a snapshot taken of a sandbox that was given a secret is refused unless you force it, because the snapshot could then contain the value. Leave it refused. ## End it when the session ends ```bash promigence sandbox kill SID ``` That stops the sandbox and its bill, and everything in it is gone. If a session is likely to come back, pause instead: `promigence sandbox pause SID` holds no capacity and bills no seconds, and `promigence sandbox autopause SID --after 5m` pauses it on its own when it goes quiet. In the SDK, `sandbox.kill()` does the same as the CLI command. ## Read failures as data The exit code says whose failure it was. A 4 means the model's code exited non-zero, which is a normal answer to show the user or feed back to the model. With 3, the environment failed, which is not the code's fault and should not be reported as such. Every error carries a `code`, a `message` and a `fix`. ## Checklist 1. One sandbox per user or session, from a snapshot you built and verified. 2. `--network none` by default; `--allow HOST` when a host is needed. 3. A spend cap and a timeout on every sandbox, and a command timeout on every command. 4. Secrets stored with `secrets set` and named where needed; host-bound for keys the code must never read. 5. `sandbox kill` when the session ends, or pause when it will be back. --- Page: https://www.promigence.ai/docs/guides/openai-agents-sdk # Run OpenAI Agents SDK agents in a Promigence sandbox Give an OpenAI Agents SDK SandboxAgent a Promigence sandbox, so its shell and file tools run there instead of on your machine. The OpenAI Agents SDK has a sandbox interface for agents that need a shell and a filesystem. The `promigence-openai-agents` package implements it with `PromigenceSandboxClient`, so a `SandboxAgent` runs its commands and file edits in a Promigence sandbox. Your agent code stays the same. Only the client you pass in changes. ## What you need - A Promigence API key in `PROMIGENCE_API_KEY`. - Python 3.10 or newer. - `openai-agents` 0.22.3. The sandbox base classes are not a stable API upstream, so the package pins `>=0.22.3,<0.23`. ## Install ```bash pip install promigence-openai-agents export PROMIGENCE_API_KEY=prom_api_... export PROMIGENCE_SPEND_CAP=5 ``` ## A minimal example Hand the client to the SDK through `SandboxRunConfig`. The SDK creates the session, starts it, gives the model its `exec_command` tool and ends the session when the run is over. ```python import asyncio from agents import RunConfig, Runner from agents.sandbox import SandboxAgent, SandboxRunConfig from promigence_openai_agents import PromigenceSandboxClient, PromigenceSandboxClientOptions agent = SandboxAgent(name="coder", instructions="Use the shell.") async def main() -> None: result = await Runner.run( agent, "Write a note to note.txt and read it back.", run_config=RunConfig(sandbox=SandboxRunConfig( client=PromigenceSandboxClient(), options=PromigenceSandboxClientOptions(image="python:3.12-slim", spend_cap=1), )), ) print(result.final_output) asyncio.run(main()) ``` You can also drive a session yourself: ```python client = PromigenceSandboxClient() session = await client.create(options=PromigenceSandboxClientOptions(image="python:3.12-slim", spend_cap=1)) async with session: result = await session.exec("python", "-c", "print(1 + 1)", shell=False) print(result.stdout.decode()) await client.delete(session) ``` Pass exactly one of `image` or `snapshot`. The first time you name an image, Promigence pins the tag to a digest, builds a snapshot from it and checks it; later sandboxes reuse that snapshot. That build is billed per second while it runs, whether it verifies or not, up to $0.17 at the default small size ([quickstart](https://www.promigence.ai/docs/quickstart)), and the sandboxes that reuse the snapshot pay no further build charge. A `snapshot` (an id, an alias, or `alias@commit7`) is used as given. Other useful options: `tier` (`small`, `medium` or `large`), `setup` and `verify` to prepare and check the snapshot, `allow_internet_access=False` for no network and `registry_secret` for a private image. Preview URLs are not enabled on Promigence yet, so resolving a port in `exposed_ports` raises `ExposedPortUnavailableError`; to reach a port, forward it over SSH with `promigence sandbox ssh -- -N -L :localhost:`. ## One sandbox per session Each SDK session is one sandbox, a fresh copy of the snapshot. Two runs never share a filesystem. To carry a session's work across runs, the SDK persists the workspace. With `workspace_persistence="tar"` (the default) you get a plain tar of the workspace directory, which any other sandbox backend can read. With `workspace_persistence="pause"` the sandbox itself is parked: it bills no seconds while parked, and `client.resume(state)` brings the whole machine back, installed packages included. A parked reference only works on Promigence, so pick `tar` when state has to move. ## Setting a spend cap `spend_cap` in `PromigenceSandboxClientOptions` is the most one sandbox may spend, in US dollars. It falls back to `PROMIGENCE_SPEND_CAP`, then to your organization's default. If none of the three is set, creating the session fails with a configuration error before anything starts. `sandbox_timeout_sec` (3600 by default) bounds the sandbox's lifetime. ## Cleaning up `await client.delete(session)` ends the sandbox, or parks it when you set `pause_on_exit=True`. A session parked through `workspace_persistence="pause"` stays parked even after `delete`, because the saved reference is the only way back to it. End those with `promigence sandbox kill ` once you no longer need them. Failures are kept apart. A command that exits non-zero comes back as a result, a timeout raises `ExecTimeoutError`, and a failure on the Promigence side raises `ExecTransportError` with `context["failure_class"] == "env"`, marked retryable so the SDK's own retry logic can try again. ## What is not supported yet - Interactive terminals. `supports_pty()` is `False`, so `pty_exec_start` is unavailable. - Streaming output. A command's output arrives when it finishes. - Manifest entries that need a cloud mount. Plain files, directories and git artifacts work. - A JavaScript version. The JS SDK's sandbox contract differs and needs its own package. - The image needs `/bin/sh`, and `tar` for the default persistence mode. ## Next Read [the agent briefing](https://www.promigence.ai/agents) for what a sandbox gives an agent, or start with [the quickstart](https://www.promigence.ai/docs/quickstart). --- Page: https://www.promigence.ai/docs/guides/strands # Run Strands agents in a Promigence sandbox Give a Strands agent a Promigence sandbox, so its shell and file-editor tools run there with output streamed back as it is written. Strands Agents has a sandbox interface: give an `Agent` a sandbox and it gets shell and file-editor tools bound to it. The `strands-promigence` package provides `PromigenceSandbox`, so those tools act on a Promigence sandbox instead of the machine running your agent. Output streams back while a command is still running. ## What you need - A Promigence API key in `PROMIGENCE_API_KEY`. - Python 3.10 or newer. - `strands-agents` 1.56.0. The sandbox interface is young, so the package pins `>=1.56,<2`. ## Install ```bash pip install strands-promigence export PROMIGENCE_API_KEY=prom_api_... export PROMIGENCE_SPEND_CAP=5 ``` ## A minimal example ```python import asyncio from strands import Agent from strands_promigence import PromigenceSandbox async def main() -> None: async with PromigenceSandbox(image="python:3.12-slim", spend_cap=1) as sandbox: agent = Agent(sandbox=sandbox) await agent.invoke_async("Install httpx and print its version.") asyncio.run(main()) ``` `Agent(sandbox=...)` registers two tools, `sandbox_shell` and `sandbox_file_editor`, unless you already have tools with those names. The `async with` form creates the sandbox up front and ends it on exit. Without it, nothing is created until the first command runs, so you can build an `Agent` before a key is even set. In that case end it with `await sandbox.aclose()`. Pass exactly one of `image` or `snapshot`. The first time you name an image, Promigence pins its tag to a digest, builds a snapshot from it and checks it. A snapshot is a saved, verified environment, and each sandbox starts as a fresh copy of it, so later sandboxes reuse what was built. That build is billed per second while it runs, whether it verifies or not, up to $0.17 at the default small size ([quickstart](https://www.promigence.ai/docs/quickstart)), and the sandboxes that reuse it pay no further build charge. Useful options include `tier` (`small`, `medium` or `large`), `working_dir`, `env`, `user`, `setup` and `verify` to prepare and check the snapshot, `allow_internet_access=False` for no network, and `registry_secret` for a private image. ## How sandboxes map to agents One `PromigenceSandbox` is one sandbox. Give each agent, or each task you want kept apart, its own instance. Sharing one across several agents shares one filesystem. Output is read while the command runs, every 250 ms by default (`poll_ms`), so a line written early reaches the agent within one read rather than at exit. That suits logs and test output well. ## Setting a spend cap `spend_cap` is the most one sandbox may spend, in US dollars. It falls back to `PROMIGENCE_SPEND_CAP`, then to your organization's default, and a configuration error is raised if there is none. `sandbox_timeout_sec` (3600 by default) bounds the sandbox's lifetime. ## Cleaning up `async with` ends the sandbox for you. Otherwise call `await sandbox.aclose()`. A sandbox you forget ends on its own at `sandbox_timeout_sec`. When something fails, you can tell whose failure it was. A non-zero exit is an `ExecutionResult` with the exit code. A timeout raises `SandboxTimeoutError` with whatever the command had written. A failure on the Promigence side raises `PromigenceAdapterError` with `failure_class == "env"`, so it never looks like the agent's command failed. ## What is not supported yet - An interactive terminal tool. The Strands sandbox interface has no place for one. - `output_files`. It is always empty; the agent reads files it produced with the file tools. - Changing directory between commands. `working_dir` is resolved once, so a `cd` does not carry over. - The image needs `/bin/sh`. Running code also needs `base64` and the interpreter you name. ## Next Read [the agent briefing](https://www.promigence.ai/agents) for what a sandbox gives an agent, or start with [the quickstart](https://www.promigence.ai/docs/quickstart). --- Page: https://www.promigence.ai/docs/guides/vercel-ai-sdk # Run Vercel AI SDK agents in a Promigence sandbox Pass a Promigence sandbox to the Vercel AI SDK as experimental_sandbox, or to bash-tool, so an agent's commands and files live there. The Vercel AI SDK lets a tool reach a sandbox through `experimental_sandbox`, and `bash-tool` takes a sandbox of its own. The `promigence-ai-sdk-sandbox` package wraps a Promigence sandbox in one object that both accept. Your tools run commands, read files and write files in the sandbox, and nothing the model asks for touches your server. ## What you need - A Promigence API key in `PROMIGENCE_API_KEY`. - Node.js 20 or newer. - `ai` 7.0.106 and, if you use it, `bash-tool` 1.3.19. Those are the versions the package was tested against, on TypeScript 5.9. ## Install ```bash npm install promigence-ai-sdk-sandbox @promigence/sdk ai zod bash-tool export PROMIGENCE_API_KEY=prom_api_... ``` ## A minimal example Create the sandbox with `@promigence/sdk`, then wrap it: ```ts import { generateText, tool } from "ai"; import { Sandbox } from "@promigence/sdk"; import { promigenceSandbox } from "promigence-ai-sdk-sandbox"; import { z } from "zod"; const sandbox = await Sandbox.create({ timeoutMs: 600_000, spendCap: 1 }); const session = promigenceSandbox(sandbox, { workingDirectory: "/workspace" }); try { await generateText({ model: "anthropic/claude-sonnet-4-5", prompt: "run the tests and fix what fails", experimental_sandbox: session, tools: { shell: tool({ description: "run a shell command", inputSchema: z.object({ command: z.string() }), execute: async ({ command }, { experimental_sandbox }) => { const { exitCode, stdout, stderr } = await experimental_sandbox!.run({ command }); return `${exitCode}\n${stdout}${stderr}`; }, }), }, }); } finally { await session.stop(); } ``` With no snapshot named, `Sandbox.create` starts from the built-in base. To start from your own environment, pass a snapshot alias (`Sandbox.create("my-env", { ... })`) or an image digest with `{ image: "registry/name@sha256:...", allowBuild: true }`. A snapshot is a saved, verified environment, and each sandbox starts as a fresh copy of it. The first use of a new image builds that snapshot, and `allowBuild: true` is how you agree to that build. Alternatively, build it once ahead of time with `promigence snapshot create --image --alias my-env`. Either way, the build is billed per second while it runs, whether it verifies or not, up to $0.17 at the default small size ([quickstart](https://www.promigence.ai/docs/quickstart)), and sandboxes started from the snapshot pay no further build charge. The same session works as `bash-tool`'s sandbox: ```ts import { createBashTool } from "bash-tool"; const { tools } = await createBashTool({ sandbox: session, destination: "/workspace" }); ``` `promigenceSandbox` accepts `description` (what the agent is told about its environment), `workingDirectory` (default `/workspace`, created before the first command that uses it), `env`, `timeoutMs`, `maxOutputBytes` and `user`. Beyond `run`, the session has `spawn` for a background command with streamed `stdout` and `stderr`, and read and write methods for text and binary files. Relative paths resolve under `workingDirectory`. ## One sandbox per conversation The package does not create or end sandboxes beyond `stop()`. It wraps the handle you give it. A sensible default is one sandbox per agent run or per user conversation, created at the start and stopped at the end, so no two runs share files. ## Setting a spend cap Pass `spendCap` (US dollars) to `Sandbox.create`, or set `PROMIGENCE_SPEND_CAP`. Without either, your organization's default applies. It is the most the sandbox may spend. `timeoutMs` on `Sandbox.create` bounds how long the sandbox lives. ## Cleaning up `await session.stop()` ends the sandbox. Put it in `finally`, as above. `promigence sandbox list` shows anything left running. A command that exits non-zero is the agent's result and comes back in `exitCode`. A failure of the sandbox itself is thrown as `PromigenceEnvironmentError` with a `failureClass`, because an exit code of 1 would wrongly say the agent's command failed. `failureClassOf(error)` classifies any error the Promigence SDK throws. ## What is not supported yet - Sandbox lifecycle beyond `stop()`. Create the sandbox with `@promigence/sdk`; copies and parking stay there too. - `SandboxProcess.pid`. The command id is on `process.execId` instead. - Byte-by-byte output. `spawn`'s streams deliver chunks as they are read. - Per-file errors from `writeFiles`. It stops at the first failure. - Directory upload, port previews and interactive terminals through this wrapper. Use the `@promigence/sdk` handle for those. ## Next Read [the agent briefing](https://www.promigence.ai/agents) for what a sandbox gives an agent, or start with [the quickstart](https://www.promigence.ai/docs/quickstart). --- Page: https://www.promigence.ai/docs/guides/snapshot-and-fork # Snapshot after npm install, then fork 10 copies Install dependencies once in a sandbox, take a snapshot of it while it runs, and start ten parallel attempts from that snapshot, in TypeScript, Python or the CLI. `npm install` is the slow, identical part of every attempt an agent makes. Run it once, take a snapshot of the sandbox as it is at that moment, and start every attempt from the snapshot: ten copies, each with `node_modules` already in place, each free to change its own files without touching the others. ## The short answer Install once in one sandbox, snapshot it while it runs, and start ten sandboxes from the snapshot. On Promigence that is `client.sandboxes.snapshot(id)` followed by `Sandbox.fork(snapshotId, { count: 10 })` in TypeScript, the same two calls in Python, or `promigence sandbox snapshot` and `promigence run --count 10` in a shell. Every copy starts with the files the sandbox had when you took the snapshot. ## In TypeScript It has to run as an ES module, for the top-level `await`. The base sandbox already has Node.js with npm, and git (`promigence templates show base` lists everything in it). ```typescript import { PromigenceClient, Sandbox } from "@promigence/sdk"; const client = new PromigenceClient(); // reads PROMIGENCE_API_KEY, or the key signup stored const REPO = "https://github.com/your-org/your-app"; // 1. One sandbox, and the slow part, once const setup = await Sandbox.create({ client, spendCap: 1, timeoutMs: 30 * 60_000 }); await setup.commands.run(`git clone --depth 1 ${REPO} /work/app && cd /work/app && npm install`, { timeoutMs: 15 * 60_000, }); // 2. A snapshot of the sandbox as it is now const snap = await client.sandboxes.snapshot(setup.sandboxId, { alias: "app-installed", moveAlias: true }); await setup.kill(); // 3. Ten copies, each with node_modules already installed const copies = await Sandbox.fork(snap.snapshot_id, { client, count: 10, spendCap: 3, timeoutMs: 20 * 60_000 }); // 4. One attempt per copy, all at once const results = await Promise.all( copies.map(async (sbx, i) => { const r = await sbx.commands.run("cd /work/app && node agent.js && npm test", { envs: { ATTEMPT: String(i) }, timeoutMs: 15 * 60_000, throwOnExit: false, }); return { sbx, attempt: i, passed: r.exitCode === 0 }; }), ); const winner = results.find((r) => r.passed); console.log(winner ? `attempt ${winner.attempt} passed in ${winner.sbx.sandboxId}` : "no attempt passed"); await Promise.all(results.filter((r) => r !== winner).map((r) => r.sbx.kill())); ``` `node agent.js` stands for your agent's attempt; `ATTEMPT` tells each copy which one it is, so it can vary a seed or a prompt. The winner keeps running until you kill it or it reaches its timeout, so you can read its diff with `sbx.commands.run("git -C /work/app diff")` before you end it. `spendCap: 3` caps what the ten copies may spend together: ten small sandboxes for up to 20 minutes cost at most 10 × 1,200 × $0.000046 = $0.55 at list, so the cap leaves room. A sandbox that reaches its cap is paused with its files kept, and if your script dies halfway, every copy still ends at its 20-minute timeout. ## In Python The same four steps, with a thread per attempt: ```python from concurrent.futures import ThreadPoolExecutor from typing import List from promigence import Promigence, Sandbox REPO = "https://github.com/your-org/your-app" with Promigence() as client: # reads PROMIGENCE_API_KEY setup = Sandbox.create(client=client, spend_cap=1, timeout_ms=30 * 60_000) setup.commands.run(f"git clone --depth 1 {REPO} /work/app && cd /work/app && npm install", timeout_ms=15 * 60_000) snap = client.sandboxes.snapshot(setup.sandbox_id, alias="app-installed", move_alias=True) setup.kill() copies: List[Sandbox] = Sandbox.fork( snap["snapshot_id"], client=client, count=10, spend_cap=3, timeout_ms=20 * 60_000, ) def attempt(i: int) -> bool: result = copies[i].commands.run( "cd /work/app && node agent.js && npm test", envs={"ATTEMPT": str(i)}, timeout_ms=15 * 60_000, throw_on_exit=False, ) return result.exit_code == 0 with ThreadPoolExecutor(max_workers=10) as pool: passed = list(pool.map(attempt, range(10))) winner = passed.index(True) if True in passed else None print(f"attempt {winner} passed" if winner is not None else "no attempt passed") for i, sbx in enumerate(copies): if i != winner: sbx.kill() ``` ## From a shell `--json` makes every command print one JSON document, so a script can pick out the ids: ```bash SID=$(promigence fork --count 1 --cap 1 --timeout 30m --fresh --json | jq -r '.sandboxes[0].sandbox_id') promigence exec --sandbox "$SID" --timeout 15m -- \ sh -c "git clone --depth 1 https://github.com/your-org/your-app /work/app && cd /work/app && npm install" promigence sandbox snapshot "$SID" --alias app-installed --move-alias promigence sandbox kill "$SID" promigence run --snapshot app-installed --count 10 --cap 3 --timeout 20m \ -- sh -c 'cd /work/app && ATTEMPT=$PROMIGENCE_INDEX node agent.js && npm test' ``` `promigence run` starts the ten copies, runs the attempt in each with `PROMIGENCE_INDEX` set from 0 to 9, and prints a validity report that says which attempts passed and whether any failure was the environment's or the attempt's. ## What the snapshot keeps, and what to watch The sandbox you snapshot keeps running. Its files go into the snapshot, `node_modules` included, and every copy starts with them. Commands started in the background (`background: true`, or `exec --background`) are ended to take the snapshot, so start long-lived processes again in the copies. Three details save a debugging session: 1. `sbx.fork()` on a sandbox object never copies your install: after any command it asks for `fromOrigin: true` and then copies the snapshot the sandbox started from. To copy it as it is now, take a snapshot first and fork that. 2. A sandbox that was given a secret is refused a snapshot unless you force it, because the snapshot and every copy could then contain the value. So install first, and give the secret to the copies (`secrets` on `Sandbox.fork`). 3. An alias names one snapshot in your organization. `moveAlias` (`--move-alias`) takes it from the snapshot that has it, so the script can run again. When every task installs the same dependencies, build the snapshot from a recipe instead and let a verify command check it. It is stored only if the verify command exits 0, the build is billed per second while it runs, up to $0.17 at the default small size ([quickstart](https://www.promigence.ai/docs/quickstart)), and a connected GitHub repository can rebuild it on every push: ```bash promigence snapshot create --image node:22 \ --setup "git clone https://github.com/your-org/your-app /work/app && git -C /work/app checkout <40-char sha>" \ --setup "cd /work/app && npm ci" \ --verify "cd /work/app && npm test" \ --alias app --wait --wait-timeout 10m ``` A build that fails its verify command is billed for the time it ran, and the sandboxes started from the snapshot pay no further build charge. ## At a glance | | Snapshot of a running sandbox | Snapshot built from a recipe | |---|---|---| | Command | `promigence sandbox snapshot SID`, `client.sandboxes.snapshot(id)` | `promigence snapshot create --image REF --setup CMD --verify CMD` | | Starts from | Whatever the sandbox holds at that moment | An image or a Dockerfile, plus your setup steps | | Checked by a verify command | No | Yes: stored only if the command exits 0 | | Best for | Branching a session mid-task, retries from one point | An environment many runs share, rebuilt per commit | | Background commands | Ended to take the snapshot | A `--start` command runs in every copy | | Copies | `Sandbox.fork(id, { count })`, `promigence run --snapshot NAME --count N` | The same | **Install once, try ten times** Your agent framework installs dependencies once in one sandbox and takes a snapshot of it. Ten copies start from that snapshot with node_modules already installed, each runs one attempt and its tests, and the framework keeps the attempt that passed. Steps: 1. Your agent framework 2. One sandbox: git clone and npm install 3. Snapshot: app-installed 4. Ten copies with node_modules in place 5. Ten attempts, then npm test 6. Keep the attempt that passed, kill the rest Connections: 1. Your agent framework → One sandbox: git clone and npm install: Sandbox.create 2. One sandbox: git clone and npm install → Snapshot: app-installed: sandboxes.snapshot 3. Snapshot: app-installed → Ten copies with node_modules in place: Sandbox.fork, count 10 4. Ten copies with node_modules in place → Ten attempts, then npm test: one attempt each 5. Ten attempts, then npm test → Keep the attempt that passed, kill the rest: results 6. Keep the attempt that passed, kill the rest → Your agent framework: diff of the winner _Your agent framework branches one prepared sandbox into ten attempts_ ## FAQ ### How do you snapshot a sandbox after npm install and fork it for 10 parallel attempts? In one sandbox, run `npm install`, take a snapshot with `client.sandboxes.snapshot(sandboxId)`, then start ten copies with `Sandbox.fork(snapshotId, { count: 10 })`. The copies start with `node_modules` already installed, and each runs its own attempt. The full program is above in TypeScript, in Python and as CLI commands. ### Which sandbox platforms let me snapshot and fork a running agent environment? Promigence is one: `promigence sandbox snapshot` takes a snapshot of a running sandbox without stopping it, and any number of sandboxes can start from the result. When you compare platforms, ask whether a snapshot can come from a running sandbox or only from a template build, whether copies start with the files you captured, what happens to running processes, and whether a secret in the sandbox can end up in the snapshot. ### Does the original sandbox stop when I take the snapshot? No. It keeps running, and you get an ordinary snapshot id you can start sandboxes from. Commands started in the background are ended to take the snapshot; the CLI and the SDK say how many. ### Do the ten copies share files? Each copy starts with the snapshot's files, and what one attempt writes is its own. No sandbox can see, reach or address another, so a failing attempt cannot damage the others. ### What does forking ten copies cost? Every copy bills per second at the rate for its size, and snapshot storage is included in every plan. At list, ten small sandboxes for up to 20 minutes cost at most $0.55, and `spendCap` holds the batch to the number you set. ## Sources - [CLI reference](https://www.promigence.ai/docs/cli): `sandbox snapshot`, `fork`, `exec`, `run`, `snapshot create`, read 17 Oct 2026 - [TypeScript SDK](https://www.promigence.ai/docs/sdk): `Sandbox.create`, `commands.run`, `kill`, spend caps, read 17 Oct 2026 - [Pricing](https://www.promigence.ai/#pricing): rates per size, read 17 Oct 2026 - [Quickstart](https://www.promigence.ai/docs/quickstart): builds billed per second while they run, failed ones included, read 19 Oct 2026 - [Limits and notices](https://www.promigence.ai/docs/limits): what happens at a spend cap, read 17 Oct 2026 - [Security](https://www.promigence.ai/security): isolation between sandboxes, secrets kept out of snapshots, read 17 Oct 2026 - [What is snapshot fork?](https://www.promigence.ai/glossary/snapshot-fork), Promigence glossary, read 17 Oct 2026 - [@promigence/sdk on npm](https://www.npmjs.com/package/@promigence/sdk): version 0.1.0-beta.7, read 17 Oct 2026 - [promigence on PyPI](https://pypi.org/project/promigence/): the Python SDK, version 0.1.0b7, read 17 Oct 2026 Updated 2026-10-17. --- Page: https://www.promigence.ai/docs/migrate # Migrate Move code written for another sandbox provider to Promigence, and see which calls change. - [Moving from Runloop to Promigence](https://www.promigence.ai/docs/migrate/migrate-from-runloop-to-promigence) Move Runloop devboxes and blueprints to Promigence sandboxes: a concept map, the same code in TypeScript and Python, and checks that prove the move. --- Page: https://www.promigence.ai/docs/migrate/migrate-from-runloop-to-promigence # Moving from Runloop to Promigence Move Runloop devboxes and blueprints to Promigence sandboxes: a concept map, the same code in TypeScript and Python, and checks that prove the move. This notice opens Runloop's documentation: "Runloop is winding down its services. Support for existing customers continues through November 13, 2026 at 11:59 PM PT." ([Runloop transition guides](https://docs.runloop.ai/docs/transitions/overview), read 25 Oct 2026) If your agents run in Runloop devboxes, this guide moves them to Promigence sandboxes. You get a map from each Runloop part to what replaces it, one program written both ways in TypeScript and Python, a blueprint rebuilt from its Dockerfile, the checks that prove the move, and both price lists. When Promigence has nothing to match a Runloop feature, the tables say so. ## Before you start Install the CLI, sign up, then add the SDK your code uses: ```bash npm i -g promigence # the CLI promigence signup # in your browser: sign up, then authorize the CLI promigence credits claim # claim your free credit before the first run npm i @promigence/sdk # the TypeScript SDK (Node.js 20 or newer) pip install promigence # the Python SDK ``` Both SDKs read `PROMIGENCE_API_KEY`, or the key `promigence signup` stored. Where your Runloop CI read `RUNLOOP_API_KEY`, set `PROMIGENCE_API_KEY` to a key from `promigence keys create`. A new account runs 20 sandboxes at once, each for up to an hour, on sizes up to large (8 vCPU), with 20 GB of data out a month. If your Runloop fleet needs more, email support@promigence.ai before you move it. ## What each Runloop part becomes The first table covers what most Runloop code calls. Where the Python name differs, it follows the TypeScript one in parentheses. | Runloop | Promigence | What changes | |---|---|---| | Devbox: `runloop.devbox.create()` | Sandbox: `Sandbox.create()`, `AsyncSandbox.create()` in Python, `promigence fork --count 1 --cap 1` in the CLI | A sandbox starts from a snapshot or a template, or from the Promigence base when you name neither. Every sandbox runs under a spend cap: `spendCap` (`spend_cap`) in dollars; leave it out and the sandbox is held to what its full timeout costs (on the trial, to the credit left), or to your organization's default cap if it has one | | Prebuilt blueprints such as `runloop/starter-x86_64` and `runloop/universal-ubuntu-24.04-x86_64` | Templates | `promigence templates` lists them and `promigence templates show NAME` lists what one has installed. Start a sandbox from one by its name | | Blueprints you built: `runloop.blueprint.create()`, `rli blueprint from-dockerfile` | Snapshots you build: `promigence snapshot create --dockerfile PATH --alias NAME` | Start sandboxes from the alias where you passed `blueprint_name`. [Moving an environment](#moving-an-environment) has the steps | | Disk snapshots: `devbox.snapshot_disk()`, then `snapshot.create_devbox()` | `client.sandboxes.snapshot(id)` or `promigence sandbox snapshot SID`, then `Sandbox.create(snapshot_id)` | The sandbox keeps running while the snapshot is taken. Commands started in the background end. Snapshotting a sandbox that was given a secret needs `--force`. Delete a snapshot with `client.snapshots.delete(id)` or `promigence snapshot delete` | | Suspend and resume: `suspend()`, `await_suspended()`, `resume()`, `await_running()` | Pause and resume: `pause()` and `resume()`, or `promigence sandbox pause SID` and `promigence sandbox resume SID` | No wait calls: each returns when it is done. Runloop keeps the disk, and you restart processes after a resume. On Promigence, commands started with `background: true` end at the pause; anything else you started keeps running when the sandbox resumes, so guard your restart logic against starting a second copy. A paused sandbox is not billed by the second and does not count against your concurrency limit. Paused sandboxes are kept for 30 days, and resuming starts the 30 days again | | Idle policy: `lifecycle.after_idle` with `on_idle: "suspend"` | `setAutoPause(seconds)` (`set_auto_pause`), or `promigence sandbox autopause SID --after DUR` | The shortest idle window is 2 seconds. Idle means no API requests; `--mode activity` also waits until nothing inside uses CPU, moves network traffic or holds a connection open. `on_idle: "shutdown"` has no equivalent: the timeout ends a sandbox | | Lifetime: `keep_alive_time_seconds`, 1 hour by default, and `keep_alive()` | `timeoutMs` (`timeout_ms`) at create, `--timeout` in the CLI; extend with `setTimeout(ms)` (`set_timeout`) or `promigence sandbox extend SID --timeout DUR` | The default timeout is 15 minutes. An extension sets a new total timeout, and it is refused if it would take the run past its spend cap. Resuming a paused sandbox starts its clock again, for billing and for the timeout | | Commands: `devbox.cmd.exec()` | `sandbox.commands.run()` | `stdout`, `stderr` and `exitCode` (`exit_code`) are fields, so `await result.stdout()` becomes `result.stdout`. Unless you pass `throwOnExit: false` (`throw_on_exit=False`), a non-zero exit raises `CommandExitError`. Up to 64 KiB of each output stream is kept by default; `maxOutputBytes` raises that, and `truncated` tells you when output was cut | | Long-running commands: `exec_async()`, `execAsync()` | `commands.run(cmd, { background: true })` (`background=True`) | It returns a handle with `wait()` and `kill()` | | Streaming: the `stdout`, `stderr` and `output` callbacks | `onStdout` and `onStderr` (`on_stdout`, `on_stderr`) | There is no combined `output` callback, so pass both | | Files: `file.write()`, `file.read()`, `file.upload()`, `file.download()` | `files.write(path, data)`, `files.read(path)` | Text is UTF-8 both ways. For binary data, pass bytes to `files.write` and read with `{ format: "bytes" }` (`format="bytes"`). Whole directories move with `files.uploadDir` and `files.downloadDir` (`upload_dir`, `download_dir`) or `promigence files put --recursive`. Write absolute paths: Runloop resolves relative ones against `/home/user`, its default home | | Tunnels: `enable_tunnel()`, `get_tunnel_url()`, `wake_on_http` | No equivalent today | To reach a port from your own machine, forward it over SSH with `promigence sandbox ssh`. Nothing replaces `wake_on_http` | | Account secrets: `secrets: { ENV_NAME: "SECRET_NAME" }` | Stored secrets: `promigence secrets set NAME --from-env VAR` | Give one to a sandbox by name and it arrives as an environment variable of that name: `secrets=["NAME"]` in Python, or `{"name": "NAME", "as": "ENV_NAME"}` for another variable name. In TypeScript the option goes on `Sandbox.fork(snapshot, { count: 1, secrets })`, and in the CLI it is `--secret NAME`. Blueprint build secrets have no equivalent: a snapshot you build never holds a secret | The rest of Runloop's features, most of which have no Promigence equivalent: | Runloop | Promigence | What changes | |---|---|---| | Named shells: `devbox.shell(name)`, `shell_name` | No equivalent | Each `commands.run` starts a new shell, as Runloop's default `exec` does. Pass `cwd` and `envs` on each call, or chain dependent steps in one command. An interactive session needs a terminal: `sandbox.pty.create()` or `promigence sandbox shell SID` | | SSH: `rli devbox ssh` | `promigence sandbox ssh SID` | Port forwarding with `-L` works, as do scp and sftp, and `--config` prints a block for an IDE. Access lasts an hour at most (`--ttl`) | | Network policies: `allowed_hostnames` | An outbound allow-list: `allow_hosts=[...]` in Python, `allowHosts` on `Sandbox.fork` in TypeScript, `--allow HOST` in the CLI | `allowInternetAccess: false` or `--network none` starts a sandbox with no network. `disableInternet()` or `promigence sandbox network SID --cut` turns off a running sandbox's outbound access for good, and `promigence sandbox network SID` lists the hosts it was refused | | Sizes: `resource_size_request`, `CUSTOM_SIZE` | Tiers: `--tier xsmall` up to `2xlarge` when you build a snapshot | A sandbox gets its snapshot's size, and the base is small (2 vCPU, 4 GiB). There are no custom sizes | | `architecture: "arm64"` | No equivalent | There is no architecture setting. Write to support@promigence.ai before you move an arm64 workload | | Mounts: `code_mount`, `object_mount`, `file_mount`, `agent_mount` | No equivalent | Clone code in a `--setup` step at a pinned commit, or build from a connected GitHub repository with `--repo`. Copy files in with `files.write` or a `COPY` line in your Dockerfile. `promigence agent start` starts Claude Code, Codex or OpenCode in a new sandbox | | Storage objects | No equivalent | Keep artifacts in your own storage and move them with `files.read` and `files.write` | | Axons and the Broker | No equivalent | Keep events and state in a store of your own | | Agent Gateways and MCP Hub | No equivalent for MCP Hub | For a model key, the nearest match is a stored secret bound to a host (`promigence secrets set NAME --host HOST`), described in the [CLI reference](https://www.promigence.ai/docs/cli) | ## The same program, side by side Each Runloop cell below quotes a page of Runloop's docs, read 25 Oct 2026: the [quickstart](https://docs.runloop.ai/docs/tutorials/quickstart), the guides to [commands](https://docs.runloop.ai/docs/devboxes/execute-commands) and [files](https://docs.runloop.ai/docs/devboxes/files), the [snapshot](https://docs.runloop.ai/docs/devboxes/snapshots) and [lifecycle](https://docs.runloop.ai/docs/devboxes/lifecycle) pages, and the Python [SDK reference](https://runloopai.github.io/api-client-python/api/snapshot.html) for `create_devbox`. Next to each one, the Promigence cell does the same step. TypeScript: | Step | Runloop | Promigence | |---|---|---| | Client | `const runloop = new RunloopSDK();` | `const client = new PromigenceClient();` | | Create | `const devbox = await runloop.devbox.create();` | `const sbx = await Sandbox.create({ client, spendCap: 1 });` | | Run a command | `const result = await devbox.cmd.exec("echo 'Runloop!!'");` | `const result = await sbx.commands.run("echo 'Hello from Promigence'");` | | Read the result | `await result.stdout()`, `result.exitCode` | `result.stdout`, `result.exitCode` | | Write a file | `await devbox.file.write({ file_path: '/home/user/main.py', contents: 'print("Hello, World!")' });` | `await sbx.files.write("/tmp/main.py", 'print("Hello, World!")');` | | Read a file | `const contents = await devbox.file.read({ file_path: '/home/user/test_results.txt' });` | `const contents = await sbx.files.read("/tmp/main.py");` | | Snapshot | `const snapshot = await devbox.snapshotDisk();` | `const snap = await client.sandboxes.snapshot(sbx.sandboxId);` | | Suspend, or pause | `await devbox.suspend();` then `await devbox.awaitSuspended();` | `await sbx.pause();` | | Resume | `await devbox.resume();` then `await devbox.awaitRunning();` | `await sbx.resume();` | | Start from the snapshot | `const devbox = await snapshot.createDevbox();` | `const copy = await Sandbox.create(snap.snapshot_id, { client, spendCap: 1 });` | | Shut down | `await devbox.shutdown();` | `await sbx.kill();` | Python, with the async SDKs on both sides: | Step | Runloop | Promigence | |---|---|---| | Client | `runloop = AsyncRunloopSDK()` | `client = AsyncPromigence()` | | Create | `devbox = await runloop.devbox.create()` | `sbx = await AsyncSandbox.create(client=client, spend_cap=1)` | | Run a command | `result = await devbox.cmd.exec(command="echo 'Runloop!!'")` | `result = await sbx.commands.run("echo 'Hello from Promigence'")` | | Read the result | `await result.stdout()`, `result.exit_code` | `result.stdout`, `result.exit_code` | | Write a file | `await devbox.file.write(file_path="/home/user/main.py", contents='print("Hello, World!")')` | `await sbx.files.write("/tmp/main.py", 'print("Hello, World!")')` | | Read a file | `contents = await devbox.file.read(file_path="/home/user/test_results.txt")` | `contents = await sbx.files.read("/tmp/main.py")` | | Snapshot | `snapshot = await devbox.snapshot_disk()` | `snap = await client.sandboxes.snapshot(sbx.sandbox_id)` | | Suspend, or pause | `await devbox.suspend()` then `await devbox.await_suspended()` | `await sbx.pause()` | | Resume | `await devbox.resume()` then `await devbox.await_running()` | `await sbx.resume()` | | Start from the snapshot | `await snapshot.create_devbox()` | `copy = await AsyncSandbox.create(snap["snapshot_id"], client=client, spend_cap=1)` | | Shut down | `await devbox.shutdown()` | `await sbx.kill()` | Here is the whole Promigence program in TypeScript, which also starts a second sandbox from the snapshot and cleans up after itself. Run it as an ES module, for the top-level `await`: ```typescript import { PromigenceClient, Sandbox } from "@promigence/sdk"; const client = new PromigenceClient(); // reads PROMIGENCE_API_KEY, or the key signup stored const sbx = await Sandbox.create({ client, spendCap: 1 }); try { const result = await sbx.commands.run("echo 'Hello from Promigence'"); console.log(result.stdout, result.exitCode); await sbx.files.write("/tmp/main.py", 'print("Hello, World!")'); console.log(await sbx.files.read("/tmp/main.py")); // A snapshot of the sandbox as it is now: new sandboxes can start from it const snap = await client.sandboxes.snapshot(sbx.sandboxId); await sbx.pause(); await sbx.resume(); console.log(await sbx.files.read("/tmp/main.py")); // still there const copy = await Sandbox.create(snap.snapshot_id, { client, spendCap: 1 }); console.log(await copy.files.read("/tmp/main.py")); await copy.kill(); await client.snapshots.delete(snap.snapshot_id); } finally { await sbx.kill(); } ``` And the same in Python: ```python import asyncio from promigence import AsyncPromigence, AsyncSandbox async def main() -> None: async with AsyncPromigence() as client: # reads PROMIGENCE_API_KEY, or the key signup stored sbx = await AsyncSandbox.create(client=client, spend_cap=1) try: result = await sbx.commands.run("echo 'Hello from Promigence'") print(result.stdout, result.exit_code) await sbx.files.write("/tmp/main.py", 'print("Hello, World!")') print(await sbx.files.read("/tmp/main.py")) # A snapshot of the sandbox as it is now: new sandboxes can start from it snap = await client.sandboxes.snapshot(sbx.sandbox_id) await sbx.pause() await sbx.resume() print(await sbx.files.read("/tmp/main.py")) # still there copy = await AsyncSandbox.create(snap["snapshot_id"], client=client, spend_cap=1) print(await copy.files.read("/tmp/main.py")) await copy.kill() await client.snapshots.delete(snap["snapshot_id"]) finally: await sbx.kill() asyncio.run(main()) ``` `spendCap: 1` caps what the sandbox may spend at one dollar. Leave it out and the sandbox is capped at what its full timeout costs (on the trial, at the credit left). ## Moving an environment A Runloop blueprint becomes a snapshot that you build once and start sandboxes from by its alias. Builds take an image or a Dockerfile, your setup steps and a verify command. If the verify command does not exit 0, nothing is stored. A build is billed per second while it runs, whether it verifies or not, up to $0.17 at the default small size. Runloop's blueprint guide uses `launch_commands` to install `jq` ([Runloop blueprints](https://docs.runloop.ai/docs/devboxes/blueprints/overview), read 25 Oct 2026). Every launch command becomes a `--setup` step, and the verify command proves the step worked: ```bash promigence snapshot create --image ubuntu:24.04 \ --setup "apt-get update && apt-get install -y jq" \ --verify "jq --version" \ --alias docs-template --wait --wait-timeout 10m ``` A blueprint built from a Dockerfile, with `rli blueprint from-dockerfile --name my-agent-env --dockerfile ./docker/Dockerfile --build-context .`, keeps its Dockerfile. First change any `FROM runloop:` line. That prefix names Runloop's own images and blueprints ([Runloop Dockerfile customization](https://docs.runloop.ai/docs/devboxes/blueprints/dockerfile-customization), read 25 Oct 2026), so start from a public image instead and install what your code used from Runloop's starter image. The [Runloop devbox overview](https://docs.runloop.ai/docs/devboxes/overview) lists what that image includes. ```dockerfile # was: FROM runloop:runloop/starter-x86_64 FROM ubuntu:24.04 RUN apt-get update \ && apt-get install -y --no-install-recommends ca-certificates curl git jq python3 python3-pip \ && rm -rf /var/lib/apt/lists/* ``` Then build it, with the same build context: ```bash promigence snapshot create --dockerfile ./docker/Dockerfile --context . \ --verify "python3 --version && jq --version" \ --alias my-agent-env --wait --wait-timeout 10m ``` Start sandboxes from the alias with `Sandbox.create("my-agent-env", { spendCap: 1 })` in TypeScript, `AsyncSandbox.create("my-agent-env", spend_cap=1)` in Python, or `promigence fork --snapshot my-agent-env --count 1 --cap 1`. Other blueprint settings move to flags of `snapshot create`: | On Runloop | On Promigence | |---|---| | `resource_size_request` for each devbox | `--tier` on the build, for every sandbox from the snapshot: `--tier medium` is 4 vCPU and 16 GiB | | A server started by a background launch command | `--start CMD`, started at build time and already running in every sandbox made from the snapshot | | A code mount | A `git clone` in a `--setup` step at a pinned commit, or `--repo owner/name` for a connected GitHub repository, with `--track` to rebuild on every push | | `rli blueprint logs` | `promigence snapshot status BUILD_ID --log 80` for the last 80 lines of the build log | Promigence cannot import a Runloop snapshot. To keep data from one, start a temporary devbox from it and export the directories you need, as Runloop's transition guides suggest ([Runloop transition guides](https://docs.runloop.ai/docs/transitions/overview), read 25 Oct 2026). Pack them with `tar` in that devbox and fetch the archive with `file.download`. Unpack it on your machine, copy it into a sandbox with `promigence files put --recursive`, and keep the result with `promigence sandbox snapshot SID --alias NAME`. ## Check the move Runloop's guides for moving devboxes to Tensorlake, Modal and Freestyle start with a script that checks command execution and UTF-8 file round trips, then extend the checks with a validation plan for the workload ([Runloop transition guides](https://docs.runloop.ai/docs/transitions/overview), read 25 Oct 2026). Run the same checks on Promigence before you switch any traffic: 1. Commands: for a command that succeeds and for one that exits 7, the exit code matches and so does the output on both streams. 2. UTF-8 text: a file with non-ASCII characters reads back exactly as written. 3. Binary data: bytes with a NUL in them read back unchanged. 4. Modes and links: after `chmod 750` and `ln -s`, `stat -c %a` and `readlink` show the mode and the link you set. 5. Shell state: no environment variable or working directory carries over between commands. Pass `cwd` and `envs` where your Runloop code used a named shell. 6. User and paths: `id -un`, `echo $HOME` and `pwd` give what your code expects. On Runloop the default user is `user`, with its home at `/home/user`. 7. Pause and resume: a file written before a pause is there after the resume, and nothing your resume logic starts is running twice. 8. Snapshots: a sandbox started from a snapshot has the same files, the same modes and the same links. 9. Network: when you used a network policy, an allowed host answers and a host outside the list is refused. 10. Clean-up: `promigence sandbox list --state ready,running,paused` lists none of your test sandboxes, and the test snapshots are gone. This script runs checks 1 to 4 and checks 7 and 8 in one go, printing a line per check and exiting non-zero if any fails: ```python import asyncio import uuid from promigence import AsyncPromigence, AsyncSandbox async def main() -> None: token = uuid.uuid4().hex path = f"/tmp/transition-probe-{token}" text = f"transition probe {token}: café, naïve, 東京\n" checks: dict[str, bool] = {} async with AsyncPromigence() as client: sbx = await AsyncSandbox.create(client=client, spend_cap=1) try: r = await sbx.commands.run("printf 'stdout-probe\\n'; printf 'stderr-probe\\n' >&2") checks["command exit 0, stdout, stderr"] = (r.exit_code, r.stdout, r.stderr) == (0, "stdout-probe\n", "stderr-probe\n") r = await sbx.commands.run("exit 7", throw_on_exit=False) checks["command exit 7"] = r.exit_code == 7 await sbx.files.write(f"{path}.txt", text) checks["UTF-8 file round trip"] = await sbx.files.read(f"{path}.txt") == text data = b"binary\x00fixture" await sbx.files.write(f"{path}.bin", data) checks["binary file round trip"] = await sbx.files.read(f"{path}.bin", format="bytes") == data await sbx.commands.run(f"chmod 750 {path}.bin && ln -s {path}.bin {path}.link") manifest = f"stat -c %a {path}.bin && readlink {path}.link" r = await sbx.commands.run(manifest) checks["file mode and symlink"] = r.stdout == f"750\n{path}.bin\n" await sbx.pause() await sbx.resume() checks["files after pause and resume"] = await sbx.files.read(f"{path}.txt") == text snap = await client.sandboxes.snapshot(sbx.sandbox_id) copy = await AsyncSandbox.create(snap["snapshot_id"], client=client, spend_cap=1) try: checks["files in a sandbox started from the snapshot"] = await copy.files.read(f"{path}.txt") == text r = await copy.commands.run(manifest) checks["mode and symlink in that sandbox"] = r.stdout == f"750\n{path}.bin\n" finally: await copy.kill() await client.snapshots.delete(snap["snapshot_id"]) finally: await sbx.kill() for name, ok in checks.items(): print("PASS" if ok else "FAIL", name) raise SystemExit(0 if checks and all(checks.values()) else 1) asyncio.run(main()) ``` The same calls exist in the TypeScript SDK, under the names in the tables above. ## Prices Each column comes from that company's own pages, read on 25 Oct 2026: [Runloop pricing](https://runloop.ai/pricing) on one side; on the other, the Promigence [pricing section](https://www.promigence.ai/#pricing), [pricing page](https://www.promigence.ai/pricing) and [FAQ](https://www.promigence.ai/faq), with the build price from the [quickstart](https://www.promigence.ai/docs/quickstart), the paused rule from [Limits and notices](https://www.promigence.ai/docs/limits) and the storage rule from the [errors reference](https://www.promigence.ai/docs/errors). | | Runloop | Promigence | |---|---|---| | Billing | Usage billed separately from the plan, with no minimums; rates listed per hour and per second | Per second | | CPU | $0.108 per CPU-hour | $0.0504 per vCPU-hour | | Memory | $0.0252 per GB-hour | $0.0162 per GiB-hour | | The vendor's own example | "A standard 2-CPU / 4 GB devbox running 8 active hours per day costs approximately $2.73/day in compute" | "$0.17 an hour for a small sandbox (2 vCPU, 4 GB)" | | Building an environment | Blueprint builds at $0.252 an hour | Billed per second at the size's rate while the build runs, for at most an hour: $0.17 an hour at small | | Storage | Devbox storage at $0.00034236 per GB-hour; blueprint storage, snapshot storage and object storage at $0.000072 per GB-hour each; 100 GB free on Basic, 1 TB on Pro | Snapshot storage is included in every plan. Past your account's storage limit, a new snapshot is refused with `storage_limit_reached`, and nothing already stored is removed | | Suspended or paused | No compute or memory charges while suspended; storage charges continue | Not billed by the second while paused | | Plans | Basic: free, plus usage. Pro: $250 a month plus usage. Enterprise: contact sales | Free: $0, pay as you go. Pro: $50 a month. Max: $250 a month, or $500 at its higher level. Enterprise: custom. "Plans are set up with you by email." | | Free credit | A Pro trial with a "$50 Usage Credit", "No Credit Card Required" | "Every plan starts with $50 of free credit." | ## Help with the move Write to support@promigence.ai with what you run on Runloop today (the SDK and its version, your blueprints, snapshot sizes and network rules), and we will plan the move with you. The founder will help with your migration personally. ## Sources Every page below was read on 25 Oct 2026. Prices and features change, and each company's own page is the authority. | Company | Pages | Checked | |---|---|---| | Runloop | [Transition guides](https://docs.runloop.ai/docs/transitions/overview) and the notice on every docs page, [Quickstart](https://docs.runloop.ai/docs/tutorials/quickstart), [Execute commands](https://docs.runloop.ai/docs/devboxes/execute-commands), [Named shells](https://docs.runloop.ai/docs/devboxes/named-shells), [Files](https://docs.runloop.ai/docs/devboxes/files), [Snapshots](https://docs.runloop.ai/docs/devboxes/snapshots), [Lifecycle](https://docs.runloop.ai/docs/devboxes/lifecycle), [Lifetime management](https://docs.runloop.ai/docs/devboxes/start-stop), [Tunnels](https://docs.runloop.ai/docs/devboxes/tunnels), [Account secrets](https://docs.runloop.ai/docs/devboxes/configuration/account-secrets), [Network policies](https://docs.runloop.ai/docs/network-policies), [Sizes](https://docs.runloop.ai/docs/devboxes/configuration/sizes), [Architecture](https://docs.runloop.ai/docs/devboxes/configuration/devbox-architecture), [User profile](https://docs.runloop.ai/docs/devboxes/configuration/user-parameters), [Mounts](https://docs.runloop.ai/docs/devboxes/mounts/overview), [SSH](https://docs.runloop.ai/docs/devboxes/ssh), [Blueprints](https://docs.runloop.ai/docs/devboxes/blueprints/overview), [Dockerfile customization](https://docs.runloop.ai/docs/devboxes/blueprints/dockerfile-customization), [Devbox overview](https://docs.runloop.ai/docs/devboxes/overview), [Python SDK reference](https://runloopai.github.io/api-client-python/api/snapshot.html), [Pricing](https://runloop.ai/pricing) | 25 Oct 2026 | | Promigence | [Pricing section](https://www.promigence.ai/#pricing), [Pricing page](https://www.promigence.ai/pricing), [FAQ](https://www.promigence.ai/faq), [Quickstart](https://www.promigence.ai/docs/quickstart), [Limits and notices](https://www.promigence.ai/docs/limits), [Errors reference](https://www.promigence.ai/docs/errors), [CLI reference](https://www.promigence.ai/docs/cli) | 25 Oct 2026 | If anything on this page is out of date or wrong, write to support@promigence.ai and we will correct it and note the date.