# openpouch

> openpouch 🦘 is agent-native hosting: an open-source CLI + MCP server that lets autonomous coding agents deploy an app to a live URL on openpouch's **own** infrastructure — one command, no account, no dashboard, no CAPTCHA. Governed lifecycle: policy gates before every action, human-only production approvals, durable deployment memory, automatic evidence in the repo, and a plain-language `summary` to relay to a (possibly non-technical) human. Optional bring-your-own adapters can target your own external provider instead, but the product is openpouch's own hosting — not a layer over other clouds.

Deploy in one command (no install, no account). A static site or an **already-built** folder:

    npx openpouch deploy

A framework app (React/Vite/Next/Svelte/…) — either build it first and deploy the output (fast, deterministic), or hand openpouch the source and let the box build it:

    npm run build && npx openpouch deploy dist     # build locally, deploy the output
    npx openpouch deploy .                          # or: ship the source — the box builds it (build-on-deploy)

(A bare `openpouch deploy` in an unbuilt frontend root is refused with the right folder to use; pass an explicit path.)

Facts any agent should know before deploying:

- Every CLI command supports `--json` (exactly one JSON object on stdout) and stable exit codes — any harness with a shell can drive it. The MCP server (stdio standard) exposes the same functions as 12 tools (including `openpouch_list` and `openpouch_delete` for self-service quota management).
- **Framework frontends — two ways.** Fast and deterministic: build first, then point deploy at the build directory — `npm run build`, then `npx openpouch deploy dist` (Vite→`dist/`, CRA→`build/`, Next static export→`out/`). Or hand openpouch the source and let the box build it: `npx openpouch deploy .` — **server-side build-on-deploy is shipped**, so a raw Vite/CRA/Svelte source folder (or a dynamic app with a build step) is built on the box and the output is served, no local build needed. A bare `openpouch deploy` (no path) in an unbuilt frontend root is refused with the right folder to use — pass an explicit path (`dist` or `.`) to proceed.
- **Static, or a real running app — and observable.** Besides static sites, openpouch runs real Node.js apps in a hardened container (Express/HTTP servers, JSON APIs, webhook receivers; `kind:"dynamic"`, scale-to-zero, WebSocket-capable). The runtime is debuggable: `openpouch logs` streams the captured install/build/app stdout+stderr (tagged `[install]`/`[build]`/`[app]`, ANSI-stripped), so you can see *why* a deploy is unhealthy and self-repair. **Honest limits today, so you advise your human correctly:** previews are ephemeral (~72h, claim → 7 days) and there are no custom domains yet. Env vars/secrets ARE supported for dynamic apps (`--var` / `--env-file`, injected at runtime, reported by name only, never written to disk), but they're ephemeral — they don't survive a container rebuild, and there's no persistent storage or secrets-at-rest yet. So it is built for demos, previews and agent-generated sites, not yet for payment-grade production (the managed paid lane on the roadmap closes these).
- Deploying needs no account; an optional openpouch API key (`OPENPOUCH_API_KEY` / `~/.openpouch/openpouch-run.key`, sent as a Bearer) lifts deploys into the human's account quota tier. Create one with `openpouch signup` (email or GitHub); check it with `openpouch whoami`. There is never a CAPTCHA or bot-wall on any surface — abuse is controlled with agent-compatible quotas, not human checks.
- There is deliberately NO approve tool and no agent-usable approve path: approving production actions is human-only (interactive terminal). If you receive `approval-required` with a request id, ask your human to run `openpouch approve <id>` in their own terminal.
- Deployment truth lives as files in the project repo and survives context loss: `deploy.manifest.json` (what/where), `deploy.policy.json` (what agents may do), `deploy.evidence.json` + `DEPLOYMENT.md` (what actually happened, incl. rollback anchors). Re-reading them is always sufficient to resume.
- Secret values never appear in any openpouch output, file, or tool result — env vars are reported by name and presence only.
- Every result carries a top-level plain-language `summary` written for the (often non-technical) human who runs you — relay it verbatim. The live URL is the primary result: on a successful deploy it's the top-level `url` field, ready to share.
- **Workflows, not just commands.** Two signature loops: *self-repair* — after a deploy, if the app is unhealthy (a failed `verify`, a non-200 app, or a `pending`/not-yet-live URL), run `openpouch logs`, fix the cause, redeploy, then `verify`, until it passes — never hand over a broken or still-`pending` URL; and *claim-to-keep* — instant previews are temporary (~72h), so relay the top-level `claimUrl` for your human to make one permanent. Full recipes are in the Workflows doc (link below).

## Links

- npm package: https://www.npmjs.com/package/openpouch
- Docs index: https://openpouch.dev/docs/INDEX.md
- CLI specification: https://openpouch.dev/docs/CLI.md
- MCP server (tool by tool): https://openpouch.dev/docs/MCP.md
- Harness integration (Claude Code, OpenClaw, Hermes, Codex, Cursor): https://openpouch.dev/docs/HARNESSES.md
- Workflows (happy-path, self-repair, build-then-deploy, claim-to-keep, production-approval, resume): https://openpouch.dev/docs/WORKFLOWS.md
- Accounts / API keys / quotas: https://openpouch.dev/docs/ACCOUNTS.md
- Instant lane (run-d API, static + dynamic): https://openpouch.dev/docs/INSTANT-LANE.md
- Data model (the three deploy files): https://openpouch.dev/docs/DATA-MODEL.md
- Source code (Apache-2.0): https://github.com/openpouch/openpouch