insta
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseInstaCloud
InstaCloud
InstaCloud provisions and governs a project's cloud services behind one CLI and one credential
seam. The 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:
insta- postgres — relational DB (autoscaling compute + read replicas). Plain Postgres: connect
any driver/ORM directly with — no vendor SDK or vendor skill. It scales to zero when idle, so keep your pool's
DATABASE_URLunder the suspend window (see frameworks.md).idleTimeoutMillis - 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:
, ,
. A project may have multiple services of every type (up to
5 per type). Credentials are named per service: , , …
(service name upper-snaked); the oldest service of each type also gets the plain names
(, , …), so single-service projects work unchanged.
Use to rename a service; platform-managed
credential names are re-keyed to the new suffix.
insta services add postgres <name>insta services add compute <name>insta services add storage <name>DATABASE_URL_<NAME>BUCKET_NAME_<NAME>DATABASE_URLBUCKET_NAMEinsta services rename <type> <name> <new-name>InstaCloud 通过一个 CLI 和一套凭证体系,为项目提供并管控云服务。 CLI 仅与 InstaCloud 控制平面通信——你无需直接配置云后端。项目可按需添加任意数量的服务,你可直接对接三种服务类型:
insta- postgres — 关系型数据库(自动扩缩容计算资源 + 只读副本)。原生 Postgres:直接使用 连接任意驱动/ORM——无需厂商SDK或专属技能。闲置时会自动缩容至零资源占用,因此请将连接池的
DATABASE_URL设置在休眠窗口以内(详见 frameworks.md)。idleTimeoutMillis - storage — 兼容 S3 的对象/blob存储。
- compute — 你的容器将部署到公网 URL。一个项目可拥有多个计算服务(例如 、
api)。worker
新项目初始为空——不会自动创建任何服务。按需添加所需服务:、、。一个项目每种服务类型可拥有多个实例(最多5个)。凭证按服务命名:、……(服务名称转为大写蛇形命名);每种类型中最早创建的服务还会使用无后缀的名称(、……),因此单服务项目无需修改即可正常运行。使用 重命名服务;平台管理的凭证名称会自动更新为新后缀。
insta services add postgres <name>insta services add compute <name>insta services add storage <name>DATABASE_URL_<NAME>BUCKET_NAME_<NAME>DATABASE_URLBUCKET_NAMEinsta services rename <type> <name> <new-name>Install & upgrade the CLI
安装与升级 CLI
If finds nothing, install it (never assume it's present):
command -v instabash
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:
(CLIs that have it; auto-update is on by default pre-1.0 —
to disable), else re-run the installer (idempotent) or .
insta upgradeinsta autoupdate offnpm update -g insta如果 无输出,请安装 CLI(不要假设它已存在):
command -v instabash
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,更新频繁。如果命令运行异常或无法识别,请先更新:(支持该命令的 CLI;1.0版本前默认开启自动更新——使用 关闭),否则重新运行安装脚本(幂等操作)或执行 。
insta upgradeinsta autoupdate offnpm update -g instaTwo targets, one CLI
两种目标环境,一套 CLI
The same commands drive both. Resolve which one you're on from ( line):
insta statusapi:- InstaCloud (managed cloud) — requires (agents:
insta loginor an API token; humans:--email/--password, opens a browser; headless machine with a human reachable elsewhere:--oauth github|googleprints a link + code they approve from any other browser).--device - insta-oss (self-hosted local daemon) — (its default). No login exists or is needed (localhost trust, builtin
INSTA_API_URL=http://127.0.0.1:8080user); billing/usage/metrics return clear "cloud-only" errors — don't retry them.local
同一套命令可用于两种环境。通过 的 行判断当前所处环境:
insta statusapi:- InstaCloud(托管云) — 需要执行 (Agent:使用
insta login或 API 令牌;人工用户:使用--email/--password,会打开浏览器;无头机器可使用--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:
- CLI for anything that needs local machine state: auth (), pulling secret values (
insta login/insta secrets), source-directory deploys (insta run), the observe hook, and repo-linked context (insta deploy <dir>)..insta/project.json - Remote MCP (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.
insta_* - No MCP connected → the CLI covers everything.
MCP tools take explicit / args — never assume the CLI's linked context
carries over; resolve IDs first (e.g. , or locally) and
pass them explicitly. Full mapping + connection guide: mcp.md.
projectIdbranchinsta_project_listinsta status --jsonSelf-heal: if the insta skill or the MCP tools are expected but missing, run
(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_*insta setup agent -yinsta mcp install --agent <slug>InstaCloud 为Agent提供两种操作路径。按以下优先级选择:
- CLI:适用于需要本地机器状态的操作:认证()、拉取密钥值(
insta login/insta secrets)、基于源码目录的部署(insta run)、观察钩子,以及仓库关联上下文(insta deploy <dir>)。.insta/project.json - 远程 MCP(连接后使用 工具):默认用于无需本地文件的平台级操作:发现、服务、分支、镜像部署、指标/日志/使用情况、治理。返回结构化JSON,遵循相同治理规则,保留相同审计轨迹。
insta_* - 未连接 MCP → 使用 CLI 完成所有操作。
MCP 工具需要显式传入 / 参数——请勿假设 CLI 的关联上下文会自动继承;请先获取ID(例如本地执行 或 )并显式传入。完整映射与连接指南:mcp.md。
projectIdbranchinsta_project_listinsta status --json自我修复:如果缺少预期的 insta 技能或 MCP 工具,请运行 (安装技能并为 Claude Code 和所有检测到的Agent注册 MCP),然后告知用户重启编码工具——正在运行的会话无法识别新注册的 MCP 服务器或工具。为单个Agent安装:。
insta_*insta setup agent -yinsta 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: (logged in? linked?) → if unauthenticated on cloud, → if
unlinked, → (if the app needs a
DB) + → → → verify the printed URL serves (below). The app reads creds.
insta statusinsta logininsta project create <dir-name>insta services add postgres dbinsta services add compute appinsta secretsinsta deploy . --port <the port the app listens on>process.env"Set up / onboard / sign up": cloud → (browser) or
; then . Local/oss → nothing to set up beyond the daemon.
insta login --oauth github--email/--passwordinsta project createA 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 .
mainAnything else (configure, debug, inspect): light preflight, then the matching reference below.
在执行预检流程前先按意图进行路由:
"发布/部署此应用"(从零开始):无需先检查状态——直接执行以下流程并告知用户:(已登录?已关联项目?)→ 如果在云环境中未认证,执行 → 如果未关联项目,执行 → 如果应用需要数据库,执行 + → → → 验证打印的URL可正常访问(见下文)。应用通过 读取凭证。
insta statusinsta logininsta project create <dir-name>insta services add postgres dbinsta services add compute appinsta secretsinsta deploy . --port <应用监听端口>process.env"设置/接入/注册":云环境 → 执行 (浏览器授权)或 ;然后执行 。本地/oss环境 → 除守护进程外无需额外设置。
insta login --oauth github--email/--passwordinsta project create现有项目上的工作单元(功能开发、修复、实验、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 branchSkip this ceremony for the ship-from-zero chain above — is its first step already.
statusContext rules (multi-agent safety):
- The link () is per directory and includes the current branch.
./.insta/project.json - Prefer explicit on commands that accept it (
--branch <name>,secrets,deploy,metrics,logs) overeventswhen acting on a branch you don't own —insta branch switchmutates the shared per-directory link and races parallel agents in the same checkout.switch - For parallel agents, the rule is 1:1:1 — task ↔ git worktree ↔ insta branch (each worktree has
its own link, so is safe there). See branching.md.
switch
bash
command -v insta # 是否已安装?(未安装则参考安装章节)
insta status --json # 目标API、登录状态、关联项目、当前分支上述从零开始发布的流程已包含 步骤,因此无需重复执行此预检。
status上下文规则(多Agent安全):
- 关联信息()按目录存储,包含当前分支信息。
./.insta/project.json - 操作非自有分支时,优先使用显式的 参数(适用于
--branch <name>、secrets、deploy、metrics、logs等命令),而非events——insta branch switch会修改共享的目录关联信息,可能导致同一检出目录中的并行Agent出现竞争。switch - 对于并行Agent,规则为1:1:1——任务 ↔ git worktree ↔ insta分支(每个worktree拥有独立的关联信息,因此在此环境下使用 是安全的)。详见 branching.md。
switch
Core principle
核心原则
One unit of work = one branch = one isolated environment.
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 ; don't pile multiple features on one branch.
insta branch create <name>mainMultiple 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.
一个工作单元 = 一个分支 = 一个隔离环境。 会将父分支当前的服务实例化到新分支——包括CoW数据库分支(父分支数据的副本)、CoW分叉存储桶,以及每个计算服务的克隆(各自拥有独立URL),这些资源在分支创建时即完成创建,因此分支从一开始就是完整可运行的环境。
分支完全并行运行;彼此操作互不干扰。每个项目最多支持10个分支(硬性限制)。请勿在 分支上开发;请勿在一个分支上叠加多个功能。
insta branch create <name>main同时处理多个独立功能(或Agent任务)? 为每个功能分配独立的分支和独立的子Agent——隔离的数据库+存储+计算+URL可确保零冲突。详见 branching.md → Parallel agents。
Verify before reporting (deploys)
部署后验证(报告前)
Never report a deploy as successful from the command exiting alone. prints the
branch URL on success — that means the platform accepted and rolled the machine, not that the app
serves:
insta deploy- Poll the printed URL () 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).
curl -s -o /dev/null -w '%{http_code}' - (or the app's expected status) → deployed; report the URL.
200 - Still failing → the ordered triage list in operate.md (port mismatch and migration-gated startup account for most failures).
- Report the exact failing state — never claim success you didn't observe.
切勿仅根据命令执行成功就报告部署完成。 成功时会打印分支URL——这仅表示平台已接受并完成机器部署,不代表应用可正常提供服务:
insta deploy- 每隔约3秒轮询打印的URL(执行 ),最多等待约60秒。默认的缩容至零分支会在首次请求时冷启动——需允许首次请求较慢(始终在线服务可跳过此步骤;详见 references/operate.md)。
curl -s -o /dev/null -w '%{http_code}' - 返回 (或应用预期的状态码)→ 部署完成;报告URL。
200 - 仍失败 → 参考 operate.md 中的有序排查列表(端口不匹配和迁移 gated 启动是最常见的失败原因)。
- 报告确切的失败状态——切勿声称未验证的成功。
Approval relay (CRITICAL — gated actions)
审批转发(关键—— gated 操作)
Sensitive actions are gated at the credential boundary (, , ,
, , ; policy per action:
allow/deny/approve — requires approval by default). When a command returns
"approval required" with an approval id:
secrets.readsecrets.writedeployproject.deletebranch.deleteservice.add/remove/scale/upgradeproject.delete- Relay it to the human immediately and verbatim — the exact line to run:
(add
insta approvals approve <id>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.--always - 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 policy is a hard no: report it, don't circumvent it.
deny
敏感操作受凭证边界管控(、、、、、;每个操作对应策略:允许/拒绝/需要审批—— 默认需要审批)。当命令返回**"需要审批"并附带审批ID**时:
secrets.readsecrets.writedeployproject.deletebranch.deleteservice.add/remove/scale/upgradeproject.delete- 立即将完整信息转发给人工用户——包括确切的执行命令:(添加
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 gatesUse wherever you parse output.
--jsonbash
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 # 待处理审批解析输出时请尽量使用 参数。
--jsonRouting
路由指南
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 | CLI install/upgrade, cloud vs oss target, auth, project, services, ship-from-zero |
| Ship code or manage releases | deploy.md · framework recipes: frameworks.md | image vs source (remote build), |
| Branch environments, parallel agents, promotion ("preview env", "sandbox per task", "merge to main") | 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 | gates catalog, the approval relay, events timeline, observe hook, agent audit patterns |
| Check health or debug failures | operate.md | status/manifest triage, ordered deploy-failure list, metrics/logs, cloud-vs-oss differences |
| Command lookup | cli-reference.md | the full CLI catalog with flags and gates |
Remote MCP tools ("connect a connector", | mcp.md | connecting 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.md | CLI安装/升级、云环境与oss环境对比、认证、项目、服务、从零开始发布 |
| 发布代码或管理版本 | deploy.md · 框架示例:frameworks.md | 镜像部署 vs 源码部署(远程构建)、 |
| 分支环境、并行Agent、分支晋升("预览环境"、"每个任务专属沙箱"、"合并到main") | branching.md | 数据分叉环境模型(实际克隆的资源)、分支生命周期、1:1:1 worktree模式与调度说明、分支晋升、迁移规范 |
| 审批、策略、审计、凭证扫描 | governance.md | 管控目录、审批转发流程、事件时间线、观察钩子、Agent审计模式 |
| 检查健康状态或调试失败 | operate.md | 状态/清单排查、部署失败有序列表、指标/日志、云环境与oss环境差异 |
| 命令查询 | cli-reference.md | 完整CLI命令目录,包含参数与管控规则 |
远程MCP工具("连接连接器"、 | mcp.md | 客户端连接、工具与CLI映射、仅CLI支持的操作 |
如果请求涉及两个领域("部署并检查健康状态"),加载对应两个文档并一次性回答。
Two non-negotiables (wherever you are)
两项不可协商规则(无论身处何种环境)
- Prefer — 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.
insta run -- <cmd> - When a file is genuinely needed, treat (from
./.env; auto-gitignored in git repos) as the only credential source — never hardcode or print secret values.insta secrets+ compute + storage (DATABASE_URL/AWS_*) 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 inBUCKET_NAME(project-wide) /insta secrets set <NAME>for branch overrides — never hand-edit--branchvalues you want to persist; a redeploy re-injects the platform's view..env - Track every schema change as a file under so it replays on a branch DB and again on
migrations/after a merge. InstaCloud never merges databases — only migration files carry schema forward.main
- 优先使用 ——每次调用都会获取凭证包并仅注入子进程环境;无磁盘写入,因此不会发生泄露或被提交。
insta run -- <cmd> - 当确实需要文件时,仅将 (来自
./.env;在git仓库中会自动被忽略)作为唯一凭证来源——切勿硬编码或打印密钥值。insta secrets、计算服务、存储服务(DATABASE_URL/AWS_*)均为分支专属(每个分支会对父分支的存储桶进行copy-on-write分叉;未启用快照的遗留存储桶仍为共享——无隔离性)。用户配置应存储在BUCKET_NAME(项目级)/ 使用insta secrets set <NAME>指定分支覆盖——切勿手动编辑--branch中需要持久化的值;重新部署会重新注入平台管理的凭证。.env - 将所有 schema 变更作为文件存储在 目录下,以便在分支数据库和合并到
migrations/后的主数据库中重新执行。InstaCloud 从不合并数据库——仅迁移文件可同步schema变更。main
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;
(all plans: , , or at
create) trades a small continuous RAM cost for zero cold starts — see
operate.md. The paid levers are the resource CEILING (,
— per-machine size, see operate.md)
and machine COUNT ( — horizontal): free plans stay
at the minimum of both and get a 403 — first; /
show cycle usage and cost. One free org per user. Full flags in
cli-reference.md.
always-oninsta compute always-oninsta db always-on--always-oninsta compute limitsinsta db limitsinsta services scaleinsta billing upgradeinsta usageinsta billing管控机制与转发流程见上文;凭证审计观察钩子、事件时间线、Agent审计模式见 governance.md。
计费基于实际应用使用量(实际消耗的vCPU·分钟 / RAM GB·分钟 + 存储 + 流量——而非机器规格×时长)。默认启用缩容至零,因此闲置服务几乎无成本;(所有套餐支持:、,或创建时使用 参数)以少量持续RAM消耗换取零冷启动——详见 operate.md。付费控制项为资源上限(、——单机器规格,详见 operate.md)和机器数量(——水平扩缩容):免费套餐默认使用最低配置,超出会返回403——需先执行 ; / 显示周期使用量和成本。每个用户可拥有一个免费组织。完整参数见 cli-reference.md。
always-oninsta compute always-oninsta db always-on--always-oninsta compute limitsinsta db limitsinsta services scaleinsta billing upgradeinsta usageinsta billingResponse 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、观测到的状态——而非假设)、下一步操作(或任务已完成)。仅在有助于理解的情况下包含命令输出。