Provisioning

Endpoints that drive the Devcontainers pipeline: discover available features and runtimes, trigger or rebuild a crew’s cached image, and inspect the local cache. Implementation lives in internal/api/crew_provisioning_jobs.go and internal/api/crew_provisioning_cache.go; the underlying provisioner is in internal/devcontainer/.

All routes require authentication and are workspace-scoped where they touch crew rows.

Endpoints

Method	Endpoint	Purpose
GET	`/api/v1/features/catalog`	List installable devcontainer features
GET	`/api/v1/runtimes/catalog`	List mise-managed runtimes
GET	`/api/v1/crews/{crewId}/provision`	Get crew provision status
POST	`/api/v1/crews/{crewId}/provision`	Trigger a provision
GET	`/api/v1/crews/{crewId}/provision/revisions`	Read bounded immutable build history
POST	`/api/v1/crews/{crewId}/rebuild`	Rebuild without reusing the build cache
POST	`/api/v1/crews/{crewId}/restart-agents`	Recreate the runtime container without rebuilding
GET	`/api/v1/crews/{crewId}/image-status`	Report whether the running container is behind its image tag
POST	`/api/v1/crews/{crewId}/refresh-image`	Pull the current image and recycle the container
GET	`/api/v1/cache/images`	List cached images
DELETE	`/api/v1/cache/images/{tag}`	Delete a cached image

Environment revisions

GET /api/v1/crews/{crewId}/provision/revisions

Auth: Authenticated workspace member with the read action. Request: crewId path parameter; no body or pagination parameters. Response: JSON object containing revisions and the fixed limit: 100, newest records first. Statuses: 200 OK; 401 Unauthorized at authentication middleware; 403 Forbidden without the read role; 404 Not Found for a missing, deleted or other-workspace crew; 500 Internal Server Error on storage/evidence errors. Each revision contains id, definition_hash, build_hash, image_id, created_at and nullable toolchain inventory/qualification evidence. Raw configuration values and credentials are omitted. Empty history returns an empty array. Records describe builds, not running containers; this endpoint neither checks whether image bytes still exist nor performs retention or rollback.

{"revisions": [], "limit": 100}

Catalogs

Discover the features and runtimes a crew can pin in its devcontainer_config.

Feature catalog

GET /api/v1/features/catalog?search=…

Auth: Authenticated request. Request: optional search query parameter; no body. Response: JSON object with a features array. Statuses: 200 OK on success; the catalog remains available through the documented fallback when the dynamic fetch fails. Lists devcontainer features Crewship can install. The dynamic fetcher pulls from upstream registries (ghcr.io/devcontainers/features/*, ghcr.io/devcontainers-extra/features/*, ghcr.io/crewship-ai/features/*); when that fails, the handler falls back to internal/devcontainer.FallbackCatalog so the UI is never empty. ?search= filters by name, description, or category (server-side substring). Response: 200 OK

{
  "features": [
    {
      "ref": "ghcr.io/devcontainers/features/python:1",
      "name": "Python",
      "description": "Installs the specified Python version, pip, and pipx. Supports virtual environments.",
      "category": "languages",
      "icon": "code",
      "size_hint": "~80 MB"
    }
  ]
}

Field	Description
`ref`	OCI reference — what you put in `devcontainer_config.features`.
`category`	One of `languages`, `tools`, `cloud`, `databases`.
`icon`	Lucide icon name for UI rendering.
`size_hint`	Approximate installed-size delta (`~80 MB`).

Unknown publishers (anything outside the three allowlisted prefixes) are rejected at provisioning time even if they appear in a custom catalog — see internal/devcontainer/features.go.

Runtime catalog

GET /api/v1/runtimes/catalog?search=…

Auth: Authenticated request. Request: optional search query parameter; no body. Response: JSON object with a runtimes array. Statuses: 200 OK on success; the catalog uses the documented fallback when the dynamic fetch fails. Lists the mise-managed runtimes (Node, Python, Go, Terraform, kubectl, …) the workspace can pin in devcontainer_config.mise. Falls back to FallbackRuntimeCatalog when the dynamic fetcher fails. Not a base-image catalog. The base-image list is CLI-only — crewship features base-images reads baseImagesCatalog directly from cmd/crewship/cmd_features.go; there is no HTTP endpoint for it today. Response: 200 OK

{
  "runtimes": [
    {
      "name": "Node.js",
      "tool": "node",
      "description": "JavaScript runtime.",
      "category": "languages",
      "icon": "hexagon",
      "versions": ["22", "20", "18"],
      "default_version": "22",
      "backends": ["asdf"]
    }
  ]
}

Field	Description
`tool`	Mise tool ID — what you put in `mise.json`.
`category`	Same set as the feature catalog: `languages`, `tools`, `cloud`, `databases`.
`versions`	Available versions, ordered newest-first. May be empty when mise resolves dynamically.
`default_version`	What Crewship picks when the crew config does not pin one.
`backends`	Mise install backends (`asdf`, `cargo`, `npm`, `pipx`, `github`). Empty → mise default.

Crew provisioning lifecycle

Inspect, trigger, rebuild, and recycle a crew’s cached image and runtime container.

Provision status

GET /api/v1/crews/{crewId}/provision

Auth: Authenticated workspace request; crewId must belong to that workspace. Request: crewId path parameter; no body. Response: JSON provision-status object described below. Statuses: 200 OK; 404 Not Found when the crew is not in the workspace; 503 Service Unavailable when provisioning is not configured. Response: 200 OK. Always-present fields come from the crews row; the step / total / message / steps / log_tail / started_at / completed_at / error fields appear when an in-memory job is currently running or recently finished for this crew. error, log_tail and completed_at also surface without a live job when the crew’s most recent build outcome was a failure — they are read back from the journal, so they survive the in-memory job’s TTL and a server restart.

{
  "status": "running",
  "devcontainer_config": "{\"image\":\"…\",\"features\":{…}}",
  "cached_image": null,
  "config_hash": "a1b2c3d4e5f6…",
  "agents_pending_restart": 0,
  "step": 3,
  "total": 6,
  "message": "installing devcontainer features",
  "steps": ["validate", "pull-base", "install-features", "install-mise", "snapshot", "tag"],
  "log_tail": ["Feature python installed", "Feature node installed"],
  "started_at": "2026-04-30T11:01:18Z"
}

status is one of:

Value	Meaning
`idle`	No active job and no `cached_image` — crew has nothing built or in flight.
`pending`	Job enqueued, not yet picked up.
`running`	Provisioner is mid-pipeline.
`completed`	Cached image exists at `cached_image` (no active job).
`failed`	Job ended in failure. `error` carries the reason.

Field	When present	Meaning
`devcontainer_config`	always	The effective devcontainer JSON: the crew’s own `devcontainer_config`, or the built-in default when the crew never set one.
`devcontainer_config_defaulted`	always	`true` when `devcontainer_config` is the built-in default rather than a config the crew set.
`cached_image`	always	The currently selected image. On Docker this is the immutable local image ID (`sha256:…`) of the last successful build — the `crewship-cache:*` tag is only a cache lookup alias. Native build providers report the image tag. Null when nothing is built.
`config_hash`	always	SHA-256 over (base image, devcontainer, mise, generated-build fingerprint, required adapter CLIs, provisioner schema version) used as the cache key — a newly required adapter CLI changes it, an agent on an already-covered adapter does not.
`toolchain`	always	`{requested, built}`: the tool selectors the current config and the crew’s live adapters imply, kept separate from the inventory/qualification evidence bound to the selected built image. `built` is null until a build with recorded requirements is selected.
`resolved_features`	when provenance was recorded	Feature provenance records for the last build: `ref`, `id` and `pinned` are always present; `version` and `digest` are omitted when unknown. The key itself is absent — not `[]`, not `null` — when the crew predates provenance recording (#1779), and invalid stored provenance JSON is also omitted. Valid stored `[]` and `null` remain an empty array and JSON null respectively.
`agents_pending_restart`	always	Count of crew agents whose live container is on a stale image.
`step` / `total`	active job	Numeric progress (e.g. `3 / 6`). The UI’s `CrewProvisioningCard` renders a checklist from this pair.
`message`	active job	Free-form short message for the current step.
`steps`	active job	Ordered list of step labels for the whole pipeline.
`log_tail`	active job	Trailing log lines (bounded) for inline display.
`started_at`	active job	RFC3339 start time.
`completed_at`	finished job	RFC3339 end time (only after `completed`/`failed`).
`error`	failed job	Human-readable failure reason.

Trigger provision

POST /api/v1/crews/{crewId}/provision

Auth: Authenticated caller with the create role action. Request: crewId path parameter; no body. Response: JSON { "status": "started", "message": "…" }. Statuses: 202 Accepted; 400, 403, 404, 409, 429, 500, or 503 for the conditions listed below. Requires the create role action (OWNER, ADMIN, MANAGER). Returns 202 immediately and runs the pipeline in a background goroutine; poll the status endpoint for progress.

This builds an image. It does not start a container. A completed provision leaves the crew’s cached_image set and its container stopped — the container is created lazily on the crew’s first agent run. On a cache hit the job reaches completed in seconds having started nothing at all. A cache hit is confirmed against the Docker daemon before it is reported: a crewship-cache:* tag removed outside Crewship (docker rmi, docker system prune) is rebuilt, not reported present from a stale image list.A chat message that arrives while the crew is unstartable is parked on the build and resumed when it completes. If the completed build still leaves the image missing from the daemon, the message is deferred to another build — with a back-off of 2 s, then 4 s, each plus a random jitter of up to one step (so several chats deferred by the same pruned image do not re-enqueue in lock step; capped at 30 s) — and after 3 consecutive rebuilds it gives up: the session receives a streamed error event whose metadata carries reason: "provisioning_loop" and rebuilds: 3, followed by done, and the message is not retried. Check the server logs and docker images for whatever is removing crewship-cache:* images, then send the message again (#2431).To start the container, call POST /api/v1/crews/{crewId}/container-start, which provisions first if the crew has no image and then starts it.

Response: 202 Accepted

{
  "status": "started",
  "message": "Provisioning started. Monitor with 'crewship crew provision status <slug>'."
}

Errors: provisioning admission failures use RFC 7807 Problem Details (type, title, status, detail, instance) as application/json. Authentication, workspace and role guards use { "error": "…" }; rebuild also uses that envelope for unexpected enqueue failures.

Status	Condition
400	Invalid crew ID. A crew with no `devcontainer_config` is provisioned from the built-in default, not rejected.
403	Caller lacks `create` permission.
404	Crew not in workspace.
409	A provisioning job is already in progress for this crew. The 409 body extends Problem Details with `job_status` (the existing job’s state) so callers can decide whether to wait or fall through. Not idempotent — the second caller is told to back off, not silently joined to the running job.
429	Per-workspace rate limit exceeded.
500	Unexpected server-side error (panic-recovered).
503	Provisioner not configured (no Docker client wired).

Rebuild

POST /api/v1/crews/{crewId}/rebuild

Auth: Authenticated caller with the create role action. Request: crewId path parameter; no body. Response: the same JSON shape as the trigger endpoint. Statuses: 202 Accepted; 400, 401, 403, 404, 409, 429, 500, or 503 when the corresponding provisioning or middleware condition applies. Triggers a fresh build that bypasses the provisioned-image cache and the installation-layer caches, so floating tool selectors can resolve newer versions. The previously selected image stays in place until the new build publishes: a failed or superseded rebuild leaves the previous image and its requirements selected, and the crew remains startable throughout. Use when upstream features publish breaking updates under the same tag.

The cache bypass belongs to the build, not to the crew row — the previous image is not discarded up front. A running container is not replaced either: it keeps its image until the new one activates (see Immutable Docker build references).

Response: 202 Accepted — same shape as Trigger.

Restart agents

POST /api/v1/crews/{crewId}/restart-agents

Auth: Authenticated caller with the update role action. Request: crewId path parameter; no body. Response: JSON { "restarted": <count> }. Statuses: 200 OK; 400, 403, 404, 500, or 503 for the conditions listed below. Force-removes the crew’s runtime container so the next agent exec recreates it from the current cached_image — without rebuilding the image. Used when an env-var change should take effect without the cost of a new image. Idempotent: when no container is running it still returns 200 OK with { "restarted": 0 }. Requires the update role action (OWNER, ADMIN, MANAGER). Response: 200 OK with { "restarted": <count> } — the count is the number of non-deleted agents in the crew (they share one container, so all are recreated together).

Status	Condition
400	Empty crew ID.
403	Caller lacks `update` permission.
404	Crew not in workspace.
500	DB error or Docker `ContainerRemove` failure.
503	Docker client not configured.

Image freshness

A crew container is created once and reused until something recreates it. On a long-lived crew that can be weeks, during which the image tag it was built from keeps moving — so the container quietly becomes a snapshot of an older release. These two endpoints report that and fix it. See Keeping crew images current for the full story, including the daily check and the notification it raises.

Image status

GET /api/v1/crews/{crewId}/image-status

Auth: Authenticated workspace request; any workspace role, including VIEWER — noticing that a crew is behind is a read. Request: crewId path parameter; no body. Response: JSON object with crew_id, image, container_id, running, running_digest, resolved_digest, behind and reason. Statuses: 200 OK; 400 on an empty crew ID, 404 when the crew is not in the workspace, 500 on a daemon failure, 503 when no container provider can report image digests. Compares the registry manifest digest the crew’s running container was created from against what its tag resolves to on the registry right now. It never pulls and never restarts anything.

{
  "crew_id": "c8f2…",
  "image": "ghcr.io/crewship-ai/agent-runtime:latest",
  "container_id": "3f1a9c02b7de",
  "running": true,
  "running_digest": "sha256:1111…",
  "resolved_digest": "sha256:2222…",
  "behind": true,
  "reason": ""
}

behind: false is not the same as “current”. Read reason alongside it — registry unreachable, no container, image has no registry digest and locally built image all report behind: false because nothing could be compared. Only an empty reason with behind: false means the two digests were compared and agreed.

Status	Condition
400	Empty crew ID.
404	Crew not in workspace.
500	Container runtime could not be queried.
503	No container provider, or a provider that cannot report image digests.

Refresh image

POST /api/v1/crews/{crewId}/refresh-image

Auth: Authenticated caller with the update role action (OWNER, ADMIN, MANAGER). Request: crewId path parameter; no body. Response: JSON object with crew_id, image, previous_digest, new_digest and container_removed. Statuses: 200 OK; 400, 403, 404, 500, or 503 for the conditions listed below. Pulls the crew’s configured image, then force-removes its runtime container so the next agent exec recreates it from the fresh copy. The pull happens first: if it fails, the crew is left exactly as it was rather than without a container and without an image. Idempotent — a crew that is already current transfers nothing, and one with no container has nothing to drop (container_removed: false).

Agents executing in the container when it is removed are interrupted.

Not the same as Restart agents. restart-agents drops the container without pulling, which picks up a devcontainer image you have already rebuilt locally. refresh-image pulls first, which is what picks up a base image that has moved on in the registry.

Status	Condition
400	Empty crew ID.
403	Caller lacks `update` permission.
404	Crew not in workspace.
500	The pull failed (a throttling registry is the common cause), or the container could not be removed.
503	No container provider, or a provider that cannot report image digests.

Cache image registry

Inspect and prune the locally built crewship-cache:* images. This registry is per-host, not per-workspace — see Tenancy.

List cached images

GET /api/v1/cache/images

Auth: Authenticated workspace request. Request: no body or required query parameters. Response: JSON object with an images array. Statuses: 200 OK; 500 on Docker image-list failure; 503 when Docker is not configured. Response: 200 OK

{
  "images": [
    {
      "tag": "crewship-cache:a1b2c3d4e5f6",
      "size": 824191022,
      "created_at": 1714415721,
      "referenced_by": ["backend"]
    }
  ]
}

Field	Type	Description
`tag`	string	The `crewship-cache:*` image tag.
`size`	integer	Image size in bytes.
`created_at`	integer	Image creation time as Unix seconds (from the Docker image summary), not an RFC3339 string.
`referenced_by`	string[]	Slugs of live crews referencing this tag (workspace-scoped).

Requires the read role action (any workspace member). Returns 503 ({ "error": "cache management not available (Docker client not configured)" }) when no Docker client is wired, and 500 on a Docker ImageList failure. Images orphaned from any crew (i.e. referenced_by is empty) are eligible for the GC sweeper. See CREWSHIP_CACHE_GC_AUTODELETE.

Delete cached image

DELETE /api/v1/cache/images/{tag}

Auth: Authenticated caller with the delete role action (ADMIN or OWNER). Request: tag path parameter and optional force=true query parameter; no body. Response: JSON deletion result with tag and status. Statuses: 200 OK; 400 for an invalid tag, 403 for insufficient role, 409 when a referenced image is not forced, 500 for Docker removal failure, or 503 when Docker is not configured. Removes a cached image. By default refuses to delete an image still referenced by a live crew (returns 409 Conflict). Pass ?force=true to delete anyway.

?force=true removes an image even while live crews reference it — their next agent run rebuilds from scratch.

Requires the delete role action (OWNER, ADMIN only — a MANAGER is rejected with 403). Response: 200 OK

{ "tag": "crewship-cache:a1b2c3d4e5f6", "status": "deleted" }

A 409 Conflict body lists the referencing crew slugs under referenced_by. The reference check is host-global — it counts crews in any workspace, so an image another tenant still uses cannot be force-free-deleted by accident:

{
  "error": "image is referenced by live crews; pass ?force=true to delete anyway",
  "referenced_by": ["backend"]
}

Errors:

Status	Condition
400	Empty `tag`, or `tag` outside the `crewship-cache:` namespace (`{ "error": "only crewship-cache:* tags may be deleted" }`).
403	Caller is below the `ADMIN` role.
409	Image still referenced by a live crew and `?force=true` not set.
500	Docker `ImageRemove` failed.
503	Docker client not configured (`{ "error": "cache management not available (Docker client not configured)" }`).

Tenancy

crewId on the provision-status / trigger / rebuild / restart-agents routes is validated against the session workspace via the crews.workspace_id SELECT; a crew in another workspace returns 404.
The cache image registry is per-host, not per-workspace — operators sharing a Docker daemon will see each other’s tags, and the cache routes do not workspace-scope the {tag} path param. GET /cache/images scopes only the referenced_by annotation to the caller’s workspace; DELETE /cache/images/{tag} deliberately checks references across all workspaces so a tag another tenant depends on cannot be deleted without ?force=true. There is no cross-tenant 404 on a {tag} — the tag namespace is shared by design.

Devcontainers guide — full provisioning pipeline.
crewship features, crewship runtimes — CLI wrappers.
Configuration — Devcontainer Cache GC — CREWSHIP_CACHE_GC_AUTODELETE.

​Provisioning

​Endpoints

​Environment revisions

​Catalogs

​Feature catalog

​Runtime catalog

​Crew provisioning lifecycle

​Provision status

​Trigger provision

​Rebuild

​Restart agents

​Image freshness

​Image status

​Refresh image

​Cache image registry

​List cached images

​Delete cached image

​Tenancy

​Related

Provisioning

Endpoints

Environment revisions

Catalogs

Feature catalog

Runtime catalog

Crew provisioning lifecycle

Provision status

Trigger provision

Rebuild

Restart agents

Image freshness

Image status

Refresh image

Cache image registry

List cached images

Delete cached image

Tenancy

Related