Cargo Hosting

Cargo CLI — Hosting

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

• App — a static front end (a Vite single-page app by default; Next.js static export, Astro, SvelteKit, Nuxt, Gatsby and Create React App are detected too) served on its own subdomain (see URLs). The templates are 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.

Bootstrap

Already signed in (cargo-ai whoami returns a workspace)? Skip to the next section.

npm install -g @cargo-ai/cli            # no global install? prefix every command with `npx @cargo-ai/cli`
cargo-ai login --email you@company.com  # emailed code, no browser; creates the account on first use
                                        # alternatives: --oauth (browser) · --token <api-token> (CI)
cargo-ai whoami                         # confirm the active workspace before any write

Every command prints JSON to stdout; failures exit non-zero with {"errorMessage": "..."}. Anything that creates a run or a batch is async — pass --wait-until-finished or poll the matching get. When the full skill bundle is installed, `../cargo/references/prerequisites.md` adds the CLI version pin, token scopes, and the admin-only surface.

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)

1. Scaffold a local project from a template — hosting app init <dir> / hosting worker init <dir>.
2. Create the slot in the workspace — hosting app create --name --slug → appUuid (or workerUuid). The --slug becomes part of the subdomain and must be unique within the workspace.
3. (optional) Wire local dev — for an app, hosting app env <appUuid> prints the .env.local lines a local copy needs (Cargo OAuth + workspace + app UUID + API URL). For a worker, npm run dev in the scaffold (see Run a worker locally). A worker that calls the Cargo API also needs a CARGO_API_TOKEN secret before its first deploy (see Worker env vars and secrets).
4. Deploy — hosting deployment create --app-uuid <uuid> --source <dir> uploads the source. The backend then builds it in a sandbox: for an app, npm ci --ignore-scripts followed by the app's own build script, or the framework's default build if there is none (see App builds); for a worker, it bundles the entrypoint. Returns a deploymentUuid.
5. 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).

URLs

The live host is `<slug>-<first 8 chars of the workspace UUID>` under the hosting root domain, and apps and workers have different root domains — in production https://<slug>-<ws>.app.getcargo.run for an app, https://<slug>-<ws>.worker.getcargo.run for a worker. The workspace suffix is what makes the host globally unique, which is why a slug only has to be unique inside your workspace.

Don't build the URL by hand. Read url from create or get — the root domain differs per environment. Each deployment also gets a preview host, https://deployment-<deploymentUuid>.<root>, before it is promoted.

Because the roots differ, an app calling a worker is always a cross-origin request. No option serves them on the same origin, so the worker has to answer CORS. See the app + worker pattern in `references/examples/workers.md`.

Apps

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

# Scaffold locally (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"

# Create the slot (slug unique per workspace; `url` in the response is the live host)
cargo-ai hosting app create --name "My App" --slug my-app --folder-uuid <folder-uuid>

# Print .env.local for local development
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), territories-overview (read-only territories grid demoing useCargoApi() + react-query), and public-site (a public, indexable site that prerenders every route from its own build script and ships robots.txt + sitemap.xml). Run app init <dir> --list-templates for the current list.

App builds

If `package.json` declares a `build` script, Cargo runs it, and that script owns the whole build. Cargo runs nothing before or after it, so the script must produce the client bundle as well as anything extra, such as prerendered HTML. Without a build script, the detected framework's default command runs:

• Output must land in that framework's output directory and contain an `index.html`, or the build fails. Unknown paths fall back to that shell.
• Whatever the build script does now runs on every deploy. That includes a tsc pass, a different --mode, and prebuild/postbuild hooks. A script that fails there fails the deploy. The live deployment keeps serving, because promotion only follows a successful build.
• A `build` script Cargo can't use falls back silently. That covers an unparseable package.json, an empty script, or a non-string entry. The deploy still goes green, and only the build log says why, so check it when a prerender step seems to have been skipped.
• Platform values are injected under every public prefix. A Vite app reads VITE_CARGO_API_URL and a Next.js app reads NEXT_PUBLIC_CARGO_API_URL. When a build script is used, they are also passed as real process env vars, so a plain-Node prerender step sees them. User env values are redacted from build logs.

App env vars are public