Devcontainer Configuration

This page is the flat reference for every field, env var, and CLI flag that governs Crewship’s devcontainer runtime. For the step-by-step narrative, see Guides → Devcontainers & Runtime Images.

Per-crew fields

Stored on the crews table, settable via UI wizard, REST PATCH, or crewship crew config.

Column	Type	Default	Notes
`runtime_image`	string	`debian:bookworm-slim` (global default) / `mcr.microsoft.com/devcontainers/base:bookworm` (seeds)	OCI reference. Glibc Linux only. Whitespace/control chars rejected.
`devcontainer_config`	JSON string	`NULL`	Subset of `devcontainer.json`. Max 100 KB. Validated at write time.
`mise_config`	JSON string	`NULL`	`{"tools":{…}}` map. Max 10 KB.
`cached_image`	string	`NULL`	Populated by the provisioner on success: `crewship-cache:{hash[:12]}`.
`config_hash`	string	`NULL`	SHA-256 of `(runtime_image, devcontainer_config, mise_config)`.

`devcontainer_config` schema

Parser: internal/devcontainer/config.go:Config.

Field	Type	Required	Purpose
`image`	string	✓	Base image reference. Must equal `runtime_image` at the API boundary.
`features`	`map[featureRef]options`	—	Community devcontainer features. Accepts tag form (`ghcr.io/…/python:1`) and SHA256 digest form (`ghcr.io/…/python@sha256:abc…`). Digest form pins the exact artifact — recommended for paid/shared templates where an upstream tag rewrite would silently ship new code to every customer.
`postCreateCommand`	`string` \| `[]string` \| `map[string]string`	—	Commands run as `agent` user (UID 1001) once during provisioning. Baked into the cached image. Changes invalidate the cache.
`postStartCommand`	`string` \| `[]string` \| `map[string]string`	—	Commands run as `agent` user (UID 1001) on every container start / restart. Not baked into the image; changes do not invalidate the cache. Use for “start local services” style init. Failures log a warning but do not block the container.
`containerEnv`	`map[string]string`	—	Env vars baked into the cached image (via `ENV` on commit).
`remoteUser`	string	—	Default user for commands. Only `"agent"` / `"1001"` / empty are accepted — other values are rejected with HTTP 400. Crewship always runs as UID 1001.

Allowed feature registries

Feature IDs are validated against an allowlist in internal/devcontainer/features.go to avoid arbitrary OCI artifact execution. Accepted prefixes:

ghcr.io/devcontainers/features/* — official
ghcr.io/devcontainers-extra/features/* — extras (claude-code, opencode, codex, …)
ghcr.io/devcontainers-community/features/*
ghcr.io/crewship-ai/features/* — reserved for first-party features

Dependencies declared in a feature’s devcontainer-feature.json installsAfter (either spec form ["common-utils"] or legacy wild form [{"id":"common-utils"}]) are honoured by the topological sort in SortFeatures.

Canonical feature set for every Crewship crew

These two are considered the minimum to turn a bare Debian/Ubuntu image into a working Crewship crew container:

"features": {
  "ghcr.io/devcontainers/features/common-utils:2": {
    "username": "agent",
    "userUid": "1001",
    "userGid": "1001",
    "installZsh": false
  },
  "ghcr.io/devcontainers-extra/features/claude-code:2": {}
}

common-utils creates the agent user at UID 1001 and installs curl, git, ca-certificates, sudo. Replaces the deleted EnsureAgentUser Go helper.
claude-code installs Node.js 22 (NodeSource) + @anthropic-ai/claude-code globally. Replaces the deleted EnsureClaudeCode Go helper.

`mise_config` schema

{
  "tools": {
    "<tool>": "<version>"
  }
}

Provisioner installs mise as the agent user, then mise install per tool. Versions follow mise semantics (latest, 22, 22.11.0, lts).

Environment variables

Extend the main environment reference. These govern the bind-mount pipeline.

Variable	Default	Description
`CREWSHIP_SIDECAR_PATH`	autodetected	Absolute path to the `crewship-sidecar` Go binary on the host.
`CREWSHIP_ENTRYPOINT_PATH`	autodetected	Absolute path to `entrypoint.sh` on the host.
`CREWSHIP_SKIP_SIDECAR`	(unset)	Set to `1` to bypass the fail-fast check. Intended for unit tests; never set in production.
`CREWSHIP_RUNTIME_IMAGE`	`debian:bookworm-slim`	Global default base image if a crew has no explicit `runtime_image`.

Autodetect order

internal/config/config.go:autodetectSidecarPaths walks these candidates and picks the first hit: Sidecar binary

{dir of executable}/crewship-sidecar — tar.gz / installer layout
{dir of executable}/../libexec/crewship-sidecar — Homebrew layout
{dir of executable}/../libexec/crewship/crewship-sidecar — deb/rpm FHS layout (/usr/libexec/crewship/)
/usr/local/bin/crewship-sidecar

Entrypoint script

{dir of executable}/entrypoint.sh — tar.gz / installer layout
{dir of executable}/../libexec/entrypoint.sh — Homebrew layout
{dir of executable}/../libexec/crewship/entrypoint.sh — deb/rpm FHS layout (/usr/libexec/crewship/)
{cwd}/scripts/entrypoint.sh
{cwd}/entrypoint.sh
/usr/local/share/crewship/entrypoint.sh

The executable directory is resolved through symlinks first, so a Homebrew-symlinked crewship on your PATH resolves to its real Cellar directory (where the libexec sibling lives). If either remains empty and CREWSHIP_SKIP_SIDECAR != 1, config.Load returns a descriptive error and the server refuses to start.

REST endpoints

Method	Path	Handler	Purpose
`GET`	`/api/v1/crews/{crewId}/provision`	`ProvisioningHandler.ProvisionStatus`	Current status + cached image tag + config hash.
`POST`	`/api/v1/crews/{crewId}/provision`	`ProvisioningHandler.ProvisionTrigger`	Enqueue async provisioning; returns `202 Accepted`.
`POST`	`/api/v1/crews/{crewId}/rebuild`	`ProvisioningHandler.ProvisionRebuild`	Clear cache marker + re-provision.
`GET`	`/api/v1/features/catalog`	feature/runtime catalog handler	Dynamic devcontainer + mise catalog for UI (3-tier cache).
`GET`	`/api/v1/runtimes/catalog`	runtime catalog handler	Curated base-image + mise runtime list (the `cmd_features.go` / `cmd_runtimes.go` CLI commands hit these same endpoints).

REST contract

All routes in this section require an authenticated request. Crew routes also require workspace context and resolve crewId within that workspace.

GET /api/v1/crews//provision

Auth: Authenticated workspace request. Request: crewId path parameter; no body. Response: 200 OK with the current status, cached image tag, and config hash. Statuses: 200 OK or 404 Not Found when the crew is not in the caller’s workspace.

POST /api/v1/crews//provision

Auth: Authenticated workspace caller with the provisioning write permission. Request: crewId path parameter; no body. Response: 202 Accepted when the asynchronous job is queued. Statuses: 202 Accepted, or 400, 403, 404, 409, 429, 500, or 503 for the validation, permission, workspace, duplicate-job, rate-limit, server, or Docker-configuration conditions described in the provisioning reference.

POST /api/v1/crews//rebuild

Auth: Authenticated workspace caller with the provisioning write permission. Request: crewId path parameter; no body. Response: 202 Accepted when the cache marker is cleared and re-provisioning is queued. Statuses: 202 Accepted, or 403, 404, 409, 429, 500, or 503 for the corresponding conditions.

GET /api/v1/features/catalog

Auth: Authenticated request. Request: optional search query parameter; no body. Response: 200 OK with a features array. Statuses: 200 OK; the handler uses its catalog fallback when the dynamic fetch fails.

GET /api/v1/runtimes/catalog

Auth: Authenticated request. Request: optional search query parameter; no body. Response: 200 OK with a runtimes array. Statuses: 200 OK; the handler uses its catalog fallback when the dynamic fetch fails. All endpoints require a workspace-authenticated user. ProvisionTrigger returns 503 Service Unavailable if the Docker client is not configured on the server.

CLI flags

crewship crew config <slug>
  --show                    Print current config as YAML.
  --export                  Export runtime configuration as JSON to stdout.
  --clear                   Remove runtime_image + devcontainer_config + mise_config.
  --devcontainer <path>     Load JSON from path and PATCH devcontainer_config.
  --mise <path>             Load JSON from path and PATCH mise_config.
  --runtime-image <ref>     PATCH runtime_image only.

crewship crew provision <slug>                # trigger async
crewship crew provision status <slug>         # poll
crewship crew rebuild <slug>                  # invalidate + trigger

Flags are mutually exclusive; combining them errors out before hitting the API.

Provisioning states

Emitted by ProvisionStatus + WebSocket channel provision:{crewId}:

State	Meaning
`idle`	No config yet, or cached image in sync with hash.
`pending`	Job enqueued, goroutine not yet started.
`running`	Active — installing features / mise / running postCreate.
`success`	Cache image committed, `cached_image` + `config_hash` written.
`failed`	Commit never happened; error recorded. Re-run with `crewship crew rebuild`.

Validation rules

Enforced in internal/api/crews.go write paths and devcontainer.Config.Validate:

image / runtime_image: non-empty, no whitespace/control chars, ≤ 512 chars.
features: keys match the allowlisted registries above.
postCreateCommand: ≤ 4096 chars per entry, no null bytes.
containerEnv: ≤ 32 keys, each key [A-Z_][A-Z0-9_]*.
mise_config: well-formed JSON, tools map only, ≤ 32 entries.
Total devcontainer_config blob ≤ 100 KB.
Total mise_config blob ≤ 10 KB.

Cache image naming

Successful provisions commit a reusable layer tagged crewship-cache:{hash[:12]}, where hash is the SHA-256 of (runtime_image, devcontainer_config, mise_config). The full 64-char hash is written to crews.config_hash; the truncated 12-char form is used as the image tag so docker images stays legible.

Cache hit — provisioner sees the crewship-cache:{hash[:12]} image already exists and the crew row is in sync. No work is done; cached_image is kept.
Cache miss — hash differs from crews.config_hash, or the tagged image was pruned. Full feature + mise install runs and the new image is committed under the new hash.

Two crews with identical configs share the same cache image (deduped on first provision). Pushing a custom containerEnv key or tweaking postCreateCommand changes the hash and creates a fresh cache image; the old one becomes eligible for GC after its last crew migrates off.

Runtime base-image digest check

internal/dockerutil/imagedigest.go keeps a HEAD-manifest cache of remote base-image digests (DefaultDigestTTL = 24 * time.Hour). On a provision request, the resolver checks whether the caller’s runtime_image reference still resolves to the digest baked into the existing cache image. If the registry has moved the tag (security update, rolled release), the provisioner treats the cache as stale even when the config_hash is unchanged and rebuilds.

TTL: 24 hours. Empty/negative results are also cached so a missing upstream does not trigger a HEAD storm.
Bypass: pin runtime_image to an explicit digest (ghcr.io/…@sha256:…). Digest-pinned references skip the HEAD round-trip.
Shared: the same resolver backs GET /api/v1/cache/images so the admin UI and the provisioner do not double-pay for the registry check.

Background GC

ProvisioningHandler runs a sweeper every 30 minutes (and once at startup) to remove crash leaks:

Temp containers — those named crewship-provision-* and labelled crewship.temp=provision — are force-removed once older than 1 hour. Both conditions are required, and the name is the one that authorises deletion.
The label alone is not proof of provenance. Provisioning ends in a docker commit of the scratch container, and Docker copies that container’s labels into the resulting crewship-cache:* image — so a crew container started from it inherited crewship.temp=provision without asking. A label-only sweeper therefore force-removes healthy crews an hour into their lives; this happened on a dev host on 2026-07-20. Container names are never copied into images, which is why the name is the marker that holds.
Crew containers now set crewship.temp to the empty string at create, which stops the inheritance: the daemon merges an image label only for a key the create request leaves unset, so the explicit empty value wins and the container drops out of --filter label=crewship.temp=provision. Consequence for docker ps: an exact-value filter (label=crewship.temp=provision) now lists only scratch containers plus any crew container created before this release. A key-only filter (label=crewship.temp) still lists every crew, because the key is present with an empty value. Filter by name=crewship-provision- when you want only genuine scratch containers — that is what the sweeper itself decides on. Scratch containers leaked before this release carry a Docker-assigned random name and are no longer swept automatically. Remove them by hand if they bother you — docker ps -a --filter label=crewship.temp=provision, then discount anything named like a crew.
Cache images (crewship-cache:*) with no referencing crew row across any workspace are flagged. A 5-minute age floor protects images that Provision() has just committed but not yet linked to a crew, eliminating the obvious race window.
Intermediate feature images (crewship-feat:*) — the per-feature layers the BuildKit path produces — are regenerable and never referenced by a crew row, so the sweeper treats any unreferenced one beyond the age floor the same way it treats orphaned cache images.

Orphan deletion policy

Cache-image deletion is opt-in via the CREWSHIP_CACHE_GC_AUTODELETE environment variable (also described in Environment → Devcontainer cache GC):

Value	Behaviour
unset / `0` / `false` (default)	Log-only. Orphans are enumerated and logged; nothing is deleted. Operators see the list and can decide.
`1` / `true`	Auto-delete. Orphans beyond the 5-minute age floor are force-removed each pass.

The sweeper logs a single line per pass with removed, total_orphans, and skipped_too_young so dashboards can alert on cache growth regardless of mode.

Image-list cache

Docker’s ImageList is O(n) over every image on the host. The sweeper and GET /api/v1/cache/images share a 10-second image-list cache so admin UI polling does not pay that cost on every request. The cache is invalidated on any commit/delete performed by the provisioner itself, so the caller always sees its own writes.

Code of record

Concern	File
Config parser / validation	`internal/devcontainer/config.go`
Feature downloader (OCI)	`internal/devcontainer/features.go`
Feature installer (exec)	`internal/devcontainer/installer.go`
Provisioner + caching	`internal/devcontainer/provisioner.go`
BuildKit feature-image builder	`internal/devcontainer/imagebuilder.go`
Generated Dockerfile	`internal/devcontainer/dockerfile.go`
REST handlers + GC sweepers	`internal/api/crew_provisioning.go`, `internal/api/crew_provisioning_gc.go`
Shared HEAD-digest cache	`internal/dockerutil/imagedigest.go`
CLI `crew config`	`cmd/crewship/cmd_crew_config.go`
CLI `crew provision`	`cmd/crewship/cmd_crew_provision.go`
Seed demo data	`cmd/crewship/seeddata/crews.go`
Sidecar bind mount	`internal/provider/docker/docker.go:buildMounts`
Autodetect + fail-fast	`internal/config/config.go:autodetectSidecarPaths`

Get Started

Guides

Security

Configuration

Manifest Reference

Devcontainer Configuration

Devcontainer Configuration

Per-crew fields

`devcontainer_config` schema

Allowed feature registries

Canonical feature set for every Crewship crew

`mise_config` schema

Environment variables

Autodetect order

REST endpoints

REST contract

GET /api/v1/crews//provision

POST /api/v1/crews//provision

POST /api/v1/crews//rebuild

GET /api/v1/features/catalog

GET /api/v1/runtimes/catalog

CLI flags

Provisioning states

Validation rules

Cache image naming

Runtime base-image digest check

Background GC

Orphan deletion policy

Image-list cache

Code of record

​Devcontainer Configuration

​Per-crew fields

​devcontainer_config schema

​Allowed feature registries

​Canonical feature set for every Crewship crew

​mise_config schema

​Environment variables

​Autodetect order

​REST endpoints

​REST contract

​GET /api/v1/crews//provision

​POST /api/v1/crews//provision

​POST /api/v1/crews//rebuild

​GET /api/v1/features/catalog

​GET /api/v1/runtimes/catalog

​CLI flags

​Provisioning states

​Validation rules

​Cache image naming

​Runtime base-image digest check

​Background GC

​Orphan deletion policy

​Image-list cache

​Code of record

Devcontainer Configuration

Per-crew fields

`devcontainer_config` schema

Allowed feature registries

Canonical feature set for every Crewship crew

`mise_config` schema

Environment variables

Autodetect order

REST endpoints

REST contract

GET /api/v1/crews//provision

POST /api/v1/crews//provision

POST /api/v1/crews//rebuild

GET /api/v1/features/catalog

GET /api/v1/runtimes/catalog

CLI flags

Provisioning states

Validation rules

Cache image naming

Runtime base-image digest check

Background GC

Orphan deletion policy

Image-list cache

Code of record