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](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: ```bash 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): ```bash 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). **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 secrets bind DATABASE_URL postgres/db --to compute/app`) → `insta --agent deploy . --port <the port the app listens on>` → **verify the printed URL serves** (below). The app reads `process.env` creds. For a portless insta-compute worker, first check that the installed CLI's `insta --agent service add --help` and `insta --agent deploy --help` advertise worker port zero before using `--port 0`. Otherwise use a template `type: worker` with a prebuilt image, or the [source-only listener fallback](references/deploy.md#workers-without-a-routed-port). Keep workers always-on. Portless deployments have no public URL; verify status/logs plus a completed job. **"Set up / onboard / sign up":** cloud → `insta --agent login` (browser sign-in; relay the printed link if no browser opens) or `--email/--password`; then `insta --agent project create`. Local/oss → nothing to set up beyond the daemon. **A unit of work on an existing project (feature, fix, experiment, agent task):** one branch per unit of work — see the core principle below and **[branching.md](references/branching.md)**. Never develop on `main`. **Anything else (configure, debug, inspect):** light preflight, then the matching reference below. ## Preflight & context (before mutations) ```bash command -v insta # installed? (else: Install section) insta --agent status --json # target api, login, linked project, current branch ``` Skip this ceremony for the ship-from-zero chain above — `status` is its first step already. **Context rules (multi-agent safety):** - The link (`./.insta/project.json`) is **per directory** and includes the current branch. - **Prefer explicit `--branch <name>`** on commands that accept it (`secrets`, `deploy`, `<type> metrics`, `<type> logs`, `agent events`, `postgres url` / `postgres connect` — a wrong-branch DSN means querying the wrong database) over `insta --agent branch switch` when acting on a branch you don't own — `switch` mutates the shared per-directory link and races parallel agents in the same checkout. - For parallel agents, the rule is **1:1:1 — task ↔ git worktree ↔ insta branch** (each worktree has its own link, so `switch` is safe there). See [branching.md](references/branching.md). ## Core principle **One unit of work = one branch = one isolated environment.** `insta --agent branch create <name>` materializes the **parent branch's** current services onto the new branch — a CoW database branch (copy of the parent's data), a CoW-forked storage bucket, and a clone of every compute service (own URL each), created **at branch-create**, so a branch is a complete runnable environment from the start. Branches run fully in parallel; nothing one does touches another. **≤10 branches per project (hard limit).** Don't develop on `main`; don't pile multiple features on one branch. **Multiple independent features (or agent tasks) at once?** Give each its own branch **and its own subagent** — isolated DB + storage + compute + URLs mean zero collision. See **[branching.md](references/branching.md) → Parallel agents**. ## Verify before reporting (deploys) **Never report a deploy as successful from the command exiting alone.** `insta --agent deploy` prints the branch URL on success — that means the platform accepted and rolled the machine, not that the app serves: 1. Poll the printed URL (`curl -s -o /dev/null -w '%{http_code}'`) every ~3s for up to ~60s. New compute services are born scale-to-zero, so an idle service cold-starts on the first request — allow a slow first hit. One created with `--always-on` (or switched on with `insta --agent compute always-on on`) skips this; see references/operate.md. 2. `200` (or the app's expected status) → deployed; report the URL. 3. Still failing → the ordered triage list in [operate.md](references/operate.md) (port mismatch and migration-gated startup account for most failures). 4. Report the exact failing state — never claim success you didn't observe. ## Approval relay (CRITICAL — gated actions) Sensitive actions are gated at the credential boundary (`secrets.read`, `secrets.write`, `deploy`, `project.delete`, `branch.delete`, `service.add/remove/scale/upgrade`, `domain.purchase`, `domain.delegate`, `zone.delegate`; policy per action: allow/deny/approve, using the project's agent policy). When a command returns **"approval required" with an approval id**: - **Relay it to the human immediately and verbatim** — the exact line to run: `insta agent approvals approve <id>` in a human terminal. Approvals authorize only one exact request. Don't summarize it away, don't retry the command, and don't report the task as failed without surfacing the approval first. Only an **admin** can approve. - Grants are **single-use**: after approval, **re-run the original command**; the next occurrence prompts again unless a human explicitly changes the applicable `agent policy` rule. - **Never work around a gate** (e.g. by hand-editing state or bypassing the CLI) — the gate is the product's safety model. A `deny` policy is a hard no: report it, don't circumvent it. ## Common quick operations ```bash insta --agent status --json # target, login, link, current branch insta --agent agent manifest --json # agent-legible env view: every branch's services + URLs insta --agent service list --json # what exists on this project insta --agent run -- <cmd> # run with the branch bundle injected (NOTHING on disk; --branch <b>) insta --agent run --service compute/app -- <cmd> # one service's own env — needed when several define the same name insta --agent run --ignore-collisions -- <cmd> # run anyway; every colliding name is REMOVED from the child env