# CargoForge > CargoForge hosts docker-compose.yml applications. Every service runs in its own lightweight VM (Kata Containers) with a fixed CPU/memory allocation, gets a public HTTPS hostname for each published port, and sleeps when idle on the free plan. Everything the dashboard does is a REST API an agent can drive with an API key. - Dashboard: https://crane.cargoforge.dev - API base URL: https://api.cargoforge.dev - OpenAPI spec (every endpoint, request and response shape): https://api.cargoforge.dev/openapi.json - Interactive API docs: https://api.cargoforge.dev/docs ## Authentication API access requires the **Cargo** (paid) plan. Everything an agent does is billed to that account like the rest of its usage. On the free Freight plan, API keys can't be created and existing ones are refused with `403` and `"code": "api_access_requires_paid_plan"`; ask the account's owner to upgrade under Billing. Create an API key in the dashboard under **API Keys** (https://crane.cargoforge.dev/api-keys). It is shown once. Send it on every request: ``` Authorization: Bearer ``` New keys default to the **Deploy** scope and expire after 90 days (1-365 days, or never). Give each key the narrowest scope that works: - **Deploy** (recommended for agents): create projects, validate and deploy compose files, start/stop/restart, set env vars, read logs, backups, park/unpark. Cannot delete projects or touch billing, team, API keys, the account, or repo connections. - **Read only**: every `GET`, plus validating a compose file and fetching logs. - **Full access**: everything the user can do, including deleting projects. A call outside the key's scope gets `403` naming the scope and the route. An expired key gets `401` saying it expired; ask the user for a new one. A key may also have limits the user set: a monthly spend limit and a maximum number of containers, both counting only what that key deployed. Going over gets `403` with `"code": "api_key_spend_limit_reached"` or `"api_key_container_limit_reached"`, and `validate` reports them too. Don't work around them: stop something the key deployed, or ask the user to raise the limit (keys can't change limits). `GET /api-keys` shows each key's limits and current usage. Everything a key does appears in the user's activity feed under the key's name and your User-Agent, so send a descriptive one. Keep keys out of logs and commits. The account's email must be verified before projects can be created or deployed. ## MCP server (the easiest way for an agent) CargoForge is a remote MCP server at `https://api.cargoforge.dev/mcp` (streamable HTTP). Two ways to authenticate; either way the scope, limits and the Cargo plan apply exactly as on the REST API: - **Sign in (OAuth 2.1).** Clients that support MCP authorization (claude.ai custom connectors and others) only need the URL: the server answers `401` pointing at `/.well-known/oauth-protected-resource/mcp`, the client registers itself, and the user approves on a CargoForge consent page, choosing the scope and optional limits. Access tokens last an hour; refresh them. - **API key.** Send a key from the dashboard as a bearer token: Claude Code: ``` claude mcp add --transport http cargoforge https://api.cargoforge.dev/mcp --header "Authorization: Bearer " ``` Clients configured with JSON (Cursor, and others): ```json {"mcpServers": {"cargoforge": {"url": "https://api.cargoforge.dev/mcp", "headers": {"Authorization": "Bearer "}}}} ``` Tools: `list_projects`, `create_project`, `validate_compose`, `deploy_compose`, `wait_for_deployment`, `list_deployments`, `get_endpoints`, `get_logs`, `restart_deployment`, `stop_deployment`, `start_deployment`, `set_env_var`, `list_env_vars`, `list_containers`. `create_project` and `deploy_compose` take an optional `idempotency_key`. `wait_for_deployment` and `get_logs` wait at most 90 seconds per call (default 60 and 30); call `wait_for_deployment` again while `settled` is false. ## Deploy a compose file (the whole loop) 1. Create a project (once). Send an `Idempotency-Key` so a retried request returns the same project instead of failing: ``` POST /projects Idempotency-Key: {"name": "my-app"} ``` 2. Check the compose file without deploying it (free, changes nothing). Always 200; read `valid`: ``` POST /projects/{project_id}/deployments/validate {"compose_yaml": ""} -> {"valid": true|false, "errors": [...], "notices": [...], "processed_spec": {...}|null} ``` `errors` would make the deploy fail. `notices` list parts of the file that are accepted but not applied as written (skipped `profiles:` services, ignored keys, a reservation used as the limit). `processed_spec` is exactly what would run. Fix and repeat until `valid` is true and the notices are what you expect. 3. Deploy it. Send an `Idempotency-Key`; a retry with the same key and the same file returns the same deployment (200) instead of creating another; the same key with a different file is a 409: ``` POST /projects/{project_id}/deployments Idempotency-Key: {"compose_yaml": "..."} ``` 4. Poll until it settles (every 5-10 s is plenty): ``` GET /projects/{project_id}/deployments/{deployment_id} ``` `actual_state`: `running` (done), `failed` (see `last_error`), `degraded` (up, but a service keeps crashing or couldn't start, e.g. its image doesn't exist: see `degraded_reason`), or still in progress. `last_failure` keeps the latest unresolved error even after the state changes. `GET .../jobs` shows each step. 5. Find the public URLs: `GET /projects/{project_id}/endpoints` (one hostname per published port, served over HTTPS). 6. Read logs: `POST /projects/{project_id}/deployments/{deployment_id}/logs` returns a `job_id`; poll `GET .../logs/{job_id}` until `status` is `succeeded`, then `logs` maps each service name to its recent output. Other useful calls: `GET /containers` (every container across your projects with state and live CPU/memory), `GET /projects/{project_id}/resource-usage`, `PUT /projects/{project_id}/env-vars/{KEY}` with `{"value": "..."}` (secrets: set them here, not in the compose file), `POST .../deployments/{deployment_id}/restart`, `.../stop`, `.../start`. ## Compose rules that differ from plain `docker compose up` - **Images only, or a connected repo.** `build:` works only for a project connected to GitHub/GitLab (builds from the repo on push). Otherwise every service needs `image:`. - **Published ports get a public hostname, not the host port you asked for.** The left side of `"8080:80"` is ignored; the service is reached at `https://-.fastlayer.com`. Unpublished services are reachable only by their siblings. - **Sizing.** Set `mem_limit`/`cpus`, or `deploy.resources.limits` (`memory`, `cpus`). Not both with different values. A service with neither gets 1 GB / 0.5 vCPU. Each service runs with a fixed allocation equal to its limit and is billed on it. A reservation only matters when no limit is set (it's used as the limit). - **Project size ceiling.** Total declared RAM/CPU across all services: 4 GB / 2 vCPU on Freight (free), 8 GB / 4 vCPU on Cargo (paid). Larger projects need Fleet (a dedicated server). - **Storage per service:** `x-cargoforge: {storage_limit_gb: }` (default 2 GB). Named volumes persist across redeploys. - **Redeploys and fragile services.** A redeploy starts the new copy of a service before stopping the old one (no downtime), except for a *fragile* service: its old copy stops cleanly first, so two copies never run at once. A service with a volume is fragile by default (two databases on one data directory corrupt it). Set `x-cargoforge: {fragile: true}` for one without a volume that must never run twice (a bot, a scheduler, a queue consumer), or `{fragile: false}` for a volume that's safe to share (an uploads folder) to keep zero-downtime deploys; `validate` warns about `false` on a database image. A fragile service's memory is only lowered with a restart. Stops honor `stop_grace_period` (up to 2m; default 30s for a fragile service, else 10s) and `stop_signal`. - **`profiles:`** Services behind a profile are never deployed (no profile is ever activated). - **Service names resolve to siblings** (`db:5432` works). This is done by writing `/etc/hosts` with the container's own `sh`/`cat`, so an image with no shell (distroless, `scratch`) can be reached by name but cannot look names up itself. - **Not allowed:** `privileged`, host `network_mode`/`pid`/`ipc`, host `devices`, bind-mounting host paths (use named volumes), and capabilities, sysctls or `security_opt` values that weaken the sandbox. `validate` reports each one. - **Crash loops.** A service that keeps exiting marks the deployment `degraded`; after 15 minutes the platform stops that service's container. Fix it and redeploy or restart. ## Plans - **Freight (free):** dashboard only, no API access. Up to 3 projects, small services, projects sleep when idle and wake on the next request. - **Cargo (paid):** API access for scripts, CI and agents; metered per vCPU-hour, MB-hour and GB-hour; always-on option, custom domains, push-to-deploy, pull-request previews. - **Fleet:** dedicated servers for larger projects. Pricing: https://cargoforge.dev/#pricing