# Promigence for AI agents

You are an AI agent reading www.promigence.ai. This page is for you: it says how to use Promigence on behalf of the
person you work for. People are welcome to read it too.

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.

A sandbox gives you your own computer to work in: run commands, install packages, edit files, start servers, and throw
it away when you are done. Nothing you do in it touches the person's machine.

## Set up

```bash
npm i -g promigence        # the CLI, with the TypeScript SDK in the same package (needs Node.js)
promigence login           # signs up or signs in through the browser, then saves an API key on this machine
promigence doctor          # checks the install, the key and the connection, and says how to fix each failure
```

- No browser where you run? `promigence login --no-browser` prints a URL. The person opens it, signs in, and pastes
  the code back to you.
- If the person already has an API key, read it from the environment: set `PROMIGENCE_API_KEY`, or store it with
  `promigence auth login --from-env PROMIGENCE_API_KEY`. Never put a key on a command line, where shell history and
  process listings keep it.
- No account yet? Create one in the browser with `promigence signup`, or the person can sign up at
  https://console.promigence.ai/signup?utm_source=agents&utm_medium=agent-briefing&utm_campaign=agents-page
- A new account's owner claims its free credit once, in the browser: `promigence credits claim` opens the page. Until
  then a run stops with `credit_unclaimed` (exit 5), and nothing starts or is charged.
- Once per session, run `promigence agent-guide`. It prints a short guide to the CLI, about 1,200
  tokens, written for agents. `--section commands`, `--section errors` and `--section cost` print the full lists.

## Check that everything works, in one command

```bash
promigence run --snapshot promigence/base --count 2 --cap 1 --json -- python3 -c 'print(6*7)'
```

This starts two sandboxes from the built-in `promigence/base` snapshot, runs the command in each, prints the result as
JSON and ends both sandboxes. `--cap 1` means the run can never cost more than one US dollar.

## CLI, MCP or SDK

- **CLI**, when you can run shell commands. Each command prints one JSON document when its output is not a terminal
  (`--json` forces it), and the exit codes below are a stable contract.
- **MCP**, when your harness speaks the Model Context Protocol. Add the server with
  `claude mcp add promigence -- promigence mcp` (on Windows, end it with `-- cmd /c promigence mcp`).
  `--read-only` offers only the tools that read; `--cap USD` sets the most each sandbox or batch it starts may spend.
  Sandboxes the session started end when the server stops, unless you pass `--keep`.
- **SDK**, inside a program: `npm i @promigence/sdk`. It has a native client for snapshots and runs, and a
  compatibility `Sandbox` class with the familiar `create`, `commands.run`, `files` and `kill` calls, so code
  written for the sandbox API many AI apps already use moves over with one import line and an API key.
  In Python, `pip install promigence` gives the same two parts: https://www.promigence.ai/docs/sdk-python

## Rules to work by

1. Always set a spend cap. `--cap` is in US dollars. A run whose quote is above it is refused before anything
   starts (exit 5). Ask the person before you raise a cap.
2. Read JSON and exit codes, not the human text. Every error carries a `code`, a `message` and a `fix`.
3. Pin what you build. Use `--commit` with a full 40-character SHA, or an image pinned with
   `promigence image resolve`. A snapshot built from a moving branch cannot be reproduced.
4. Keep secrets out of commands. Store one with `promigence secrets set NAME` (it reads an environment variable,
   a file or stdin) and hand it to sandboxes with `--secret NAME`. Never echo a secret into a command or a file.
5. End what you start. `promigence sandbox kill SID` stops the bill for that sandbox. A paused sandbox is not
   billed by the second, and `promigence sandbox autopause SID --after 5m` pauses it when it goes quiet.
6. Retry safely. Commands that start things accept `--idempotency-key K`: the same key within 24 hours returns
   the first result and starts nothing new.
7. Say whose failure it was. Exit 3 is an environment failure, the platform's and not the person's code. Report
   it as such, and do not count it against the task.

## How Promigence thinks

- **Snapshot.** A saved environment that passed its own check: an image, a Dockerfile, a `devcontainer.json`, a git
  repository or a local directory, with your setup steps run and your verify command exiting 0. A build whose verify
  command fails is not stored. A snapshot has an ID (`snap_…`) and can have an alias. `promigence/base` is built in,
  and `promigence templates` lists the other ready-made ones: languages, app starters, agent frameworks, benchmarks.
- **Sandbox.** An isolated computer started from a snapshot, with an ID (`SID`), a size, a timeout (15 minutes unless
  you set `--timeout`) and a running cost. It is billed by the second while it runs.
- **Fork.** Start any number of fresh, identical sandboxes from one snapshot at once:
  `promigence fork --count N`.
- **Run.** Sandboxes started together under one spend cap. It is priced before it starts (`run quote`) and ends with a
  validity report that keeps environment failures apart from task failures.
- **Saving your work.** `promigence sandbox snapshot SID` turns a running sandbox into a new snapshot, so later
  sandboxes start from that point.
- **Account.** An organization holds projects, and every API key belongs to one project. A project can have a monthly
  spend cap.

## Core operations

| To do this | Run |
|---|---|
| Start one sandbox | `promigence fork --snapshot promigence/base --count 1 --cap 1 --timeout 30m --json` |
| Start from a template | `promigence templates`, `promigence templates show NAME`, then `promigence fork --snapshot NAME --count 1 --cap 1` |
| Run a command in it | `promigence exec --sandbox SID -- sh -c "cd /work && npm test"` |
| Run a long command | `promigence exec --sandbox SID --background -- npm run build`, then `promigence exec output EXEC_ID --sandbox SID --follow` |
| Copy a file in | `promigence files put ./patch.diff /tmp/patch.diff --sandbox SID` |
| Copy a file out | `promigence files get /work/report.json ./report.json --sandbox SID` |
| List or search files | `promigence files ls /work --sandbox SID`, `promigence files search /work --contains TODO --sandbox SID` |
| Open a terminal | `promigence sandbox shell SID` |
| Save the sandbox as a snapshot | `promigence sandbox snapshot SID --alias my-env` |
| Build a snapshot of a repository | `promigence snapshot create --image node:22 --setup "..." --verify "npm test" --alias myapp --wait` |
| Price a run first | `promigence run quote --snapshot myapp --count 20 --timeout 15m` |
| Run a command in 20 copies | `promigence run --snapshot myapp --count 20 --cap 1 -- sh -c "cd /work/repo && npm test"` |
| Read the validity report | `promigence run report RUN_ID` |
| Pause and resume | `promigence sandbox pause SID`, `promigence sandbox resume SID` |
| Limit the network | `--network none`, or `--allow HOST` for an allow-list, on `fork` |
| Start a coding agent in a sandbox | `promigence agent start claude --key-from-env ANTHROPIC_API_KEY --repo URL --prompt "..."` (also `codex`, `opencode`) |
| End a sandbox | `promigence sandbox kill SID` |
| See the account, prices and service status | `promigence me`, `promigence pricing`, `promigence status` |

Every command has `promigence <command> --help`.

## Run CI jobs in sandboxes

**GitHub Actions.** Change one line of the workflow, then start the runner pool on any machine with the CLI:

```yaml
jobs:
  test:
    runs-on: promigence        # was: ubuntu-latest
```

```bash
GH_TOKEN=... promigence runners github --repo OWNER/REPO
```

`runs-on: promigence-medium` or `promigence-large` picks a bigger size, `--org ORG` takes the jobs of every
repository in an organization, and `--cap USD` sets the most one job may cost.

**GitLab CI.** `promigence runners gitlab` registers runners with the tags you gave them in GitLab, reading the
runner token from `GITLAB_RUNNER_TOKEN`. Jobs on that runner can read the token, so use it only for projects whose CI
code you trust.

## When something fails

| 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 |

- `promigence doctor` checks the install, the key and the connection; `promigence status` shows whether the service is
  up.
- `promigence run report RUN_ID --sandboxes failed` lists what failed and why; `--sandbox SID --repro` prints the
  command that reproduces one failure.
- `promigence sandbox info SID` shows a sandbox's state, time left, cost so far and the commands it ran.
- `promigence sandbox network SID` shows what the sandbox may reach and, under an allow-list, the hosts it was refused.
- Each error code, with its fix, is listed at https://www.promigence.ai/docs/errors

## Before destructive actions

Ask the person to confirm before you do any of these:

- Ending sandboxes. Files and running processes in them are gone: `sandbox kill`, `run kill`, `run cancel`, `exec kill`
- Deleting anything: `snapshot delete`, `files rm`, `secrets delete`, `project delete`, `org delete`
- Taking access away: `keys revoke`, `logout`, `org remove`, `org leave`, `project move` (revokes every key of the project)
- Cutting a sandbox off the network for good: `sandbox network SID --cut`
- Publishing a port. Anyone with the URL can reach it: `port expose`
- Raising or removing a spend limit: a higher `--cap`, `project cap PROJECT off`
- Starting anything billed while it waits: `runners github --warm N`, `runners gitlab --pool N`, `snapshot create --track` (every push rebuilds, billed per second)
- Saving a sandbox that was given a secret: `sandbox snapshot SID --force` (the snapshot can then contain the value)
- Money and membership: `billing card`, `org invite`, `org role`, `referrals apply`

## Reference

- Documentation: https://www.promigence.ai/docs (quickstart https://www.promigence.ai/docs/quickstart, limits https://www.promigence.ai/docs/limits, CLI https://www.promigence.ai/docs/cli, API
  https://www.promigence.ai/docs/reference/api, TypeScript SDK https://www.promigence.ai/docs/sdk, Python SDK https://www.promigence.ai/docs/sdk-python, errors https://www.promigence.ai/docs/errors)
- The docs for language models: https://www.promigence.ai/docs/llms.txt, and every docs page in one file: https://www.promigence.ai/docs/llms-full.txt
- Every page of this site as markdown: add `.md` to its address, for example https://www.promigence.ai/pricing.md
- Site index for language models: https://www.promigence.ai/llms.txt, and the whole site in one file: https://www.promigence.ai/llms-full.txt
- Structured facts: https://www.promigence.ai/facts.json
- Templates to start from, with what each has installed and the sizes you can pick: https://www.promigence.ai/templates.json
- API contract (OpenAPI): https://www.promigence.ai/openapi.json
- Prices: https://www.promigence.ai/#pricing, or `promigence pricing` for the live list
- Service status: `promigence status`
- Help: support@promigence.ai
- Sign up: https://console.promigence.ai/signup?utm_source=agents&utm_medium=agent-briefing&utm_campaign=agents-page