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 setup agent` 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_developer`, 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 db 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 db url` prints the connection string and `insta --agent db 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](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 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 services add postgres <name>`, `insta --agent services add compute <name>`, `insta --agent services add storage <name>`, `insta --agent services 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`, …). They do **not** automatically appear in `insta --agent secrets`, `insta --agent run`, or compute env. 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](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 db url` (postgres connection string; `insta --agent db connect` for a psql shell). Use `insta --agent services 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 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`), pulling secret **values** (`insta --agent secrets` / `insta --agent run`, and the postgres DSN via `insta --agent db url` / `insta --agent db 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 setup agent -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_project_list`) 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 setup agent -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 mcp install --agent <slug>`. ## 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 services add postgres db` (if the app needs a DB) + `insta --agent services 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. **"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`, `metrics`, `logs`, `events`, `db url` / `db 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. A scale-to-zero service (created with `--no-always-on`, or switched off with `insta --agent compute always-on off`) cold-starts on the first request — allow a slow first hit. New compute services are born always-on (since 2026-09-07) and skip 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`; 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 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 manifest --json # agent-legible env view: every branch's services + URLs insta --agent services list --json # what exists on this project insta --agent run -- <cmd> # run with user-defined secrets injected (NOTHING on disk; --branch <b>) insta --agent secrets --print # user-defined secrets for the current branch (--branch <b>) insta --agent secrets sources --json # provider credential sources available to bind insta --agent secrets bind DATABASE_URL postgres/db --to compute/app insta --agent secrets bindings --target compute/app --json insta --agent secrets set NAME value # user config (project-wide; --branch for overrides) insta --agent build . --port 8080 # local pre-deploy build/readiness check insta --agent deploy . --port 8080 # build (Dockerfile) + deploy to the current branch insta --agent deploy --image <ref> --port 8080 # prebuilt image instead insta --agent compute exec app -- printenv PORT # one-shot command on live compute (no shell/stdin) insta --agent compute volume app --size 1Gi # attach/grow persistent /data; mounts on next deploy insta --agent branch create feat && insta --agent branch list --json insta --agent logs compute --limit 100 --json # runtime logs (--branch <b>; also redis|mysql|mongodb; db is provider-limited) insta --agent logs compute --since 2h --json # time window (--from/--to too) — a windowless read is ONE page (~100 lines) insta --agent metrics compute --json # service metrics (also redis|mysql|mongodb) insta --agent events --limit 50 --json # audit + agent-event timeline insta --agent usage --json # cloud only (insta --agent billing --json likewise) insta --agent approvals list --status pending # outstanding gates ``` Use `--json` wherever you parse output. ## Routing For anything beyond the quick operations, load the reference that matches the intent — one is usually enough, two at most: | Intent | Reference | Covers | | --- | --- | --- | | Create or connect things ("set up", "new project", "add a database/compute") | [setup.md](references/setup.md) | CLI install/upgrade, cloud vs oss target, auth, project, services, ship-from-zero | | Ship code or manage releases | [deploy.md](references/deploy.md) · framework recipes: [frameworks.md](references/frameworks.md) | image vs source (remote build), `--port` semantics, explicit service credential binding, secrets at runtime, verify procedure, Dockerfile templates, custom domains | | Branch environments, parallel agents, promotion ("preview env", "sandbox per task", "merge to main") | [branching.md](references/branching.md) | **the data-forking env model** (what actually clones), branch loop, 1:1:1 worktree pattern + dispatch brief, promotion, migration discipline | | Approvals, policy, audit, credential scanning | [governance.md](references/governance.md) | gates catalog, the approval relay, events timeline, observe hook, agent audit patterns | | Check health or debug failures | [operate.md](references/operate.md) | status/manifest triage, ordered deploy-failure list, metrics/logs, cloud-vs-oss differences | | Command lookup | [cli-reference.md](cli-reference.md) | the full CLI catalog with flags and gates |