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#

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#

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#

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:

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

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#

• 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