promigence 0.1.0-beta.12

package/llms.txt

@@ -0,0 +1,209 @@
+# Promigence — promigence@0.1.0-beta.12
+
+> Verified, reproducible, forkable execution environments for agents. The CLI is the
+> `promigence` command (package `promigence`, which is also the TypeScript SDK).
+
+## Index
+
+- `promigence login` — sign up or sign in (email; GitHub/Google where enabled); stores a new API key
+- `promigence signup` — create an account
+- `promigence logout` — forget this CLI's key (revoked when `promigence login` minted it)
+- `promigence auth login` — store an API key (--from-env VAR | stdin; never on argv)
+- `promigence keys list` — your org's API keys
+- `promigence keys create` — mint a key (secret printed once)
+- `promigence keys revoke` — revoke a key
+- `promigence org list` — your organizations (* = default)
+- `promigence org create` — create one you own (no trial credit)
+- `promigence org switch` — sign in, make ORG the default, store a key for it
+- `promigence org members` — members and roles
+- `promigence org invite` — invite an email (owners)
+- `promigence org invites` — pending invites (14-day expiry)
+- `promigence org uninvite` — revoke an invite (owners)
+- `promigence org resend` — send an invite again (owners)
+- `promigence org role` — set owner|member (owners)
+- `promigence org remove` — remove a member; their keys die (owners)
+- `promigence org leave` — leave an organization
+- `promigence org join` — accept an invite sent to you
+- `promigence org audit` — who did what (owners; needs --sign-in)
+- `promigence org rename` — rename it (owners)
+- `promigence org delete` — delete it; keys die (owners)
+- `promigence project list` — projects and their spend this month
+- `promigence project create` — create a project
+- `promigence project rename` — rename (not `default`)
+- `promigence project delete` — delete an empty one (owners)
+- `promigence project cap` — monthly USD cap, or off (owners)
+- `promigence project move` — to another org; keys die (owners)
+- `promigence me` — plan, concurrency in use, trial credit, spend, limits
+- `promigence billing card` — add a card: prints a checkout URL (trial credits kept)
+- `promigence doctor` — check client, auth and API
+- `promigence ping` — your distance to our servers
+- `promigence init` — write promigence.toml
+- `promigence examples` — what forks with no build (no auth)
+- `promigence templates` — the templates: ready-made starting points to fork (no auth)
+- `promigence templates show` — one template: everything it has installed, and its versions (no auth)
+- `promigence agent-guide` — ~1.4k-token guide for agents (--section commands|errors|cost)
+- `promigence mcp` — MCP server on stdio: `claude mcp add promigence -- promigence mcp` (Windows: `-- cmd /c promigence mcp`)
+- `promigence snapshot create` — build + verify a snapshot (--image | --dockerfile | --devcontainer)
+- `promigence snapshot status` — poll a build by build_id
+- `promigence snapshot list` — list snapshots in your org
+- `promigence snapshot inspect` — show a snapshot's record
+- `promigence snapshot verify` — re-verify a snapshot in a fork
+- `promigence snapshot export` — write a portable .promigence bundle (commit it, cite it, mail it)
+- `promigence image resolve` — resolve REF (python:3.12) to REF@sha256:… without a local container runtime
+- `promigence github connect` — connect GitHub in the console; waits for it
+- `promigence github status` — connected accounts, pending installs, tracked branches
+- `promigence github disconnect` — stop building from a GitHub account
+- `promigence github untrack` — stop rebuilding on push (the snapshot stays)
+- `promigence repos` — repos your GitHub/GitLab connection reads (for --repo)
+- `promigence gitlab connect` — connect GitLab read-only in the console; waits
+- `promigence gitlab status` — GitLab users, pending confirmations, tracks
+- `promigence gitlab disconnect` — revoke a GitLab connection
+- `promigence gitlab untrack` — stop rebuilding on commits (snapshot stays)
+- `promigence run` — fork N, exec CMD in each, print the validity report
+- `promigence run quote` — price a run before launch
+- `promigence run report` — validity report: env vs task failures
+- `promigence run status` — poll a run
+- `promigence run cancel` — stop queued starts
+- `promigence run kill` — kill every sandbox of a run
+- `promigence run replay` — replay sandboxes (client-triggered, never automatic)
+- `promigence run open` — reopen a failed sandbox as a live one, at the moment it failed
+- `promigence run captures` — what of this run is preserved, and when it expires
+- `promigence fork` — fork N sandboxes from a snapshot (--count --cap)
+- `promigence exec` — run CMD in a sandbox (--sandbox SID) or a run (--run ID --all)
+- `promigence exec output` — an exec's output by id (background x_…: --follow)
+- `promigence exec ps` — list a sandbox's background execs
+- `promigence exec stdin` — write to a background exec's stdin (needs `exec --background --stdin`)
+- `promigence exec kill` — signal a background exec (default SIGKILL)
+- `promigence files put` — copy a local file into a sandbox (--recursive: a directory)
+- `promigence files get` — copy a file out of a sandbox (--recursive: a directory)
+- `promigence files ls` — list a directory in a sandbox (lstat per entry)
+- `promigence files search` — find files by name glob and/or text inside them
+- `promigence files mkdir` — create a directory in a sandbox
+- `promigence files mv` — move or rename a path inside a sandbox
+- `promigence files cp` — copy a path inside a sandbox (both ends are in the sandbox)
+- `promigence files chmod` — change mode and/or owner of a path in a sandbox
+- `promigence agent start` — a coding agent in a new sandbox
+- `promigence sandbox kill` — kill one sandbox
+- `promigence sandbox network` — what it may reach; with an allow-list, hosts it was refused
+- `promigence sandbox shell` — interactive terminal (raw TTY, follows window size)
+- `promigence sandbox ssh` — log in over SSH (scp, sftp and -L work too)
+- `promigence port expose` — publish a port as a preview URL (anyone with it can reach it) (not on the hosted service yet)
+- `promigence port list` — list a sandbox's preview URLs (not on the hosted service yet)
+- `promigence port revoke` — take a preview URL down (a token, or every URL for a port) (not on the hosted service yet)
+- `promigence secrets set` — store secret NAME (env/file/stdin, never argv)
+- `promigence bench burst` — N sandboxes at once: hand-off percentiles + success rate
+- `promigence runners github` — GitHub Actions jobs in sandboxes: `runs-on: promigence` (until Ctrl-C)
+- `promigence runners gitlab` — GitLab CI jobs in sandboxes, as a runner with your tags (until Ctrl-C)
+- `promigence status` — services · your concurrency in use vs your limit
+- `promigence billing usage` — this month's spend: plan, usage by tier, credits, next invoice
+- `promigence billing history` — credits and payments, newest first (owners)
+- `promigence referrals` — your referral code, its offer, your referrals
+- `promigence referrals apply` — apply a code (owner, before the first paid invoice)
+- `promigence pricing` — your prices, live (list prices with no key)
+- `promigence credits` — your free-credit offer: state, credit, expiry, campaign
+- `promigence credits claim` — open the claim page (accept the terms in the browser); prints its URL
+- `promigence snapshot delete` — remove one of your snapshots (refused while a fork of it is alive)
+- `promigence sandbox list` — your sandboxes, newest first
+- `promigence sandbox pause` — park a sandbox: it bills no seconds and does not count against your limit
+- `promigence sandbox resume` — bring a paused sandbox back and restart its clock
+- `promigence sandbox snapshot` — snapshot it without stopping it
+- `promigence secrets list` — stored secret names (never a value)
+- `promigence secrets delete` — remove a stored secret
+- `promigence billing portal` — manage the card on file and past invoices: prints a portal URL
+- `promigence snapshot builds` — your builds, newest first (a rejected build keeps its reason)
+- `promigence snapshot alias` — name a snapshot, or clear its name (unique per org)
+- `promigence run list` — your runs, newest first
+- `promigence sandbox info` — one sandbox: state, tier, time left, cost so far, and its execs
+- `promigence sandbox extend` — give a live sandbox more time, within its run's quote and --cap (exit 5 past them)
+- `promigence sandbox autopause` — pause it once it has sat idle, or read the rule it is under
+- `promigence sandbox probe` — is this still the verified environment? (its recorded paths, or --path)
+- `promigence files rm` — delete a path in a sandbox
+
+- `promigence agent-guide` — this document's first section
+- `promigence agent-guide --section commands` — every command with its flags
+- `promigence agent-guide --section errors` — every error code and exit code
+- `promigence agent-guide --section cost` — tiers and per-second prices
+- https://promigence.ai
+
+---
+
+# Promigence — agent guide (promigence@0.1.0-beta.12)
+
+Promigence is an **environment runtime**: verified, reproducible, forkable execution
+environments, billed per second (vCPU + memory). The model is one line:
+
+    verify → snapshot → fork(N) → exec → validity report
+
+- **snapshot** — an image (pinned) + ordered `setup` steps + a `verify` command that, if given, must exit 0.
+  If verify fails nothing is stored; the build's own time is billed. A branch is not a pin.
+- **fork** — a warm copy of that workspace, with its `start` service ready;
+  N at once, each checked before you get it.
+- **validity report** — per sandbox, and this split is the product: **env** failures are ours
+  (exit 3, replayable; when our side shows the cause, the time since your last snapshot is
+  credited back, up to 24 h) and **task** failures are yours (exit 4, billed).
+
+## Golden path
+
+    promigence run --snapshot promigence/base --count 2 --cap 1 --json -- python3 -c 'print(6*7)'
+
+That forks 2 sandboxes of the built-in base, runs the command in each, prints the report and
+kills them. Find public snapshots with `promigence examples` (no API key needed).
+Build your own: `promigence init` in a repo prints the `snapshot create --image … --wait` to run.
+
+## Output contract
+
+Exactly one JSON document on stdout per invocation, whenever `--json` is passed or stdout is
+not a TTY; `exec --sandbox` needs `--json` for it:
+
+    {"schema":"promigence.cli/v1","command":…,"ok":…,
+     "error":{"code","message","fix","docs","guide"},"next":[{"cmd","why"}]}
+
+Progress, prices and diagnostics go to **stderr** — never parse them. `next[].cmd` is
+id-based, runnable verbatim (fill any UPPERCASE word); use it, never invent one.
+
+Exit codes: 0 ok · 1 internal · 2 usage · 3 env_failed · 4 task_failed · 5 spend_cap · 6 not_verified · 7 auth (auth, forbidden, setup_required, account_exists, invite_invalid, invite_required, key_expired, account_blocked) · 8 not_found · 9 unreachable · 10 rate_limited (rate_limited only: retry after Retry-After) · 11 timeout · 12 partial (some sandboxes cap_killed, stopped_by_support, expired, not_started) · 13 changes_pending (agent-guide --check: files would change) · 125 passthrough (exec --sandbox: ours; else the command's code) · 130 interrupted.
+Highest-precedence code wins: 2 > 5 > 6 > 7/8/9/10 > 11 > 3 > 12 > 4 > 1 > 0.
+
+## The seven you will actually hit
+
+(`{name}` in a fix is filled from the failure's evidence.)
+
+- `auth` (exit 7) — Set PROMIGENCE_API_KEY or run `promigence auth login --from-env VAR`. No key yet: `promigence login` (sign in) or https://promigence.ai.
+- `credit_unclaimed` (exit 5) — 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.
+- `not_found` (exit 8) — Check the id; aliases resolve in your org first, then public snapshots (`promigence examples`).
+- `not_verified` (exit 6) — Wait for the build: `promigence snapshot status {build_id} --wait`.
+- `cap_exceeded` (exit 5) — Raise `--cap`, lower `--count`/`--timeout`, or pass `--allow-partial` to launch what fits.
+- `timeout` (exit 11) — Run the id-based command: `{next}`.
+- `nonzero_exit` (exit 4) — The environment was verified; the command failed. Inspect: `promigence exec output {exec_id}`.
+
+## Limits and stops
+
+- `setup_required` (exit 7): answer the account's setup questions in the console first.
+- `egress_cap_reached` (exit 5): the month's data out is spent; `--network none` still starts; it resets on the 1st (UTC).
+- A paused sandbox is kept 30 days (`pause_expires_at`); resuming keeps it, else it is deleted (`expired`).
+- `stopped_by_support` (exit 12): support stopped it; the message says why.
+
+## Do
+
+- Pass `--cap USD` on every `fork`/`run`: a run over it is refused (exit 5) before anything starts.
+- Pass `--json`, and read `ok`, `error.code` and `next` — not the text.
+- Use `--wait`. **Every wait is bounded to 100s**: exit 11 means the wait expired and
+  **nothing was killed** — run the id-based `next` command to keep waiting.
+- Treat exit 3 as ours (re-run or `run replay`) and exit 4 as yours (fix the task).
+- Pass the full 40-character commit sha to `snapshot create`.
+
+## Don't
+
+- Never put a key or a secret on argv: `auth login` reads `--from-env VAR` or stdin, `secrets
+  set` also `--from-file P`. Secrets are given at run time, never baked in.
+- Don't poll in a loop — `--wait` long-polls server-side and costs one request.
+- Don't re-fork blindly on an env failure: `promigence run replay <run_id>` re-runs it.
+
+## More
+
+`promigence agent-guide --section commands|errors|cost` · `promigence agent-guide --code <code>`
+· `promigence <command> --help` · https://promigence.ai
+Same surface as MCP tools: `promigence mcp` (stdio; `claude mcp add promigence -- promigence mcp`).
+
+Live in v0.1.0-beta.12: login · signup · logout · auth login · keys list/create/revoke · org list/create/switch/members/invite/invites/uninvite/resend/role/remove/leave/join/audit/rename/delete · project list/create/rename/delete/cap/move · me · billing card/usage/history/portal · doctor · ping · init · examples · templates +show · agent-guide · mcp · snapshot create/status/list/inspect/verify/export/delete/builds/alias · image resolve · github connect/status/disconnect/untrack · repos · gitlab connect/status/disconnect/untrack · run +quote/report/status/cancel/kill/replay/open/captures/list · fork · exec +output/ps/stdin/kill · files put/get/ls/search/mkdir/mv/cp/chmod/rm · agent start · sandbox kill/network/shell/ssh/list/pause/resume/snapshot/info/extend/autopause/probe · secrets set/list/delete · bench burst · runners github/gitlab · status · referrals +apply · pricing · credits +claim
+Not on the hosted service yet: port expose/list/revoke (preview URLs).

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "promigence",
+  "version": "0.1.0-beta.12",
+  "description": "The fastest sandboxes for AI agents and code. Snapshot an environment once, fork it as often as you need, run commands in every copy, and get a report that tells environment failures from task failures. Billed per second, with a quote before a run and a hard spend cap. One package: the promigence command and the TypeScript SDK.",
+  "license": "Apache-2.0",
+  "homepage": "https://www.promigence.ai",
+  "bugs": {
+    "email": "support@promigence.ai",
+    "url": "https://www.promigence.ai/docs"
+  },
+  "author": "Promigence AI, Inc. <support@promigence.ai>",
+  "type": "module",
+  "bin": {
+    "promigence": "./dist/bin.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "llms.txt",
+    "README.md",
+    "NOTICE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "keywords": [
+    "promigence",
+    "sandbox",
+    "sandboxes",
+    "agents",
+    "ai-agents",
+    "code-execution",
+    "cli",
+    "sdk",
+    "evals",
+    "ci",
+    "snapshots",
+    "fork"
+  ]
+}