​

Devcontainers & Runtime Images

​

What you get

​

Mental model

+----------------------------------------------------------------+
|  Host (your Mac / VM / server)                                 |
|                                                                |
|  crewshipd    <---- HTTP/WS ----   crewship CLI & UI           |
|    |                                                           |
|    | provisioner.Provision()                                   |
|    v                                                           |
|  +----------------------------------+                          |
|  | 1. Pull base image               |  debian:bookworm-slim    |
|  | 2. Create temp container         |                          |
|  | 3. Install devcontainer features |  common-utils, claude... |
|  | 4. Install mise tools            |  node@22, python@3.12    |
|  | 5. Run postCreateCommand         |                          |
|  | 6. docker commit -> cache image  |  crewship-cache:a1b2c3…  |
|  +----------------------------------+                          |
|                                                                |
|  Per-crew runtime (EnsureCrewRuntime):                         |
|  +----------------------------------+                          |
|  | image = CachedImage || RuntimeImg|                          |
|  | Bind mounts (read-only):         |                          |
|  |   crewship-sidecar -> /usr/local/bin/crewship-sidecar       |
|  |   entrypoint.sh    -> /usr/local/bin/entrypoint.sh          |
|  | Bind mounts (rw):                |                          |
|  |   /workspace /output /crew /secrets                         |
|  | Volumes: /home/agent, /opt/crew-tools                       |
|  +----------------------------------+                          |
+----------------------------------------------------------------+

​

Phase 1: Dockerfile + BuildKit provisioning

• Per-feature layer caching — adding one feature rebuilds only that layer; common-utils and the previously-installed features hit the cache.
• Package-manager cache mounts — apt / npm / pip caches persist across builds, so re-provisions don’t re-download the world.
• Deterministic ordering — features install in dependency order (topological sort with common-utils first).

​

Prerequisites

make build:sidecar
# Produces:
#   ./crewship-sidecar        (the Go binary)
#   ./entrypoint.sh           (init script, copied from scripts/entrypoint.sh)

sidecar binary not found (tried [/opt/crewship/crewship-sidecar /usr/local/bin/crewship-sidecar]);
run 'make build:sidecar' or set CREWSHIP_SIDECAR_PATH
(or CREWSHIP_SKIP_SIDECAR=1 to bypass in tests)

docker pull mcr.microsoft.com/devcontainers/base:bookworm

​

Configuration shape

​

Supported devcontainer.json fields

{
  "image": "mcr.microsoft.com/devcontainers/base:bookworm",
  "features": {
    "ghcr.io/devcontainers/features/common-utils:2": {
      "username": "agent",
      "userUid": "1001",
      "userGid": "1001",
      "installZsh": false
    },
    "ghcr.io/devcontainers-extra/features/claude-code:2": {},
    "ghcr.io/devcontainers/features/github-cli:1": {}
  },
  "postCreateCommand": "echo ready",
  "containerEnv": {
    "TZ": "UTC"
  },
  "remoteUser": "agent"
}

​

mise config

{
  "tools": {
    "node": "22",
    "python": "3.12",
    "terraform": "1.9"
  }
}

​

Managing a crew’s runtime config

# Show current config
crewship crew config engineering --show

# Set devcontainer.json from file
crewship crew config engineering --devcontainer ./devcontainer.json

# Set mise.json from file
crewship crew config engineering --mise ./mise.json

# Change the base image
crewship crew config engineering --runtime-image debian:bookworm-slim

# Export full config (prints JSON)
crewship crew config engineering --export

# Clear all runtime config (back to default base, no features/mise)
crewship crew config engineering --clear

PATCH /api/v1/crews/{crewId}
Content-Type: application/json

{
  "runtime_image": "debian:bookworm-slim",
  "devcontainer_config": "{\"image\":\"debian:bookworm-slim\",...}",
  "mise_config": "{\"tools\":{\"node\":\"22\"}}"
}

​

Triggering provisioning

0. Proactive auto-provision on config save — when a crew is created (POST /api/v1/crews, crewship apply, crewship crew create) or its devcontainer / mise / runtime-image config changes (PATCH /api/v1/crews/{crewId}), the handler immediately kicks off the build in the background (CrewHandler.maybeAutoProvision). This is the primary path: by the time anyone dispatches an issue the image is usually already cached, so operators never touch a “Build now” button. Editing the config invalidates the old cached image, so the rebuild keeps the crew current automatically.
1. Explicit CLI/API trigger — crewship crew provision <slug> or POST /api/v1/crews/{crewId}/provision.
2. Crew rebuild — crewship crew rebuild <slug> clears the cached image marker and re-runs provision.
3. Auto-provision on first chat (PR #230) — when an operator opens a chat with an agent in a crew that has a config but no cached image, the chat handler calls ProvisioningHandler.EnqueueForCrew directly. The chat surface renders an inline CrewProvisioningCard with the live progress checklist; once provisioning succeeds, the agent’s first message starts on the freshly cached image.
4. Auto-provision on dispatch — when an issue, mission, or routine is dispatched to an agent in a crew that needs provisioning but has no usable cached image (never built, or the cache tag was pruned from the daemon), the dispatch path (AssignmentHandler.runAssignment → ProvisioningHandler.EnsureProvisioned) blocks until the image is built, then starts the agent on it. The same provision.* workspace events fire, so the top-right toolbar provisioning popover lights up (“preparing container”) with no extra wiring. If the build fails or times out, the run finishes with a clear “preparing the crew container failed: …” message instead of the cryptic exit 127 you’d get from launching the agent on a bare base image with no claude CLI. This guarantee means a crew is runnable the moment it’s created — operators don’t have to remember to crewship crew provision first.

crewship crew provision engineering
# ✓ Provisioning started for crew "engineering".

crewship crew provision status engineering
# Status        running        # pending | running | success | failed | idle
# Has Config    yes
# Cached Image  crewship-cache:a1b2c3d4e5f6
# Config Hash   a1b2c3d4e5f6…

crewship crew rebuild engineering

​

What Provision does, step by step

hash := configHash(baseImage, cfg, miseConfig)
tag  := "crewship-cache:" + hash[:12]
if p.IsCached(ctx, hash) {
    return &ProvisionResult{CachedImage: tag}, nil
}

_, err := p.docker.ContainerCommit(ctx, containerID, container.CommitOptions{
    Reference: "crewship-cache:" + hash[:12],
})

​

Running agents on the cached image

1. Resolve which image to boot:
   • If team.CachedImage != "" → use the cached image.
   • Else → use team.RuntimeImage or config default (debian:bookworm-slim).
2. Ensure Docker network crewship-agents exists (Internal: false — containers need outbound HTTPS for LLM providers).
3. ContainerCreate with:
   • Entrypoint forced to /usr/local/bin/entrypoint.sh (bind-mounted).
   • HostConfig:
     • CapDrop: ALL, CapAdd: NET_RAW, no-new-privileges, ReadonlyRootfs: true.
     • Memory / CPU / PidsLimit: 200.
     • ExtraHosts: ["host.docker.internal:host-gateway"] — lets the sidecar reach crewshipd on Linux too.
     • Mounts: /workspace, /output, /crew, /secrets (rw binds), /home/agent + /opt/crew-tools (named volumes), plus the two read-only bind mounts for the sidecar binary + entrypoint.
4. ContainerStart.
5. Sanity-check the sidecar bind mount for BYOI images:
   if team.Image != "" && team.CachedImage == "" {
       // exec `ls /usr/local/bin/crewship-sidecar`; exit != 0 -> fail loudly
   }
   
   Catches Alpine/musl base images that silently can’t run the glibc-linked sidecar.
6. From then on, agent execution uses docker exec (never docker run).

​

Seed data: end-to-end demo

crewship seed                     # populate crews + credentials + agents
crewship seed --smoke-test        # also run `crewship run <slug> "hello"` on every agent
crewship seed --smoke-test --smoke-timeout 90   # per-agent timeout in seconds

​

Container actuals

• “What did this agent install last week?” — query entry_type=container.snapshot on the crew, sort by ts.
• “What’s drift between today’s container and the cached image?” — compare the latest snapshot against the manifest baked at provision time.

​

Variable expansion in mounts and env

• ${devcontainerId} — resolves to a stable, Docker-volume-safe identifier derived from the crew ID (SHA-256 of the crew ID, first 16 hex chars). Useful for naming per-crew persistent volumes.
• ${VAR} / ${containerEnv:VAR} — resolved against the base image’s environment (everything in the image’s ENV directives), not the host’s. So referencing ${HOME} resolves to whatever the image set it to (e.g. /home/agent), not the operator’s home directory. Only the curly-brace form is expanded — bare $VAR is left untouched.

​

Runtime bind-mount semantics

• To roll out a new sidecar or entrypoint across existing crews, rebuild the sidecar (make build:sidecar) and then remove each crew’s container: docker rm -f crewship-team-<slug>. The container is recreated transparently on the next agent message, picking up the updated bind mount.
• postStartCommand runs on every start, so it is the right hook for operations that must reflect host state at the moment of launch (e.g. refreshing a secret via vault read). Do not try to bake those into postCreateCommand — they’d freeze at provisioning time.
• Cached images (crewship-cache:{hash}) live on the Docker host indefinitely. Run crewship crew cache prune --older-than 30d as part of your maintenance rotation; cached images referenced by live crews are protected automatically.

​

Troubleshooting

crewship crew config my-crew --runtime-image debian:bookworm-slim
crewship crew rebuild my-crew

crewship crew rebuild my-crew

​

Migrating from the legacy agent-runtime image

make build:sidecar

crewship crew config <slug> --runtime-image debian:bookworm-slim
crewship crew config <slug> --devcontainer ./devcontainer.json   # with common-utils + claude-code
crewship crew rebuild <slug>

​

Reference

• Configuration → Devcontainers — config fields + environment variables reference.
• Configuration → Environment Variables — CREWSHIP_SIDECAR_PATH, CREWSHIP_ENTRYPOINT_PATH, CREWSHIP_SKIP_SIDECAR.
• Security → Container Isolation — UID boundaries, capability drops, network policy.
• Code of record: internal/devcontainer/, internal/provider/docker/docker.go, cmd/crewship/seeddata/crews.go, cmd/crewship/cmd_crew_config.go, cmd/crewship/cmd_crew_provision.go.