insta

InstaCloud

Agent 执行模式（托管 Platform）

agent policy 是唯一的策略系统。人类使用常规 RBAC；只有 Agent 请求会进入策略评估器。原先的 policy 命令和审批用的 --always 标志已移除。

作为 Agent 调用 CLI 时，始终使用 insta --agent <command> …，包括设置和只读命令。示例中会明确包含全局标志；使用 npx 时，请使用 npx -y insta@latest --agent <command> …。不要仅依赖环境检测。明确标记为供人类管理员使用的命令是转交指示，不是 Agent 工具调用： 切勿自行执行这些命令，也不要移除 --agent 来绕过限制。 首先在已关联的项目中运行 insta --agent agent setup（或使用 --project <id> / --create [name]）。 这会在 .insta/agent-session.json 中存储一个绑定到项目、有效期为 24 小时的会话，该文件会自动被 Git 忽略。它会补充现有的用户登录。若会话缺失、过期、已撤销或项目不匹配，命令会失败并提供设置指引；被拒绝的 Agent 请求不得在未使用 --agent 的情况下重试。

已知的 Codex/Claude Code/Cursor 环境也会启用 Agent 模式；通用 CI 或缺少 TTY 不会启用。MCP 工具调用会自动作为 Agent 请求处理。查看 insta --agent agent policy get --json，了解当前模式和受保护的分支。所有项目初始都使用 full_access。 在 branch_specific 模式下（以及携带明确规则、模式相同的 customize），对受保护分支的写入会被拒绝；对未受保护分支执行的高风险操作则需要人类审批。将审批命令转交给人类管理员，并且仅在获得批准后重试原始请求，且不得更改请求；Agent 不能审批自己的请求。详情和 SQL 限制： governance.md。此协议要求使用支持 Agent 会话的托管版 Platform；较旧版本/OSS 端点不实现此协议，会话错误也不能成为悄悄切换执行身份的理由。

InstaCloud 通过一个 CLI 和一个凭证入口，为项目配置并管理云服务。insta CLI 只与 InstaCloud 控制平面通信——你无需直接配置云后端。项目可以按需添加任意数量的服务。常见的、可直接对接的服务类型包括：

• postgres — 关系型数据库，创建时资源上限即为其套餐上限（使用任意套餐时，都可通过 insta --agent postgres limits 在免费额度内调整；超出免费额度则需要付费套餐）。这是标准的 Postgres：可在计算环境中绑定 DATABASE_URL，然后直接使用任意驱动/ORM 连接——无需供应商 SDK 或供应商技能。数据库也可以从计算服务之外通过公网连接：insta --agent postgres url 会打印连接字符串，insta --agent postgres connect 会打开一个 psql 会话——你（或人类）可以通过这种方式从笔记本电脑、迁移脚本或任何外部工具连接数据库。如果数据库已切换为缩容至零（新建数据库默认始终运行），请将连接池的 idleTimeoutMillis 设为低于其暂停窗口的值（参见 frameworks.md）。
• storage — 兼容 S3 的对象/Blob 存储。将任意 S3 库指向绑定的 AWS_* / BUCKET_NAME 环境变量即可——无需供应商 SDK。请显式设置端点，否则客户端会连接到真实的 AWS；每个分支通常都有自己的分叉存储桶（旧版快照前项目共用一个——见下文）。参见 storage.md。
• compute — 位于公网 URL 的容器。一个项目可以有多个计算服务 （例如 api、worker）。
• redis/mysql/mongodb — 托管数据服务。它们会提供诸如 REDIS_URL、MYSQL_URL 和 MONGODB_URL 的连接环境变量。 新建项目默认为空——不会自动创建服务。按需添加： insta --agent service add postgres <name>、insta --agent service add compute <name>、 insta --agent service add storage <name>、insta --agent service add redis <name> 等。一个项目可以 拥有每种类型的多个服务，每种类型的数量上限由计划按分支设定（参见 cli-reference.md）。提供商凭据的作用域限定为创建它们的服务，并在该作用域内使用规范名称（DATABASE_URL、REDIS_URL、 MYSQL_URL、MONGODB_URL、AWS_ACCESS_KEY_ID、BUCKET_NAME，……）。本地开发衔接流程 （insta --agent secrets → .env、insta --agent run）会为每种类型提供一组凭据，来自该分支上该类型的 主要服务——但它们不会自动出现在计算环境中：容器只有通过显式绑定才能获得提供商凭据，而且同类型的非主要服务不会包含在凭据包中：对于 postgres，使用 insta --agent postgres url <name> 读取； 对于其他类型，则无法直接读取——请绑定凭据，或使用 insta --agent secrets --service compute/<name> 读取绑定了该凭据的计算服务的环境变量。获取本地凭据包不会创建绑定。insta --agent service add compute 创建的服务不会继承其他服务的提供商凭据绑定。绑定每个计算服务所需的凭据，然后部署；或者，如果服务已经在运行，则运行 insta --agent compute restart（CLI ≥ 0.0.51），无需重新部署即可应用绑定。它会重新运行已记录的镜像引用，因此使用可变标签（app:latest）的服务仍会获取该标签当前解析到的镜像——在生产环境中使用前，请参阅 operate.md：

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

绑定仅适用于计算环境。如果要自行使用凭据——例如运行迁移、检查数据，或让本地工具连接数据库——请直接读取其值：insta --agent postgres url（Postgres 连接字符串；使用 insta --agent postgres connect 打开 psql shell）。

使用 insta --agent service rename <type> <name> <new-name> 重命名服务；现有绑定仍会指向该服务。

安装和升级 CLI

如果 command -v insta 没有找到任何内容，请安装 CLI（切勿假定它已存在）：

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)

CLI 尚未达到 1.0 版本，并且会频繁发布。如果命令运行异常或无法识别，请先更新： insta --agent upgrade（支持该命令的 CLI；1.0 之前默认开启自动更新——运行 insta --agent config autoupdate off 可将其关闭），否则请重新运行安装程序（可重复运行），或运行 npm update -g insta。

两个目标，一个 CLI

两者使用相同的命令。通过 insta --agent status（api: 行）判断当前连接的是哪一个：

• InstaCloud（托管云） — 需要运行 insta --agent login（Agent：使用 --email/--password 或 API 令牌；人工用户：直接运行 insta --agent login，会在浏览器中打开控制台登录／审批页面——适用于任何账户类型；在可通过其他方式联系到人工用户的无头机器上，使用 --device 打印链接和代码，供他们在其他浏览器中批准）。CI 和长期运行的自动化任务应使用限定范围的 API 令牌：人工用户在自己的终端中运行 insta tokens create <name> --org <id>（或 --project <id>），然后自动化任务使用 insta --agent login --api-key <insta_…>——绝不要使用账户级令牌。 出于安全考虑，insta tokens create／revoke 仅供人工用户使用——Agent 绝不能自行创建凭证（不带 --agent 使用 insta_ 令牌会被视为人工请求，不受 Agent 策略约束）；在 Agent 会话中，在任何策略下运行这两个命令都会返回 403 unclassified_agent_action。不要重试或切换身份：将准确的命令交给用户，让他们在本会话之外运行，避免只显示一次的明文令牌进入会话记录。 任何命令返回 403 token_scope 都表示凭证的权限范围小于该调用所需的范围，并不表示缺少角色；解决方法是由人工用户通过账户登录创建一个权限范围更大的令牌，而不是修改成员身份（参见 cli-reference.md）。
• insta-oss（可自托管的本地守护进程） — INSTA_API_URL=http://127.0.0.1:8080（默认值）。 无需登录，也不支持登录（信任 localhost，内置 local 用户）；计费／用量／指标会返回明确的“仅限云端”错误——不要重试。

工具路由：CLI 与 MCP

InstaCloud 提供两种面向 Agent 的操作方式。对于所有操作，默认使用此技能和 CLI——CLI 覆盖完整的命令范围（少数仅供 MCP 使用的只读诊断命令除外，详见 mcp.md），携带关联仓库的上下文（.insta/project.json），也是获取本地机器状态的唯一方式：身份验证（insta --agent login）、拉取密钥值（insta --agent secrets／insta --agent run，以及通过 insta --agent postgres url／insta --agent postgres connect 获取 postgres DSN）、从源目录部署（insta --agent deploy <dir>），以及 observe hook。

仅在无法调用 CLI 时，才回退到远程 MCP 工具（insta_*）：没有 shell（例如 Claude.ai／ChatGPT 连接器中的托管 Agent），或者 CLI 未安装且无法安装（常见情况是 PATH 中没有 CLI，但可以通过 npx -y insta@latest --agent agent setup -y 自行安装——参见下文的自我修复）。两者使用相同的平台 API、治理关卡和审计跟踪，但 MCP 工具需要显式传入 projectId／branch 参数：绝不要假设 CLI 关联的上下文会自动沿用；应先解析 ID（insta_list_projects），再显式传入。完整映射和连接指南：mcp.md。

自我修复：如果预期应有 insta 技能或 insta_* MCP 工具，但实际缺失，请运行 insta --agent agent setup -y（安装技能，并为 Claude Code 和所有检测到的 Agent 注册 MCP），然后告知用户重启其编码工具——运行中的会话不会获取新注册的 MCP 服务或工具。针对某个特定 Agent：insta --agent config install-mcp --agent <slug>。 仅注册并不会对客户端进行身份验证；实际使用工具需要完成 OAuth 流程或提供已授权的凭证。--mcp-token 选项会创建令牌，按设计仅供人工用户使用（参见 两个目标）；Agent 因 403 unclassified_agent_action 被拒绝时，必须停止尝试，不得重试并伪装成人工用户。 有关无人值守身份验证，请参阅 mcp.md。

InstaCloud 不适用的情况

如果不适用，就直说并停止，不要强行套用。下面每一项都可以核实，指出其中一项就是在认真回答用户，而不是拒绝回应：

不适用的情况	原因
GPU 训练或大模型推理	不提供 GPU
多容器 docker compose 应用	租户计算环境不支持 Docker-in-Docker，也不支持嵌套虚拟化
供人反复切换操作的交互式 shell	该 shell 是 insta compute ssh，需要审批才能使用，而且会进入来宾系统的 root 用户环境，而非容器内部。本项与 compute exec 无关，也与分支环境无关：每个 Agent 使用一个分支是隔离工作的受支持方式，也是上述方向之一
作为服务部署、运行一次后退出的脚本	健康检查门槛要求服务持续运行并响应。已有服务时，可在其中运行脚本：使用 insta --agent compute exec，它专为一次性命令设计，运行时限为 180s
后端完全位于其他位置的静态前端	仓库中没有任何服务端程序运行，因此没有可分叉的环境，也没有需要保留的状态；静态托管更适合这种情况。如果该后端也属于用户，请改为评估其仓库

前四项是平台无法做到的。第五项虽然能做到，但不应该为此选择该平台，因此应指出这项工作更适合在哪里完成。同一列表也发布在 https://instacloud.com/prompt.md，其中还列出了评估仓库的标准。请保持两处内容一致。

按意图路由

先按意图路由，再进行预检流程：

“发布 / 部署这个应用”（从零开始）： 不要先询问当前状态，直接运行完整流程并说明步骤：insta --agent status（已登录？已关联？）→ 如果在云端且未认证，则运行 insta --agent login → 如果未关联，则运行 insta --agent project create <dir-name> → insta --agent service add postgres db（如果应用需要数据库）+ insta --agent service add compute app → 将所需服务凭证绑定到计算环境（运行 insta --agent secrets sources，然后运行 insta --agent secrets bind DATABASE_URL postgres/db --to compute/app）→ insta --agent deploy . --port <the port the app listens on> → 验证输出的网址可以正常访问（见下文）。 应用会读取 process.env 中的凭证。对于无端口的 insta-compute worker，请先检查已安装 CLI 的 insta --agent service add --help 和 insta --agent deploy --help 是否支持 worker 端口为零，再使用 --port 0。 否则，请使用 type: worker 模板和预构建镜像，或者使用 仅源代码的监听器回退方案。请让 worker 始终运行。无端口的部署没有公开 URL；请通过状态、日志和已完成的作业来验证。

“设置 / 入门 / 注册”： 云端 → insta --agent login（通过浏览器登录；如果没有自动打开浏览器，请转发输出的链接），或使用 --email/--password；然后运行 insta --agent project create。本地 / oss → 除守护进程外，无需进行其他设置。

在现有项目上完成一个工作单元（功能、修复、实验、Agent 任务）： 每个工作单元使用一个分支——参见下方的核心原则和 branching.md。 不要在 main 上开发。

其他情况（配置、调试、检查）： 进行轻量预检，然后参阅下方对应的参考文档。

执行变更前的预检与上下文

command -v insta                 # installed? (else: Install section)
insta --agent status --json              # target api, login, linked project, current branch

上述从零开始部署的流程中无需执行这些步骤——status 已经是第一步。

上下文规则（多 Agent 安全）：

• 链接（./.insta/project.json）按目录设置，并包含当前分支。
• 在操作不属于自己的分支时，优先在支持相关选项的命令中显式使用 --branch <name>（secrets、deploy、<type> metrics、<type> logs、agent events、postgres url / postgres connect——错误分支的 DSN 会导致查询错误的数据库），而不是使用 insta --agent branch switch；switch 会修改目录共享链接，并与同一检出目录中的并行 Agent 发生竞争。
• 对于并行 Agent，规则是 1:1:1——任务 ↔ git worktree ↔ insta 分支（每个 worktree 都有自己的链接，因此在那里使用 switch 是安全的）。参见 branching.md。

核心原则

一份工作 = 一个分支 = 一个隔离环境。 insta --agent branch create <name> 会将父分支当前的服务部署到新分支——CoW 数据库分支（父分支数据的副本）、CoW 分叉的存储桶，以及每个计算服务的克隆（各自拥有独立 URL）；这些都在创建分支时生成，因此分支从一开始就是完整、可运行的环境。 各分支完全并行运行；一个分支上的操作不会影响其他分支。**每个项目最多 10 个分支（硬性限制）。**不要在 main 上开发；不要把多个功能堆在同一个分支上。

要同时处理多个独立功能（或 Agent 任务）？为每项任务分配自己的分支和自己的子 Agent——隔离的数据库、存储、计算服务和 URL 意味着不会发生冲突。参见 branching.md → 并行 Agent。

报告部署结果前先验证

切勿仅凭命令退出就报告部署成功。 insta --agent deploy 成功时会输出分支 URL——这表示平台已接受部署并启动机器，并不代表应用已正常提供服务：

1. 每隔约 3 秒轮询输出的 URL（curl -s -o /dev/null -w '%{http_code}'），最长约 60 秒。 新创建的计算服务默认缩至零，因此空闲服务会在收到第一个请求时冷启动——首次请求可能较慢，请耐心等待。使用 --always-on 创建的服务（或通过 insta --agent compute always-on on 启用的服务）不会出现这种情况；参见 references/operate.md。
2. 返回 200（或应用预期的状态码）→ 部署成功；报告 URL。
3. 仍然失败 → 按 operate.md 中的故障排查列表依次检查（最常见的原因是端口不匹配和启动受迁移阻塞）。
4. 如实报告确切的失败状态——绝不声称成功，除非你已实际观察到成功。

审批转交（关键——受审批门控的操作）

敏感操作在凭据边界受到门控（secrets.read、secrets.write、deploy、project.delete、branch.delete、service.add/remove/scale/upgrade、domain.purchase、domain.delegate、zone.delegate；各操作的策略为 allow/deny/approve，使用项目的 Agent 策略）。当命令返回**“approval required”并附有审批 ID**时：

• 立即逐字转告人工操作人员——需在人工操作人员的终端中运行的确切命令： insta agent approvals approve <id>。审批仅授权一次完全相同的请求。不要省略审批信息，不要重试命令，也不要在先告知审批要求之前报告任务失败。只有管理员可以批准。
• 授权为一次性：获批后，重新运行原命令；除非人工操作人员明确更改适用的 agent policy 规则，否则下次遇到该操作时仍会再次提示审批。
• 绝不可绕过门控（例如手动编辑状态或绕过 CLI）——门控是产品的安全模型。deny 策略表示明确禁止：如实报告，不要规避。

常见快捷操作

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

解析输出时，请使用 --json。

路由

对于快捷操作以外的内容，请加载与意图相符的参考文档——通常只需一个，最多两个：

意图	参考	涵盖内容
创建或连接事物（“设置”“新建项目”“添加数据库/计算资源”）	setup.md	CLI 安装/升级、云端与开源目标、身份验证、项目、服务、从零开始上线
按计划运行任务（“每晚”“cron 任务”“定期任务”“每小时运行一次”）	cli-reference.md	insta --agent cron 命令、仅限 UTC 的表达式、服务与外部目标（平台允许使用组织内的任意服务；CLI 只能访问当前分支的服务）、运行 ID 幂等性约定、用于凭据的 --secret-ref（发送时解析，因此轮换无需编辑）、编辑会替换请求而非合并请求，以及每种运行状态的含义
发布代码或管理版本	deploy.md · 框架配方：frameworks.md	镜像与源码（远程构建）、--port 语义、显式绑定服务凭据、运行时密钥、验证流程、Dockerfile 模板、自定义域名（用户拥有的域名会以 www 等子域名形式绑定；购买的域名则通过 insta --agent domain delegate 提供 apex 域名服务）
迁移现有应用（“将我的 Render/Railway 服务迁移到 InstaCloud”“从 Heroku/Railway/Fly/Render 迁出”“导入我的应用”“把我的应用迁过来”）	migrate.md 以及 references/migrate/ 中所需的一个来源文件（render.md、railway.md、fly.md、insforge.md）	按顺序执行的切换流程及其通过条件和回滚边界、InstaCloud 侧容易踩坑的语义（绑定需要部署、不能批量导入环境变量、cron 使用 HTTP 而非命令、工作进程）、命令与附加组件映射、各来源的差异（每个来源现在都有自己的文件，应与 migrate.md 一起阅读，而非取代它）
分支环境、并行 Agent、晋升（“预览环境”“每个任务一个沙盒”“合并到 main”）	branching.md	数据分叉环境模型（实际克隆的内容）、分支循环、1:1:1 工作树模式 + 调度说明、晋升、迁移规范
审批、策略、审计、凭据扫描	governance.md	门禁目录、审批中继、事件时间线、观察钩子、Agent 审计模式
将 Postgres 数据库从互联网隔离，或以私密方式连接计算资源（“私有数据库”“关闭公共访问”“DATABASE_PRIVATE_URL”）	operate.md → Postgres 网络访问	private-access on 会生成 DATABASE_PRIVATE_URL（仅限 InstaCloud 计算资源，不适用于笔记本电脑/CI）、重新绑定、执行 public-access off 前的影响预览、约 30 秒的传播时间，以及关闭访问会导致外部客户端、CI 和本地开发无法连接
让服务通过私有网络互相调用，或将计算服务/托管数据库从互联网隔离（“内部 URL”“服务到服务”“仅限私有网络”“*.insta.internal”“REDIS_PRIVATE_URL”）	cli-reference.md → 私有网络	每个服务在其分支范围内的 <name>.insta.internal 地址（数据库使用 <name>-<type>）、任意端口上的 TCP+UDP、私有流量唤醒、从 service list 读取 private_host，而非自行拼接、public-access off = 仅限私有访问（403，不会唤醒），数据库的 *_PRIVATE_URL，以及关闭访问前重新绑定
检查运行状况或调试故障	operate.md	状态/清单排查、按顺序排列的部署故障列表、指标/日志、云端与开源版本的差异
将项目或没有项目的镜像转为社区模板（“把它做成模板”“放进模板库”“发布给其他人”）	cli-reference.md → 发布社区模板	从项目创建草稿（或先创建空白模板，再用 template edit 添加服务和变量）、确定变量、填写标语、类别和 README、检查发布要求，并且仅在用户明确同意后发布（模板会立即公开，无需审核）
查询命令	cli-reference.md	完整 CLI 目录，包含标志和门禁
远程 MCP 工具（“连接连接器”，可使用 insta_* 工具）	mcp.md	连接客户端、工具 ↔ CLI 对照、仅限 CLI 的功能
InstaCloud 本身造成阻碍（错误、文档过时、缺少功能、使用不便）	cli-reference.md → 反馈	insta --agent feedback / insta_send_feedback：何时提交，以及情境 → 类型的对应关系
如果一个请求涉及两个领域（“部署并检查其是否健康”），则同时加载两者，并一次性作答。

无论身处何处，都必须遵守的两条原则

• 对于任何需要使用分支机密的操作，优先使用 insta --agent run -- <cmd>——每次调用都会获取机密包，并且只将其注入子进程环境；不会写入磁盘，因此不会泄露或被提交。机密包还包含分支的规范提供商凭据——每种类型一组，来自该类型的主服务——因此本地运行无需绑定任何内容即可连接数据库。计算服务接收的内容则另当别论：先使用 insta --agent secrets bind 进行绑定，再部署（或者对正在运行的服务执行 insta --agent compute restart，CLI ≥ 0.0.51——绑定变更不会自动同步到正在运行的机器上）。 如果多个服务定义了相同名称，run 会拒绝运行并以状态码 2 退出（CLI ≥ 0.0.65）：不会启动任何进程，并会将冲突名称及两种处理方式打印到标准错误。不要将其视为暂时性故障而重试——请使用 --service <type>/<name> 重新运行，以使用该服务的环境；或者使用 --ignore-collisions 继续运行，此时这些名称会从子进程环境中移除。审批状态码也是 2，因此请阅读标准错误消息，区分两者。
• 确实需要文件时，应将 ./.env（通过 insta --agent secrets 获取；在 git 仓库中会自动加入 git 忽略规则）视为唯一基于文件的机密来源——它包含你的用户机密和分支的主提供商凭据——绝不要硬编码或打印机密值。DATABASE_URL、AWS_* / BUCKET_NAME、REDIS_*、MYSQL_* 和 MONGODB_* 是服务凭据，只有通过显式的 insta --agent secrets bind 规则才能传入生产计算环境。若要在计算环境之外直接使用，获准的读取方式是 insta --agent postgres url / insta --agent postgres connect（postgres；需要 secrets.read 授权）——应通过管道传递（psql "$(insta --agent postgres url)"），绝不要将 DSN 粘贴到文件或代码中。每种类型的主服务凭据都已包含在分支的 insta --agent secrets / insta --agent run 中。非主服务不包含在机密包中：postgres 可使用上述 [service] 位置参数读取（insta --agent postgres url <name>），而其他类型均无法直接读取——请绑定该服务，或读取该服务自身的环境（insta --agent secrets --service compute/<name>）。 用户设置的配置应使用 insta --agent secrets set <NAME>（项目级）/使用 --branch 设置分支覆盖值——绝不要手动编辑 .env 中希望持久保存的值。
• 每项架构变更都必须记录为 migrations/ 下的文件，以便在分支数据库上重放，并在合并后再次应用到 main。**InstaCloud 从不合并数据库——只有迁移文件才能将架构变更延续下去。**迁移应在绑定了数据库凭据的环境中运行：在计算服务上通过 insta --agent compute exec app -- <migrate-cmd> 执行（绝不能将迁移设为启动门槛——参见 deploy.md）；或者直接执行，不涉及计算服务： psql "$(insta --agent postgres url --branch <b>)" -f migrations/<file>.sql（显式指定 --branch——不带参数的形式会读取已关联分支的数据库）。首先确认 psql / pg_dump / pg_restore 与服务器的 Postgres 主版本一致——使用 insta --agent service list --json --branch <b> 中的 pg_version（分支须与 DSN 相同）；如果该行没有此字段，请读取准确版本（参见 operate.md）。

治理与审计（这是平台的核心差异化优势）

门控机制和中继流程见上文；观测凭据审计钩子、事件时间线和 Agent 审计模式见 governance.md。

按应用的实际用量计费（实际消耗的 vCPU·min / RAM GB·min + 存储 + 出站流量，而不是机器规格 × 小时数）。新建的计算服务默认缩容至零：空闲服务几乎不产生费用，但会有冷启动；入站请求和出站流量都会计为活动，因此执行出站任务的应用在工作期间会保持运行。始终运行（创建时使用 --always-on，或执行 insta --agent compute always-on on）可消除冷启动；空闲应用的常驻 RAM 按实际用量计费；工作器（--port 0）则始终运行。新建数据库（包括 postgres）则相反：默认始终运行，因此即使空闲也会对常驻内存计费；创建后执行 insta --agent postgres always-on off 可选择缩容至零（CLI 目前还不能在创建 postgres 时选择此项）——参见 operate.md。付费调整项是资源上限（insta --agent compute limits、insta --agent postgres limits——每台机器的规格，参见 operate.md）和副本上限（insta --agent compute scale——水平扩缩容；缩容至零时按需运行 1 台至上限台数，始终运行时则运行上限台数）：新服务创建时采用其套餐的资源上限，免费套餐可以在免费上限内调整，但不能超出，并且只能使用 1 台机器；超出任一限制都会返回 403——请先执行 insta --agent billing subscribe；insta --agent billing usage / insta --agent billing 可查看当前周期的用量和费用。每位用户限 1 个免费组织。完整标志列表见 cli-reference.md。

InstaCloud 本身造成阻碍时（反馈）

如果遇到 InstaCloud 的问题——命令违反了文档所述的约定、技能或文档与实际情况不符、缺少功能或 UX 令人困惑——请使用 insta --agent feedback（或 insta_send_feedback MCP 工具）报告，然后继续通过变通方案完成用户的任务。绝不要因为报告而中断工作，也绝不要为用户正在构建的应用中的问题提交反馈——此渠道仅用于 InstaCloud 工具包（--component cli|mcp|platform|skills|docs）。团队会在控制台中回复，用户可在此阅读并回复；**（CLI ≥ 0.1.7）**你只能获取工单链接，并可按需查询工单状态。完整标志列表和情况 → 类型映射见：cli-reference.md → Feedback。

回复格式

对于运维工作，请报告：已完成的工作（操作 + 范围：项目/分支/服务）、结果（URL、ID、观察到的状态——而非假设的状态）以及后续步骤（或说明工作已完成）。仅在有帮助时附上命令输出。