mirror of https://github.com/getcargohq/cargo-skills.git synced 2026-09-14 19:17:15 +08:00

Files

T

Auree Aubert 53a1a86a7f Add cargo-hosting skill for app and worker deployment (#40 )

* Add cargo-hosting capability skill

Document the `hosting` CLI domain (apps, workers, deployments) as a
dedicated capability skill, following the one-skill-per-CLI-domain
convention.

- cargo-hosting/SKILL.md: init -> create -> deploy -> promote lifecycle
  for Vite SPA apps (*.cargo.app) and edge workers, with critical rules
  and async polling.
- references/examples/{apps,workers,deployments}.md, response-shapes.md,
  troubleshooting.md.
- Register in the cargo router (skill count 10->11, capability table row,
  recap, removed hosting from the no-skill-yet table, synced frontmatter
  count) and bump cargo 1.4.0 -> 1.5.0.
- README capability table + skill count (11 -> 12).
- CHANGELOG entries for cargo-hosting 1.0.0 and cargo 1.5.0.

https://claude.ai/code/session_018LeD9abpD7LYBhGGkDxSup

* Add hosting terms to glossary

Add app/appUuid, deployment/deploymentUuid, hosting, worker/workerUuid
entries to cargo/references/glossary.md, and correct the capability-skill
domain list (was missing content and hosting). CHANGELOG updated.

https://claude.ai/code/session_018LeD9abpD7LYBhGGkDxSup

* Pin hosting response shapes from backend types

Replace inferred shapes/caveats in cargo-hosting with the authoritative
App/Worker/Deployment structures: kind app/worker discriminant,
promotedDeployment, chargedUntil, and the deployment status enum
(pending/building/success/error/cancelled, terminal at the last three).
Polling + build-failure docs now cite the real status/errorMessage/
buildLogS3Filename fields, and a critical rule notes monthly hosting
credits per resource.

https://claude.ai/code/session_018LeD9abpD7LYBhGGkDxSup

---------

Co-authored-by: Claude <noreply@anthropic.com>

2026-06-15 10:30:32 +02:00

2.8 KiB

Raw Permalink Blame History

Worker examples

Workers are serverless HTTP handlers that run on the edge — a standard fetch(request, env) entrypoint built on @cargo-ai/worker-sdk. The blank template ships an automatic OpenAPI 3.1 spec at /openapi.json and Swagger UI at /docs.

Scaffold → create → deploy → promote (end to end)

# 1. Scaffold a local worker project
cargo-ai hosting worker init ./my-api --list-templates
cargo-ai hosting worker init ./my-api --template blank --name "My API"

# 2. Create the workspace slot. --slug is the live subdomain → must be globally unique.
cargo-ai hosting worker create --name "My API" --slug my-api
# → { "uuid": "<worker-uuid>", "slug": "my-api", "url": "https://my-api.cargo.app", ... }

# 3. Build & upload (source = package root). The backend bundles the entrypoint.
cargo-ai hosting deployment create --worker-uuid <worker-uuid> --source ./my-api
# → { "uuid": "<deployment-uuid>", "status": "...", ... }

# 4. Poll until the build is terminal
cargo-ai hosting deployment get <deployment-uuid>

# 5. Promote to go live
cargo-ai hosting deployment promote --uuid <deployment-uuid>

# 6. Confirm what's live, then hit it
cargo-ai hosting deployment get-promoted --worker-uuid <worker-uuid>
curl https://my-api.cargo.app/openapi.json

List and inspect

cargo-ai hosting worker list                       # all workers
cargo-ai hosting worker list --folder-uuid <uuid>  # only workers in one folder
cargo-ai hosting worker get <worker-uuid>          # one worker's details + URL

Templates

cargo-ai hosting worker init ./tmp --list-templates

blank — edge worker on @cargo-ai/worker-sdk with automatic OpenAPI 3.1 spec at /openapi.json and Swagger UI at /docs.
custom-integration — a Cargo Custom Integration worker: manifest / actions / extractors / autocompletes / dynamic schemas, also with /openapi.json. Use this when you're building an integration the rest of Cargo can call as a connector action.

Rename, move, remove

cargo-ai hosting worker update --uuid <worker-uuid> --name "Renamed Worker"
cargo-ai hosting worker update --uuid <worker-uuid> --folder-uuid <folder-uuid>
cargo-ai hosting worker update --uuid <worker-uuid> --folder-uuid null   # back to root
cargo-ai hosting worker remove <worker-uuid>                            # also removes its deployments

App vs worker — when to use which

App — you want a UI on *.cargo.app (dashboard, internal tool, data grid). Vite SPA, app init, has an env subcommand for local dev.
Worker — you want an HTTP endpoint with no UI (webhook receiver, API, custom integration backend). Edge fetch handler, worker init, no env subcommand — runtime config arrives via the env argument to fetch.

2.8 KiB Raw Permalink Blame History