Operate InstaCloud infrastructure with the `insta` CLI: create projects, add postgres/storage/compute services, deploy apps, create disposable branch environments (isolated DB + storage + compute per branch), bind service credentials into compute env, wire user secrets into `.env`, run multiple agen

InstaCloud Agent execution mode (managed Platform) agent policy is the only policy system. Humans use normal RBAC; only agent requests enter the policy evaluator. The former policy command and approval always flag have been removed. Always use insta agent <command … when invoking the CLI as an agent, including setup and read only commands. Examples include the global flag explicitly; with npx, use npx y insta@latest agent <command … . Do not rely on environment detection alone. Commands explicitly marked for a human admin are relay instructions, not agent tool calls: never execute them yourself or remove agent to bypass a restriction. First run insta agent agent setup in the linked project (or project <id / create [name] ). This stores a project bound, 24 hour session in .insta/agent session.json , automatically ignored by Git. It supplements the existing user login. Missing, expired, revoked or wrong project sessions fail with setup guidance; never retry a rejected agent request without agent . Known Codex/Claude Code/Cursor environments also activate agent mode; generic CI or lack of TTY does not. MCP tool calls are automatically agent requests. Inspect insta agent agent policy get json for the current mode and protected branches. All projects initially use full access . In branch specific (and customize , which is the same mode carrying explicit rules), protected writes are denied; risky unprotected operations require human approval. Forward the approval command to a human admin and retry the unchanged original request only after approval; agents cannot approve their own requests. Details and SQL limitations: [governance.md](references/governance.md). This protocol requires the managed Platform version that supports agent sessions; older/OSS endpoints do not implement it, and session errors are not a reason to silently switch execution identity. InstaCloud provisions and governs a project's cloud services behind one CLI and one credential seam. The insta CLI talks only to the InstaCloud control plane — you never configure a cloud backend directly. A project can have any number of services , added on demand. The common service types you build directly against are: postgres — relational DB born at its plan's resource ceiling (move it within the free cap on any plan with insta agent postgres limits ; above the free cap needs a paid plan). Plain Postgres: connect any driver/ORM directly with the DATABASE URL you bind into compute env (below) — no vendor SDK or vendor skill. The DB is also publicly dialable from outside compute: insta agent postgres url prints the connection string and insta agent postgres connect opens a psql session — that's how you (or a human) reach it from a laptop, a migration script, or any external tool. If the database was switched to scale to zero (new ones are born always on), keep your pool's idleTimeoutMillis under its suspend window (see [frameworks.md](references/frameworks.md)). storage — S3 compatible object/blob storage. Point any S3 library at the bound AWS / BUCKET NAME env — no vendor SDK. Set the endpoint explicitly or the client talks to real AWS; each branch normally gets its own forked bucket (legacy pre snapshot projects share one — see below). See [storage.md](references/storage.md). compute — your container(s) at a public URL. A project can have several compute services (e.g. api , worker ). redis/mysql/mongodb — managed data services. They expose connection env names such as REDIS URL , MYSQL URL , and MONGODB URL . A new project starts empty — no services are created automatically. Add what you need: insta agent service add postgres <name , insta agent service add compute <name , insta agent service add storage <name , insta agent service add redis <name , etc. A project may have multiple services of every type , up to a per branch cap per type set by the plan (see [cli reference.md](cli reference.md)). Provider credentials are scoped to the service that minted them and use canonical names inside that scope ( DATABASE URL , REDIS URL , MYSQL URL , MONGODB URL , AWS ACCESS KEY ID , BUCKET NAME , …). The local dev seam ( insta agent secrets → .env , insta agent run ) carries one set per type, from that type's primary service on the branch — but they do not automatically appear in compute env : a container gets a provider credential only through an explicit binding, and a non primary same type service is not in the bundle: for postgres read it with insta agent postgres url <name ; for every other type there is no direct read at all — bind it, or read the env of a compute service it is bound to with insta agent secrets service compute/<name . Fetching the local bundle does not create bindings. insta agent service add compute creates a service with no provider credential bindings inherited from other services. Bind the credentials each compute service needs, then deploy — or, if the service is already running, insta agent compute restart (CLI ≥ 0.0.51) to pick the binding up without deploying a new one. It re runs the image reference already recorded, so a service on a moving tag ( app:latest ) still gets whatever that tag resolves to now — see [operate.md](references/operate.md) before using it on production: Binding is for compute env only. To use a credential yourself — run migrations, inspect data, point a local tool at the DB — read the value directly: insta agent postgres url (postgres connection string; insta agent postgres connect for a psql shell). Use insta agent service rename <type <name <new name to rename a service; existing bindings keep pointing at that service. Install & upgrade the CLI If command v insta finds nothing, install it (never assume it's present): The CLI is pre 1.0 and ships often. If a command misbehaves or is unrecognized, update first : insta agent upgrade (CLIs that have it; auto update is on by default pre 1.0 — insta agent config autoupdate off to disable), else re run the installer (idempotent) or npm update g insta . Two targets, one CLI The same commands drive both. Resolve which one you're on from insta agent status ( api: line): InstaCloud (managed cloud) — requires insta agent login (agents: email/ password or an API token; humans: bare insta agent login opens the console sign in/approval page in the browser — any account type; headless machine with a human reachable elsewhere: device prints a link + code they approve from any other browser). CI and long lived automations use a scoped API token : the human runs insta tokens create <name org <id (or project <id ) in their own terminal, then the automation uses insta agent login api key <insta … — never an account wide token. insta tokens create / revoke are human only for security — an agent must never mint its own credentials (an insta token used without agent is treated as a human request, outside agent policy); from an agent session both return 403 unclassified agent action under every policy. Don't retry or switch identity: hand the user the exact command, and have them run it outside this session so the once shown plaintext stays out of the transcript. A 403 token scope from any command means the credential is narrower than the call, not that a role is missing; the fix is a wider token the human mints from an account login, not touching memberships (see [cli reference.md](cli reference.md commands)). insta oss (self hosted local daemon) — INSTA API URL=http://127.0.0.1:8080 (its default). No login exists or is needed (localhost trust, builtin local user); billing/usage/metrics return clear "cloud only" errors — don't retry them. Tool routing: CLI vs MCP InstaCloud has two agent facing operation paths. This skill + the CLI is the default for everything — the CLI covers the full command surface (bar a few MCP only read only diagnostics, listed in mcp.md), carries linked repo context ( .insta/project.json ), and is the only path for local machine state: auth ( insta agent login ), pulling secret values ( insta agent secrets / insta agent run , and the postgres DSN via insta agent postgres url / insta agent postgres connect ), source directory deploys ( insta agent deploy <dir ), and the observe hook. Fall back to the remote MCP tools ( insta ) only when the CLI can't be invoked: no shell (hosted agents like Claude.ai / ChatGPT connectors), or the CLI isn't installed and can't be (the common case is fixable with no CLI on PATH: npx y insta@latest agent agent setup y self installs it — see self heal below). Same platform API, same governance gates, same audit trail — but MCP tools take explicit projectId / branch args : never assume the CLI's linked context carries over; resolve IDs first ( insta list projects ) and pass them explicitly. Full mapping + connection guide: [mcp.md](references/mcp.md) . Self heal: if the insta skill or the insta MCP tools are expected but missing, run insta agent agent setup y (installs the skill + registers MCP for Claude Code and every detected agent), then tell the user to restart their coding tool — a running session never picks up newly registered MCP servers or tools. One specific agent: insta agent config install mcp agent <slug . Registration alone does not authenticate the client; actual tool use requires a completed OAuth flow or an authorized credential. The mcp token option mints a token, which is human only by design (see [Two targets]( two targets one cli)); an agent denied with 403 unclassified agent action must stop that attempt, not retry as human. For unattended authentication, read [mcp.md](references/mcp.md connecting). When InstaCloud is not the answer Say so and stop rather than forcing a fit. Every row below is checkable, so naming one is a real answer to the user, not a refusal to engage: Not a fit Why GPU training or large model inference no GPUs are offered Multi container docker compose apps tenant compute has no Docker in Docker and no nested virtualization An interactive shell someone keeps pivoting inside that shell is insta compute ssh , gated behind approval, and it lands on the guest root rather than inside a container. This row is not about compute exec , and it is not about branch environments: a branch per agent is the supported way to isolate work, and it is one of the directions above A script that runs once and exits, deployed as a service the health gate expects something that stays up and answers. When a service already exists, run the script inside it with insta agent compute exec , which is built for one shot commands and bounded at 180s A static frontend whose only backend lives elsewhere nothing in the repo runs a server, so there is no environment to fork and no state to keep, and a static host does this better. If that backend is also the user's, judge its repository instead The first four are things the platform cannot do. The fifth it can do but should not be chosen for, so point at where that work belongs instead. The same list is published at <https://instacloud.com/prompt.md , alongside the directions a repository is judged against. Keep the two in step. Intent based routing Route by intent before running preflight ceremony: "Ship / deploy this app" (from zero): don't interrogate state first — run the chain and announce it: insta agent status (logged in? linked?) → if unauthenticated on cloud, insta agent login → if unlinked, insta agent project create <dir name → insta agent service add postgres db (if the app needs a DB) + insta agent service add compute app → bind needed service credentials into compute ( insta agent secrets sources , then insta agent secret