insta

---
name: insta
description: >
  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), schedule recurring
  HTTP calls (cron jobs) against a service or an external URL, bind service
  credentials into compute env, wire user secrets into `.env`, run multiple
  agents each in their own branch, handle governance
  approvals, check metrics/logs/usage, and promote branches to main. Use this
  skill when working in an InstaCloud-managed project (a `.insta/` dir or the
  `insta` CLI), when the user mentions InstaCloud or insta, AND when they ask to
  deploy an app, need a database/backend/object storage, want a scheduled or
  recurring task, want preview or
  per-agent sandbox environments, want branchable infrastructure, want to
  migrate an existing app in from Heroku / Railway / Fly / Render, or mention
  agent setup or MCP — even if they don't say "InstaCloud" explicitly. Also
  covers the insta-cloud remote MCP server (insta_* tools) and the self-hosted
  insta-oss runtime (same CLI, local daemon).
allowed-tools: Bash(insta:*), Bash(npx:*), Bash(curl:*), Bash(command:*), Bash(git:*), Bash(npm:*)
---

# 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
insta --agent secrets --print                        # the branch's secrets (--branch <b>, --service <compute/name>)
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                   # remote build (Dockerfile, or nixpacks on insta-compute) + deploy to the current branch
insta --agent deploy --image <ref> --port 8080       # prebuilt image instead
insta --agent compute connect-repo owner/repo app    # cloud-only; guides GitHub authorization and App access, then connects; or --public
insta --agent compute exec app -- printenv PORT      # one-shot command on live compute (no shell/stdin)
insta compute ssh app --setup                        # HUMANS ONLY: interactive shell via `ssh app.insta` (API keys refused; agents use `compute exec`)
insta --agent compute volume app --size 1Gi          # attach/grow persistent /data; mounts on next deploy or `compute restart`
insta --agent branch create feat && insta --agent branch list --json
insta --agent compute logs --limit 100 --json        # runtime logs (--branch <b>; also <postgres|redis|mysql|mongodb>; postgres is provider-limited)
insta --agent compute logs --since 2h --json         # time window (--from/--to too) — a windowless read is ONE page (~100 lines)
insta --agent compute metrics --json                 # service metrics (also <postgres|redis|mysql|mongodb>)
insta --agent agent events --limit 50 --json               # audit + agent-event timeline
insta --agent billing usage --json                           # cloud only (insta --agent billing --json likewise)
insta --agent 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 |
| Run something on a schedule ("every night", "cron job", "recurring task", "run this hourly") | [cli-reference.md](cli-reference.md#cron) | the `insta --agent cron` commands, UTC-only expressions, service vs external targets (the platform allows any service in the org; the CLI reaches the current branch's), the run-id idempotency contract, `--secret-ref` for credentials (resolved at send time, so rotation needs no edit), that an edit REPLACES the request rather than merging it, and what each run status means |
| 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 (a domain the user owns attaches as a subdomain such as `www`, and a bought domain's apex serves via `insta --agent domain delegate`) |
| Migrate an existing app in ("migrate my Render/Railway service to InstaCloud", "move off Heroku/Railway/Fly/Render", "import my app", "bring my app over") | [migrate.md](references/migrate.md) **plus** the one source file you need from `references/migrate/` (`render.md`, `railway.md`, `fly.md`, `insforge.md`) | the ordered cutover with pass conditions and its rollback boundary, the InstaCloud-side semantics that bite (a binding needs a deploy, no bulk env import, cron is HTTP-not-command, workers), command + addon mapping, per-source (each source now has its own file, read alongside migrate.md not instead of it) deltas |
| 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 |
| Take a postgres database off the internet, or connect compute to it privately ("private database", "close public access", `DATABASE_PRIVATE_URL`) | [operate.md → Postgres network access](references/operate.md#postgres-network-access) | `private-access on` mints `DATABASE_PRIVATE_URL` (InstaCloud compute only, not laptops/CI), rebinding, the impact preview before `public-access off`, the ~30s propagation, and that closing breaks external clients, CI and local dev |
| Let services call each other privately, or take a compute service / managed database off the internet ("internal URL", "service-to-service", "private only", `*.insta.internal`, `REDIS_PRIVATE_URL`) | [cli-reference.md → Private networking](cli-reference.md#private-networking) | every service's `<name>.insta.internal` address scoped to its branch (databases `<name>-<type>`), TCP+UDP any port, wake on private traffic, read `private_host` from `service list` rather than composing it, `public-access off` = private-only (403, no wake), databases' `*_PRIVATE_URL` and rebinding before closing |
| Check health or debug failures | [operate.md](references/operate.md) | status/manifest triage, ordered deploy-failure list, metrics/logs, cloud-vs-oss differences |
| Turn a project, or an image with no project, into a community template ("make this a template", "put this in the gallery", "publish it for others") | [cli-reference.md → Publishing a community template](cli-reference.md#publishing-a-community-template) | create a draft from the project (or a blank one, then add its services and variables with `template edit`), settle its variables, fill the tagline, category and README, check the publish requirements, and publish only after the person says yes (the template is public at once, with no review) |
| Command lookup | [cli-reference.md](cli-reference.md) | the full CLI catalog with flags and gates |
| Remote MCP tools ("connect a connector", `insta_*` tools available) | [mcp.md](references/mcp.md) | connecting clients, tool ↔ CLI mapping, what stays CLI-only |
| InstaCloud itself got in your way (bug, stale doc, missing feature, friction) | [cli-reference.md → Feedback](cli-reference.md#feedback) | `insta --agent feedback` / `insta_send_feedback`: when to file, situation → type mapping |

If a request spans two areas ("deploy and check it's healthy"), load both and answer once.

## Two non-negotiables (wherever you are)

- **Prefer `insta --agent run -- <cmd>`** for anything that needs the branch's secrets — the bundle is fetched per
  invocation and injected into the child environment only; nothing is written to disk, so nothing can
  leak or be committed. The bundle also carries the branch's **canonical** provider credentials —
  one set per type, from that type's primary service — so a local run reaches the database without
  binding anything. What a **compute service** receives is separate: bind with
  `insta --agent secrets bind`, then deploy (or `insta --agent compute restart` an already-running
  service, CLI ≥ 0.0.51 — a binding change never reaches a live machine on its own).
  **`run` REFUSES and exits 2 when several services define the same name** (CLI ≥ 0.0.65): nothing
  is spawned, and the names plus both ways forward print to stderr. Do not retry it as a transient
  failure — re-run with `--service <type>/<name>` for that service's env, or
  `--ignore-collisions` to proceed with those names removed from the child environment. Exit 2 is
  also the approval code, so read the stderr message to tell them apart.
- When a file is genuinely needed, treat `./.env` (from `insta --agent secrets`; auto-gitignored in git
  repos) as the **only** file-based source for secrets — it holds your user secrets and the
  branch's primary provider credentials — never hardcode or print secret
  values. `DATABASE_URL`, `AWS_*` / `BUCKET_NAME`, `REDIS_*`, `MYSQL_*`, and `MONGODB_*` are service
  credentials that reach production compute only through explicit `insta --agent secrets bind` rules. For
  direct use **outside** compute the sanctioned read is `insta --agent postgres url` / `insta --agent postgres connect`
  (postgres; gated `secrets.read`) — pipe it (`psql "$(insta --agent postgres url)"`), never paste the DSN into
  files or code. For every type, the branch's **primary** service's credentials are already in
  `insta --agent secrets` / `insta --agent run`. A **non-primary** service is not in the bundle:
  postgres has the `[service]` positional read above (`insta --agent postgres url <name>`), and **no other type has any direct read** — bind it,
  or read that service's own env with `insta --agent secrets --service compute/<name>`.
  User-set config belongs in `insta --agent secrets set <NAME>` (project-wide) / `--branch` for branch
  overrides — never hand-edit `.env` values you want to persist.
- Track **every** schema change as a file under `migrations/` so it replays on a branch DB and again
  on `main` after a merge. **InstaCloud never merges databases — only migration files carry schema forward.**
  Migrations run where the DB credentials are bound: on the compute service, via
  `insta --agent compute exec app -- <migrate-cmd>` (never as a startup gate — see
  [deploy.md](references/deploy.md)); or directly, with no compute involved:
  `psql "$(insta --agent postgres url --branch <b>)" -f migrations/<file>.sql` (explicit `--branch` — the bare
  form reads the linked branch's DB). Match `psql` / `pg_dump` / `pg_restore` to the server's
  Postgres major first — `pg_version` on `insta --agent service list --json --branch <b>` (same branch as
  the DSN); if the row has none, read the exact version instead (see
  [operate.md](references/operate.md)).

## Governance & audit (this is the platform's core differentiator)

The gate mechanics and the relay procedure are above; the observe credential-audit hook, the events
timeline, and agent audit patterns are in [governance.md](references/governance.md).

**Billing is by actual app usage** (vCPU·min / RAM GB·min actually consumed + storage + egress —
not machine size × hours). New compute services are born scale-to-zero: an idle service costs nearly
nothing at the price of a cold start, and inbound requests and outbound traffic both count as
activity, so an app doing outbound work stays up while it works. Always-on (`--always-on` at create,
or `insta --agent compute always-on on`) removes cold starts, and the idle app's resident RAM bills at
actual usage; a worker (`--port 0`) is always-on regardless. New databases (postgres included) are the
opposite: born always-on, so they bill resident memory while idle; `insta --agent postgres always-on off`
opts one into scale-to-zero after creation (the CLI can't choose it at create time for postgres yet) — see
[operate.md](references/operate.md). **The paid levers are the resource CEILING** (`insta --agent compute limits`,
`insta --agent postgres limits` — per-machine size, see [operate.md](references/operate.md))
**and replica CAP** (`insta --agent compute scale` — horizontal; scale-to-zero runs 1..cap on demand, always-on runs the cap): a new service is born at its plan's
ceiling and free plans may move within the free cap but not above it, and stay at one machine —
beyond either is a 403 — `insta --agent billing subscribe` first; `insta --agent billing usage` /
`insta --agent billing` show cycle usage and cost. One free org per user. Full flags in
[cli-reference.md](cli-reference.md).

## When InstaCloud itself gets in your way (feedback)

If you hit a hurdle that is **InstaCloud's fault** — a command that violates its documented
contract, skill/doc text that doesn't match reality, a missing capability, confusing UX — report
it with `insta --agent feedback` (or the `insta_send_feedback` MCP tool), **then continue the user's task with
a workaround**. Never block on the report, and **never file feedback for problems in the app the
user is building** — this channel is only for the InstaCloud toolkit
(`--component cli|mcp|platform|skills|docs`). The team replies in the console, where the user reads
and answers; **(CLI ≥ 0.1.7)** you only get the ticket's link and, on request, its status. Full flags and the
situation → type mapping: [cli-reference.md → Feedback](cli-reference.md#feedback).

## Response format

For operational work, report: **what was done** (action + scope: project/branch/service), **the
result** (URLs, IDs, observed status — not assumed), and **what's next** (or that it's complete).
Include command output only where it helps.