Insta

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. 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. It scales to zero when idle, so keep your pool's idleTimeoutMillis under the suspend window (see 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.
• compute — your container(s) at a public URL. A project can have several compute services (e.g. api, worker).
• redis/mysql/mongodb — managed Fly-backed 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 5 per type). 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>. Bind the credentials a 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 before using it on production:

insta --agent secrets sources                    # what's available to bind (--branch <b> targets another branch)
insta --agent secrets bind DATABASE_URL postgres/db --to compute/app
insta --agent secrets bind REDIS_URL redis/cache --source-name REDIS_URL --to compute/app
insta --agent secrets bind MYSQL_URL mysql/orders --source-name MYSQL_URL --to compute/app
insta --agent secrets bind MONGODB_URL mongodb/catalog --source-name MONGODB_URL --to compute/app
insta --agent deploy . --group app --port 8080

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

curl -fsSL https://raw.githubusercontent.com/InsForge/insta-cli/main/install.sh | sh  # native binary, no Node
npm install -g insta                                    # npm alternative
npx insta@latest --agent <cmd>                                  # one-shot, always newest (slow per call)

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).
• 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),