cargo-hosting

Build, deploy, and manage Cargo Hosting apps and workers with the Cargo CLI — Vite SPAs served on *.cargo.app and serverless edge HTTP handlers, plus the deployments that ship and promote them. Use when the user wants to scaffold, deploy, promote, or manage a hosted app or worker on Cargo.

14stars3forksUpdated 7/17/2026

#cargo #deployment #hosting #cli #serverless #vite

Security Assessment

Low Risk(80/100)

Detected risks:

Sensitive File Access([references/examples/apps.md] .env, [references/response-shapes.md] .env, [SKILL.md] .env)

Security Score80/100

About cargo-hosting

cargo-hosting builds, deploys, and manages Cargo Hosting apps and workers using the Cargo CLI (cargo-ai). It covers two workspace-scoped resource types plus the deployments that ship them: an App, a Vite single-page app served on https://<slug>.cargo.app built on @cargo-ai/app-sdk (Vite, refine, shadcn primitives, with getCargoEnv() and useCargoApi() wired to the workspace); a Worker, a serverless edge HTTP handler (fetch(request, env)) built on @cargo-ai/worker-sdk with an auto OpenAPI 3.1 spec at /openapi.json and Swagger UI at /docs; and a Deployment, a single build and upload of a local source directory that is not live until it is promoted. It is used to scaffold, deploy, promote, or manage a hosted app or worker on Cargo.

Apps and workers follow the same lifecycle: scaffold, create slot, deploy, promote. Commands include hosting app init / worker init to scaffold from a template (blank, plus territories-overview for apps and custom-integration for workers), hosting app create / worker create with --name and --slug (the slug becomes the subdomain and must be globally unique), hosting app env to print .env.local lines for local development (workers have no env subcommand), hosting deployment create with a mutually exclusive --app-uuid or --worker-uuid and --source pointing at the package root (not dist/), and hosting deployment promote to go live. The backend builds asynchronously in a sandbox (npm ci && vite build for apps, entrypoint bundling for workers), so deployments must be polled with hosting deployment get until a terminal status (success, error, or cancelled) before promoting only a success build. deployment get-promoted shows what is currently live, and default ignores (node_modules,dist,build,.git,.next) can be overridden with --ignore.

The skill enforces critical rules: deploying is not going live, slug clashes fail at create, --source must be the package root, remove cascades to all deployments, update --folder-uuid null moves a resource to the workspace root, and hosting consumes credits monthly per resource via a chargedUntil field advanced by an hourly sweep, so unused resources should be removed. It requires @cargo-ai/cli (npm) and a Cargo account (browser sign-in via --oauth or an API token), and advises verifying the session with cargo-ai whoami first. Reference files cover app, worker, and deployment examples, response shapes, and troubleshooting, with related skills for workspace folder management and billing.

FAQ

What are the prerequisites?

The @cargo-ai/cli npm package (providing the cargo-ai binary) and a Cargo account, signed in via browser OAuth (--oauth) or an API token (--token). Verify the session with cargo-ai whoami before running commands.

What is the difference between deploying and going live?

A deployment (hosting deployment create) builds and uploads a source directory but is not live until promoted. The live URL only changes when you run hosting deployment promote on a successful deployment. Use hosting deployment get-promoted to see what is currently live.

Why must --source point at the package root and not dist/?

The build runs in a Cargo sandbox, executing npm ci && vite build for apps or entrypoint bundling for workers. Shipping a pre-built dist/ will not work, so --source must be the package root.

How do I know when a deployment is ready to promote?

Builds are asynchronous. Poll hosting deployment get <uuid> (roughly every 2-5 seconds) until the status is terminal. Terminal statuses are success, error, and cancelled, and you should only promote a success deployment.

How does Cargo Hosting billing work and what does remove do?

Hosting consumes credits monthly per resource; each app or worker carries a chargedUntil that an hourly sweep advances a month at a time, so live resources bill on an ongoing basis. Removing an app or worker cascades and also removes all of its deployments, so remove resources you no longer serve.