insta

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

InstaCloud

InstaCloud

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 — there are three service types you build directly against:
  • postgres — relational DB (autoscaling compute + read replicas). Plain Postgres: connect any driver/ORM directly with
    DATABASE_URL
    — no vendor SDK or vendor skill. 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.
  • compute — your container(s) at a public URL. A project can have several compute services (e.g.
    api
    ,
    worker
    ).
A new project starts empty — no services are created automatically. Add what you need:
insta services add postgres <name>
,
insta services add compute <name>
,
insta services add storage <name>
. A project may have multiple services of every type (up to 5 per type). Credentials are named per service:
DATABASE_URL_<NAME>
,
BUCKET_NAME_<NAME>
, … (service name upper-snaked); the oldest service of each type also gets the plain names (
DATABASE_URL
,
BUCKET_NAME
, …), so single-service projects work unchanged. Use
insta services rename <type> <name> <new-name>
to rename a service; platform-managed credential names are re-keyed to the new suffix.
InstaCloud 通过一个 CLI 和一套凭证体系,为项目提供并管控云服务。
insta
CLI 仅与 InstaCloud 控制平面通信——你无需直接配置云后端。项目可按需添加任意数量的服务,你可直接对接三种服务类型:
  • postgres — 关系型数据库(自动扩缩容计算资源 + 只读副本)。原生 Postgres:直接使用
    DATABASE_URL
    连接任意驱动/ORM——无需厂商SDK或专属技能。闲置时会自动缩容至零资源占用,因此请将连接池的
    idleTimeoutMillis
    设置在休眠窗口以内(详见 frameworks.md)。
  • storage — 兼容 S3 的对象/blob存储。
  • compute — 你的容器将部署到公网 URL。一个项目可拥有多个计算服务(例如
    api
    worker
    )。
新项目初始为空——不会自动创建任何服务。按需添加所需服务:
insta services add postgres <name>
insta services add compute <name>
insta services add storage <name>
。一个项目每种服务类型可拥有多个实例(最多5个)。凭证按服务命名:
DATABASE_URL_<NAME>
BUCKET_NAME_<NAME>
……(服务名称转为大写蛇形命名);每种类型中最早创建的服务还会使用无后缀的名称(
DATABASE_URL
BUCKET_NAME
……),因此单服务项目无需修改即可正常运行。使用
insta services rename <type> <name> <new-name>
重命名服务;平台管理的凭证名称会自动更新为新后缀。

Install & upgrade the CLI

安装与升级 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 <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 upgrade
(CLIs that have it; auto-update is on by default pre-1.0 —
insta autoupdate off
to disable), else re-run the installer (idempotent) or
npm update -g insta
.
如果
command -v insta
无输出,请安装 CLI(不要假设它已存在):
bash
curl -fsSL https://raw.githubusercontent.com/InsForge/insta-cli/main/install.sh | sh  # 原生二进制文件,无需 Node
npm install -g insta                                    # npm 替代方案
npx insta@latest <cmd>                                  # 一次性使用,始终调用最新版本(每次调用速度较慢)
当前 CLI 版本尚未达到1.0,更新频繁。如果命令运行异常或无法识别,请先更新
insta upgrade
(支持该命令的 CLI;1.0版本前默认开启自动更新——使用
insta autoupdate off
关闭),否则重新运行安装脚本(幂等操作)或执行
npm update -g insta

Two targets, one CLI

两种目标环境,一套 CLI

The same commands drive both. Resolve which one you're on from
insta status
(
api:
line):
  • InstaCloud (managed cloud) — requires
    insta login
    (agents:
    --email/--password
    or an API token; humans:
    --oauth github|google
    , opens a browser; 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.
同一套命令可用于两种环境。通过
insta status
api:
行判断当前所处环境:
  • InstaCloud(托管云) — 需要执行
    insta login
    (Agent:使用
    --email/--password
    或 API 令牌;人工用户:使用
    --oauth github|google
    ,会打开浏览器;无头机器可使用
    --device
    生成链接和验证码,由其他浏览器中的人工用户完成授权)。
  • insta-oss(自托管本地守护进程) — 默认地址为
    INSTA_API_URL=http://127.0.0.1:8080
    无需登录(基于本地信任,内置
    local
    用户);计费/使用情况/指标查询会返回明确的“仅云环境支持”错误——请勿重试此类操作。

Tool routing: MCP vs CLI

工具路由:MCP 与 CLI

InstaCloud has two agent-facing operation paths. Choose in this order:
  1. CLI for anything that needs local machine state: auth (
    insta login
    ), pulling secret values (
    insta secrets
    /
    insta run
    ), source-directory deploys (
    insta deploy <dir>
    ), the observe hook, and repo-linked context (
    .insta/project.json
    ).
  2. Remote MCP (
    insta_*
    tools, when connected) as the default for platform-scoped operations that don't need local files: discovery, services, branches, image deploys, metrics/logs/usage, governance. Structured JSON, same governance gates, same audit trail.
  3. No MCP connected → the CLI covers everything.
MCP tools take explicit
projectId
/
branch
args
— never assume the CLI's linked context carries over; resolve IDs first (e.g.
insta_project_list
, or
insta status --json
locally) and pass them explicitly. Full mapping + connection guide: mcp.md.
Self-heal: if the insta skill or the
insta_*
MCP tools are expected but missing, run
insta 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 mcp install --agent <slug>
.
InstaCloud 为Agent提供两种操作路径。按以下优先级选择:
  1. CLI:适用于需要本地机器状态的操作:认证(
    insta login
    )、拉取密钥
    insta secrets
    /
    insta run
    )、基于源码目录的部署(
    insta deploy <dir>
    )、观察钩子,以及仓库关联上下文(
    .insta/project.json
    )。
  2. 远程 MCP(连接后使用
    insta_*
    工具):默认用于无需本地文件的平台级操作:发现、服务、分支、镜像部署、指标/日志/使用情况、治理。返回结构化JSON,遵循相同治理规则,保留相同审计轨迹。
  3. 未连接 MCP → 使用 CLI 完成所有操作。
MCP 工具需要显式传入
projectId
/
branch
参数
——请勿假设 CLI 的关联上下文会自动继承;请先获取ID(例如本地执行
insta_project_list
insta status --json
)并显式传入。完整映射与连接指南:mcp.md
自我修复:如果缺少预期的 insta 技能或
insta_*
MCP 工具,请运行
insta setup agent -y
(安装技能并为 Claude Code 和所有检测到的Agent注册 MCP),然后告知用户重启编码工具——正在运行的会话无法识别新注册的 MCP 服务器或工具。为单个Agent安装:
insta 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 status
(logged in? linked?) → if unauthenticated on cloud,
insta login
→ if unlinked,
insta project create <dir-name>
insta services add postgres db
(if the app needs a DB) +
insta services add compute app
insta secrets
insta 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 login --oauth github
(browser) or
--email/--password
; then
insta 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. Never develop on
main
.
Anything else (configure, debug, inspect): light preflight, then the matching reference below.
在执行预检流程前先按意图进行路由:
"发布/部署此应用"(从零开始):无需先检查状态——直接执行以下流程并告知用户:
insta status
(已登录?已关联项目?)→ 如果在云环境中未认证,执行
insta login
→ 如果未关联项目,执行
insta project create <dir-name>
→ 如果应用需要数据库,执行
insta services add postgres db
+
insta services add compute app
insta secrets
insta deploy . --port <应用监听端口>
验证打印的URL可正常访问(见下文)。应用通过
process.env
读取凭证。
"设置/接入/注册":云环境 → 执行
insta login --oauth github
(浏览器授权)或
--email/--password
;然后执行
insta project create
。本地/oss环境 → 除守护进程外无需额外设置。
现有项目上的工作单元(功能开发、修复、实验、Agent任务):每个工作单元对应一个分支——见下文核心原则和 branching.md。请勿在
main
分支上开发。
其他操作(配置、调试、检查):执行轻量预检,然后参考下文对应的文档。

Preflight & context (before mutations)

预检与上下文(变更操作前)

bash
command -v insta                 # installed? (else: Install section)
insta 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
    ) over
    insta 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.
bash
command -v insta                 # 是否已安装?(未安装则参考安装章节)
insta status --json              # 目标API、登录状态、关联项目、当前分支
上述从零开始发布的流程已包含
status
步骤,因此无需重复执行此预检。
上下文规则(多Agent安全)
  • 关联信息(
    ./.insta/project.json
    按目录存储,包含当前分支信息。
  • 操作非自有分支时,优先使用显式的
    --branch <name>
    参数
    (适用于
    secrets
    deploy
    metrics
    logs
    events
    等命令),而非
    insta branch switch
    ——
    switch
    会修改共享的目录关联信息,可能导致同一检出目录中的并行Agent出现竞争。
  • 对于并行Agent,规则为1:1:1——任务 ↔ git worktree ↔ insta分支(每个worktree拥有独立的关联信息,因此在此环境下使用
    switch
    是安全的)。详见 branching.md

Core principle

核心原则

One unit of work = one branch = one isolated environment.
insta 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 → Parallel agents.
一个工作单元 = 一个分支 = 一个隔离环境
insta branch create <name>
会将父分支当前的服务实例化到新分支——包括CoW数据库分支(父分支数据的副本)、CoW分叉存储桶,以及每个计算服务的克隆(各自拥有独立URL),这些资源在分支创建时即完成创建,因此分支从一开始就是完整可运行的环境。 分支完全并行运行;彼此操作互不干扰。每个项目最多支持10个分支(硬性限制)。请勿在
main
分支上开发;请勿在一个分支上叠加多个功能。
同时处理多个独立功能(或Agent任务)? 为每个功能分配独立的分支和独立的子Agent——隔离的数据库+存储+计算+URL可确保零冲突。详见 branching.md → Parallel agents

Verify before reporting (deploys)

部署后验证(报告前)

Never report a deploy as successful from the command exiting alone.
insta 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. Scale-to-zero branches (the default) cold-start on the first request — allow a slow first hit (always-on services 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 (port mismatch and migration-gated startup account for most failures).
  4. Report the exact failing state — never claim success you didn't observe.
切勿仅根据命令执行成功就报告部署完成
insta deploy
成功时会打印分支URL——这仅表示平台已接受并完成机器部署,不代表应用可正常提供服务:
  1. 每隔约3秒轮询打印的URL(执行
    curl -s -o /dev/null -w '%{http_code}'
    ),最多等待约60秒。默认的缩容至零分支会在首次请求时冷启动——需允许首次请求较慢(始终在线服务可跳过此步骤;详见 references/operate.md)。
  2. 返回
    200
    (或应用预期的状态码)→ 部署完成;报告URL。
  3. 仍失败 → 参考 operate.md 中的有序排查列表(端口不匹配和迁移 gated 启动是最常见的失败原因)。
  4. 报告确切的失败状态——切勿声称未验证的成功。

Approval relay (CRITICAL — gated actions)

审批转发(关键—— gated 操作)

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 —
project.delete
requires approval by default). 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>
    (add
    --always
    to also stop future prompts for that action). 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 policy was set to allow (
    --always
    /
    insta policy set <action> allow
    ).
  • 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.
敏感操作受凭证边界管控(
secrets.read
secrets.write
deploy
project.delete
branch.delete
service.add/remove/scale/upgrade
;每个操作对应策略:允许/拒绝/需要审批——
project.delete
默认需要审批)。当命令返回**"需要审批"并附带审批ID**时:
  • 立即将完整信息转发给人工用户——包括确切的执行命令:
    insta approvals approve <id>
    (添加
    --always
    参数可停止未来该操作的审批提示)。请勿简化信息,请勿重试命令,未告知审批需求前切勿报告任务失败。仅管理员可完成审批。
  • 审批权限为一次性使用:审批通过后,重新运行原命令;除非将策略设置为允许(
    --always
    /
    insta policy set <action> allow
    ),否则下次执行该操作仍会触发审批提示。
  • 切勿绕过管控(例如手动修改状态或绕过CLI)——管控是产品的安全机制。
    deny
    策略为硬性禁止:报告该结果,请勿规避。

Common quick operations

常见快速操作

bash
insta status --json                          # target, login, link, current branch
insta manifest --json                        # agent-legible env view: every branch's services + URLs
insta services list --json                   # what exists on this project
insta run -- <cmd>                           # run with the branch bundle injected (NOTHING on disk; --branch <b>)
insta secrets --print                        # credential bundle for the current branch (--branch <b>)
insta secrets set NAME value                 # user config (project-wide; --branch for overrides)
insta deploy . --port 8080                   # build (Dockerfile) + deploy to the current branch
insta deploy --image <ref> --port 8080       # prebuilt image instead
insta branch create feat && insta branch list --json
insta logs compute --limit 100 --json        # runtime logs (--branch <b>; db is provider-limited)
insta metrics compute --json                 # service metrics
insta events --limit 50 --json               # audit + agent-event timeline
insta usage --json                           # cloud only (insta billing --json likewise)
insta approvals list --status pending        # outstanding gates
Use
--json
wherever you parse output.
bash
insta status --json                          # 目标环境、登录状态、关联信息、当前分支
insta manifest --json                        # Agent可读的环境视图:所有分支的服务+URL
insta services list --json                   # 当前项目已存在的服务
insta run -- <cmd>                           # 注入分支凭证包运行命令(无磁盘写入;可使用 --branch <b> 指定分支)
insta secrets --print                        # 当前分支的凭证包(可使用 --branch <b> 指定分支)
insta secrets set NAME value                 # 用户配置(项目级;可使用 --branch 指定分支覆盖)
insta deploy . --port 8080                   # 构建(Dockerfile)+ 部署到当前分支
insta deploy --image <ref> --port 8080       # 使用预构建镜像部署
insta branch create feat && insta branch list --json
insta logs compute --limit 100 --json        # 运行时日志(可使用 --branch <b> 指定分支;数据库日志受提供商限制)
insta metrics compute --json                 # 服务指标
insta events --limit 50 --json               # 审计+Agent事件时间线
insta usage --json                           # 仅云环境支持(insta billing --json 同理)
insta approvals list --status pending        # 待处理审批
解析输出时请尽量使用
--json
参数。

Routing

路由指南

For anything beyond the quick operations, load the reference that matches the intent — one is usually enough, two at most:
IntentReferenceCovers
Create or connect things ("set up", "new project", "add a database/compute")setup.mdCLI install/upgrade, cloud vs oss target, auth, project, services, ship-from-zero
Ship code or manage releasesdeploy.md · framework recipes: frameworks.mdimage vs source (remote build),
--port
semantics, secrets at runtime, verify procedure, Dockerfile templates, custom domains
Branch environments, parallel agents, promotion ("preview env", "sandbox per task", "merge to main")branching.mdthe data-forking env model (what actually clones), branch loop, 1:1:1 worktree pattern + dispatch brief, promotion, migration discipline
Approvals, policy, audit, credential scanninggovernance.mdgates catalog, the approval relay, events timeline, observe hook, agent audit patterns
Check health or debug failuresoperate.mdstatus/manifest triage, ordered deploy-failure list, metrics/logs, cloud-vs-oss differences
Command lookupcli-reference.mdthe full CLI catalog with flags and gates
Remote MCP tools ("connect a connector",
insta_*
tools available)
mcp.mdconnecting clients, tool ↔ CLI mapping, what stays CLI-only
If a request spans two areas ("deploy and check it's healthy"), load both and answer once.
对于快速操作之外的需求,加载与意图匹配的文档——通常一个文档足够,最多两个:
意图参考文档涵盖内容
创建或连接资源("设置"、"新项目"、"添加数据库/计算服务")setup.mdCLI安装/升级、云环境与oss环境对比、认证、项目、服务、从零开始发布
发布代码或管理版本deploy.md · 框架示例:frameworks.md镜像部署 vs 源码部署(远程构建)、
--port
语义、运行时密钥、验证流程、Dockerfile模板、自定义域名
分支环境、并行Agent、分支晋升("预览环境"、"每个任务专属沙箱"、"合并到main")branching.md数据分叉环境模型(实际克隆的资源)、分支生命周期、1:1:1 worktree模式与调度说明、分支晋升、迁移规范
审批、策略、审计、凭证扫描governance.md管控目录、审批转发流程、事件时间线、观察钩子、Agent审计模式
检查健康状态或调试失败operate.md状态/清单排查、部署失败有序列表、指标/日志、云环境与oss环境差异
命令查询cli-reference.md完整CLI命令目录,包含参数与管控规则
远程MCP工具("连接连接器"、
insta_*
工具可用)
mcp.md客户端连接、工具与CLI映射、仅CLI支持的操作
如果请求涉及两个领域("部署并检查健康状态"),加载对应两个文档并一次性回答。

Two non-negotiables (wherever you are)

两项不可协商规则(无论身处何种环境)

  • Prefer
    insta run -- <cmd>
    — 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.
  • When a file is genuinely needed, treat
    ./.env
    (from
    insta secrets
    ; auto-gitignored in git repos) as the only credential source — never hardcode or print secret values.
    DATABASE_URL
    + compute + storage (
    AWS_*
    /
    BUCKET_NAME
    ) are all per-branch (each branch copy-on-write-forks its parent's bucket; a legacy bucket created without snapshots stays shared — no isolation). User-set config belongs in
    insta secrets set <NAME>
    (project-wide) /
    --branch
    for branch overrides — never hand-edit
    .env
    values you want to persist; a redeploy re-injects the platform's view.
  • 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.
  • 优先使用
    insta run -- <cmd>
    ——每次调用都会获取凭证包并仅注入子进程环境;无磁盘写入,因此不会发生泄露或被提交。
  • 当确实需要文件时,仅将
    ./.env
    (来自
    insta secrets
    ;在git仓库中会自动被忽略)作为唯一凭证来源——切勿硬编码或打印密钥值。
    DATABASE_URL
    、计算服务、存储服务(
    AWS_*
    /
    BUCKET_NAME
    )均为分支专属(每个分支会对父分支的存储桶进行copy-on-write分叉;未启用快照的遗留存储桶仍为共享——无隔离性)。用户配置应存储在
    insta secrets set <NAME>
    (项目级)/ 使用
    --branch
    指定分支覆盖——切勿手动编辑
    .env
    中需要持久化的值;重新部署会重新注入平台管理的凭证。
  • 所有 schema 变更作为文件存储在
    migrations/
    目录下,以便在分支数据库和合并到
    main
    后的主数据库中重新执行。InstaCloud 从不合并数据库——仅迁移文件可同步schema变更。

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.
Billing is by actual app usage (vCPU·min / RAM GB·min actually consumed + storage + egress — not machine size × hours). Scale-to-zero is the default, so idle services cost nearly nothing;
always-on
(all plans:
insta compute always-on
,
insta db always-on
, or
--always-on
at create) trades a small continuous RAM cost for zero cold starts — see operate.md. The paid levers are the resource CEILING (
insta compute limits
,
insta db limits
— per-machine size, see operate.md) and machine COUNT (
insta services scale
— horizontal): free plans stay at the minimum of both and get a 403 —
insta billing upgrade
first;
insta usage
/
insta billing
show cycle usage and cost. One free org per user. Full flags in cli-reference.md.
管控机制与转发流程见上文;凭证审计观察钩子、事件时间线、Agent审计模式见 governance.md
计费基于实际应用使用量(实际消耗的vCPU·分钟 / RAM GB·分钟 + 存储 + 流量——而非机器规格×时长)。默认启用缩容至零,因此闲置服务几乎无成本;
always-on
(所有套餐支持:
insta compute always-on
insta db always-on
,或创建时使用
--always-on
参数)以少量持续RAM消耗换取零冷启动——详见 operate.md付费控制项为资源上限
insta compute limits
insta db limits
——单机器规格,详见 operate.md和机器数量
insta services scale
——水平扩缩容):免费套餐默认使用最低配置,超出会返回403——需先执行
insta billing upgrade
insta usage
/
insta billing
显示周期使用量和成本。每个用户可拥有一个免费组织。完整参数见 cli-reference.md

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.
对于运维工作,报告内容应包含:已执行操作(动作+范围:项目/分支/服务)、结果(URL、ID、观测到的状态——而非假设)、下一步操作(或任务已完成)。仅在有助于理解的情况下包含命令输出。