cargo-hosting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Cargo CLI — Hosting

Cargo CLI — 托管服务

Cargo Hosting runs two kinds of workspace-scoped resources, plus the deployments that ship them:

App — a Vite single-page app served on
```
https://<slug>.cargo.app
```
, built on
```
@cargo-ai/app-sdk
```
(Vite + refine + shadcn primitives, with
```
getCargoEnv()
```
/
```
useCargoApi()
```
wired to the workspace).
Worker — a serverless HTTP handler that runs on the edge (
```
fetch(request, env)
```
), built on
```
@cargo-ai/worker-sdk
```
(auto OpenAPI 3.1 spec at
```
/openapi.json
```
, Swagger UI at
```
/docs
```
).
Deployment — one build+upload of a local source directory to an app or worker. A deployment is not live until it's promoted.

For organizing apps/workers into folders, use
cargo-workspace-management
(
folder …
). The
--folder-uuid
flags here consume those folder UUIDs.

See
references/examples/apps.md
,
references/examples/workers.md
, and
references/examples/deployments.md
for end-to-end walkthroughs. See
references/response-shapes.md
for JSON response structures. See
references/troubleshooting.md
for common errors and how to fix them.

Cargo Hosting 运行两种工作区范围内的资源，以及用于发布它们的部署任务：

应用（App） — 部署在
```
https://<slug>.cargo.app
```
上的Vite单页应用，基于
```
@cargo-ai/app-sdk
```
构建（包含Vite + refine + shadcn基础组件，已集成
```
getCargoEnv()
```
/
```
useCargoApi()
```
以对接工作区）。
Worker — 运行在边缘节点的无服务器HTTP处理程序（
```
fetch(request, env)
```
），基于
```
@cargo-ai/worker-sdk
```
构建（自动生成OpenAPI 3.1规范，可通过
```
/openapi.json
```
访问，Swagger UI可通过
```
/docs
```
访问）。
部署（Deployment） — 将本地源码目录构建并上传至应用或Worker的一次操作。部署需经过推广后才会上线。

如需将应用/Worker整理到文件夹中，请使用
cargo-workspace-management
（
folder …
命令）。此处的
--folder-uuid
参数需使用这些文件夹的UUID。

如需端到端操作指南，请查看
references/examples/apps.md
、
references/examples/workers.md
和
references/examples/deployments.md
。如需JSON响应结构说明，请查看
references/response-shapes.md
。如需常见问题及解决方案，请查看
references/troubleshooting.md
。

Prerequisites

前置条件

See

../cargo/references/prerequisites.md

for install, login (

--oauth

--token

), JSON output conventions, and error shapes. Verify the session with

cargo-ai whoami

before running any command below.

安装、登录（

--oauth

--token

）、JSON输出规范及错误格式说明，请查看

../cargo/references/prerequisites.md

。在运行以下命令前，请通过

cargo-ai whoami

验证会话有效性。

The lifecycle

生命周期

Apps and workers follow the same shape — scaffold → create slot → deploy → promote:

init (local scaffold) → create (slot + slug) → deployment create (build+upload) → deployment promote (go live)

Scaffold a local project from a template —

hosting app init <dir>

hosting worker init <dir>

Create the slot in the workspace —
```
hosting app create --name --slug
```
→
```
appUuid
```
(or
```
workerUuid
```
). The
```
--slug
```
becomes the subdomain and must be globally unique within the hosting domain.
(apps, optional) Wire local dev —
```
hosting app env <appUuid>
```
prints the
```
.env.local
```
lines a local copy needs (Cargo OAuth + workspace + app UUID + API URL).
Deploy —
```
hosting deployment create --app-uuid <uuid> --source <dir>
```
uploads the source; the backend runs
```
npm ci && vite build
```
(apps) or bundles the entrypoint (workers) in a sandbox. Returns a
```
deploymentUuid
```
.

Promote —

hosting deployment promote --uuid <deploymentUuid>

points the live URL at that build.

Deploys build asynchronously — poll
hosting deployment get <uuid>
until the status is terminal before promoting (see Async polling).

应用和Worker遵循相同的流程 —— 搭建 → 创建插槽 → 部署 → 推广：

init（本地搭建）→ create（插槽+子域名标识）→ deployment create（构建+上传）→ deployment promote（上线）

搭建本地模板项目 ——

hosting app init <dir>

hosting worker init <dir>

。

在工作区创建插槽 ——
```
hosting app create --name --slug
```
→ 返回
```
appUuid
```
（或
```
workerUuid
```
）。
```
--slug
```
将作为子域名，必须在托管域内全局唯一。
（应用可选）配置本地开发环境 ——
```
hosting app env <appUuid>
```
会打印本地项目所需的
```
.env.local
```
配置内容（Cargo OAuth + 工作区 + 应用UUID + API地址）。
部署 ——
```
hosting deployment create --app-uuid <uuid> --source <dir>
```
上传源码；后端会在沙箱环境中执行
```
npm ci && vite build
```
（应用）或打包入口文件（Worker）。返回
```
deploymentUuid
```
。

推广 ——

hosting deployment promote --uuid <deploymentUuid>

将在线URL指向该构建版本。

部署为异步构建 —— 需轮询
hosting deployment get <uuid>
直到状态变为终态后再进行推广（详见异步轮询）。

Apps

应用（Apps）

bash

undefined

bash

undefined

Discover

查看

cargo-ai hosting app list # all apps (filter with --folder-uuid <uuid>) cargo-ai hosting app get <uuid> # one app's details + URL

cargo-ai hosting app list # 列出所有应用（可通过--folder-uuid <uuid>筛选） cargo-ai hosting app get <uuid> # 获取单个应用的详情及URL

Scaffold locally (Vite + @cargo-ai/app-sdk)

本地搭建（基于Vite + @cargo-ai/app-sdk）

cargo-ai hosting app init ./my-app --list-templates # see available templates, then: cargo-ai hosting app init ./my-app --template blank --name "My App"

cargo-ai hosting app init ./my-app --list-templates # 查看可用模板，然后执行： cargo-ai hosting app init ./my-app --template blank --name "My App"

Create the slot (slug must be globally unique → it's the subdomain)

创建插槽（slug必须全局唯一，将作为子域名）

cargo-ai hosting app create --name "My App" --slug my-app --folder-uuid <folder-uuid>

Print .env.local for local development

打印本地开发所需的.env.local配置

cargo-ai hosting app env <app-uuid> cargo-ai hosting app env <app-uuid> --api-url https://api.getcargo.io

Update / remove

更新 / 删除

cargo-ai hosting app update --uuid <app-uuid> --name "Renamed" cargo-ai hosting app update --uuid <app-uuid> --folder-uuid null # move to workspace root cargo-ai hosting app remove <app-uuid> # also removes its deployments


Templates: `blank` (minimal starting point) and `territories-overview` (read-only territories grid demoing `useCargoApi()` + react-query). Run `app init <dir> --list-templates` for the current list.

cargo-ai hosting app update --uuid <app-uuid> --name "Renamed" cargo-ai hosting app update --uuid <app-uuid> --folder-uuid null # 移至工作区根目录 cargo-ai hosting app remove <app-uuid> # 同时删除其所有部署


可用模板：`blank`（极简起始模板）和`territories-overview`（只读区域网格示例，演示`useCargoApi()` + react-query的用法）。执行`app init <dir> --list-templates`可查看当前所有模板。

Workers

Worker

Same command shape as apps — substitute

worker

for

app

bash

cargo-ai hosting worker list                        # filter with --folder-uuid <uuid>
cargo-ai hosting worker get <uuid>

命令格式与应用一致 —— 将

app

替换为

worker

即可：

bash

cargo-ai hosting worker list                        # 列出所有Worker（可通过--folder-uuid <uuid>筛选）
cargo-ai hosting worker get <uuid>

Scaffold (edge fetch(request, env) handler on @cargo-ai/worker-sdk)

搭建（基于@cargo-ai/worker-sdk的边缘fetch(request, env)处理程序）

cargo-ai hosting worker init ./my-worker --list-templates cargo-ai hosting worker init ./my-worker --template blank --name "My Worker"

cargo-ai hosting worker create --name "My Worker" --slug my-worker --folder-uuid <folder-uuid> cargo-ai hosting worker update --uuid <worker-uuid> --name "Renamed" cargo-ai hosting worker remove <worker-uuid> # also removes its deployments


Templates: `blank` (auto OpenAPI spec + Swagger UI) and `custom-integration` (a Cargo Custom Integration — manifest / actions / extractors / autocompletes / dynamic schemas). Workers have **no `env` subcommand** — they read config from the `env` argument passed to `fetch` at runtime.

cargo-ai hosting worker init ./my-worker --list-templates cargo-ai hosting worker init ./my-worker --template blank --name "My Worker"


可用模板：`blank`（自动生成OpenAPI规范 + Swagger UI）和`custom-integration`（Cargo自定义集成——包含清单/操作/提取器/自动补全/动态Schema）。Worker**没有`env`子命令**——它们在运行时从`fetch`传入的`env`参数读取配置。

Deployments

部署（Deployments）

A deployment belongs to exactly one app or one worker (

--app-uuid

and

--worker-uuid

are mutually exclusive).

bash

undefined

一个部署仅属于一个应用或一个Worker（

--app-uuid

和

--worker-uuid

不可同时使用）。

bash

undefined

List / inspect

列出 / 查看

cargo-ai hosting deployment list --app-uuid <uuid> # or --worker-uuid <uuid> cargo-ai hosting deployment get <deployment-uuid> # status + metadata cargo-ai hosting deployment get-promoted --app-uuid <uuid> # what's currently live

cargo-ai hosting deployment list --app-uuid <uuid> # 或使用--worker-uuid <uuid> cargo-ai hosting deployment get <deployment-uuid> # 获取状态及元数据 cargo-ai hosting deployment get-promoted --app-uuid <uuid> # 查看当前上线的版本

Build & upload a local source directory (point at the package root, NOT dist/)

构建并上传本地源码目录（指向项目根目录，而非dist/）

cargo-ai hosting deployment create --app-uuid <uuid> --source ./my-app cargo-ai hosting deployment create --worker-uuid <uuid> --source ./my-worker

default ignores: node_modules,dist,build,.git,.next — override with --ignore "a,b,c"

默认忽略目录：node_modules,dist,build,.git,.next —— 可通过--ignore "a,b,c"覆盖

Go live

上线

cargo-ai hosting deployment promote --uuid <deployment-uuid>

undefined

cargo-ai hosting deployment promote --uuid <deployment-uuid>

undefined

Critical rules

关键规则

--slug
must be globally unique within the hosting domain — it's the live subdomain (
```
<slug>.cargo.app
```
). A clash fails at
```
create
```
.
Deploying ≠ going live.
```
deployment create
```
builds and uploads; the URL only changes when you
```
deployment promote
```
that deployment. Use
```
deployment get-promoted
```
to see what's live now.
--source
is the package root, not
dist/
. The build runs in a Cargo sandbox:
```
npm ci && vite build
```
for apps, entrypoint bundling for workers. Shipping a pre-built
```
dist/
```
will not work.
Builds are async — poll
```
deployment get
```
until terminal before promoting (see below).

--app-uuid
/
--worker-uuid
are mutually exclusive on

deployment create

deployment list

, and

deployment get-promoted

. Pass exactly one.

remove
cascades — removing an app or worker also removes all of its deployments.
update --folder-uuid null
(literal string
```
null
```
) moves a resource back to the workspace root.
Hosting consumes credits monthly per resource. Each app/worker carries a
```
chargedUntil
```
that an hourly sweep advances a month at a time, so a live app or worker bills hosting credits on an ongoing basis —
```
remove
```
resources you no longer serve. Track consumption via
```
cargo-billing
```
.

--slug
必须在托管域内全局唯一——它是在线子域名（
```
<slug>.cargo.app
```
）。如果重复，
```
create
```
命令会执行失败。
部署 ≠ 上线。
```
deployment create
```
仅完成构建和上传；只有执行
```
deployment promote
```
后，URL才会指向该部署版本。使用
```
deployment get-promoted
```
可查看当前上线的版本。
--source
需指向项目根目录，而非
dist/
。构建在Cargo沙箱环境中执行：应用执行
```
npm ci && vite build
```
，Worker执行入口文件打包。上传预构建的
```
dist/
```
目录无法正常工作。
构建为异步操作——需轮询
```
deployment get
```
直到状态变为终态后再进行推广（详见下文）。
在
deployment create
、
deployment list
和
deployment get-promoted
命令中，
--app-uuid
/
--worker-uuid
不可同时使用，必须且只能传入其中一个。
remove
命令会级联删除——删除应用或Worker时，其所有部署也会被一并删除。
update --folder-uuid null
（传入字符串
```
null
```
）会将资源移回工作区根目录。
托管服务每月按资源消耗 credits。每个应用/Worker都有
```
chargedUntil
```
字段，每小时自动延长一个月，因此在线的应用或Worker会持续消耗托管credits——请删除不再使用的资源。消耗情况可通过
```
cargo-billing
```
查看。

Async polling

异步轮询

deployment create

kicks off a sandboxed build. The deployment's

status

moves

pending → building → success

(or

error

cancelled

). Poll until terminal, then promote the

success

one:

bash

cargo-ai hosting deployment get <deployment-uuid>   # poll ~2–5s until status is terminal

Terminal statuses are

success

error

, and

cancelled

— only promote a

success

deployment. On

error

, read the deployment's

errorMessage

(and

buildLogS3Filename

) to diagnose the build. For the general polling pattern (intervals, retries), see

../cargo-orchestration/references/polling.md

deployment create

会启动沙箱构建。部署的

status

会经历

pending → building → success

（或

error

cancelled

）状态。需轮询直到状态变为终态，然后推广

success

状态的部署：

bash

cargo-ai hosting deployment get <deployment-uuid>   # 每2–5秒轮询一次，直到状态变为终态

终态包括

success

、

error

和

cancelled

——仅可推广

success

状态的部署。若状态为

error

，可查看部署的

errorMessage

（及

buildLogS3Filename

）来诊断构建问题。通用轮询模式（间隔、重试）请查看

../cargo-orchestration/references/polling.md

。

Help

帮助

Every command supports

--help

bash

cargo-ai hosting app create --help
cargo-ai hosting deployment create --help

所有命令均支持

--help

参数：

bash

cargo-ai hosting app create --help
cargo-ai hosting deployment create --help