container-orchestration-service: Instructions file for Claude Code

container-orchestration-service (cos) — developer guide

A standalone, harness-agnostic Docker control plane with an MCP server front end. Built against agent-runtime/v2/_design/0024-container-orchestration-and-job-dispatch.md. NOT part of the arc repo — arc consumes it as an external MCP server.

Code map

src/cos/
  core/
    spec.py      EnvSpec (image | build | base+provision), WorkloadSpec, Mount,
                 Limits — the data model + validation + from_dict (the wire contract)
    labels.py    cos.* label constants — the ONLY state (docker ps is the DB)
    backend.py   DockerBackend over docker-py: resolve_image, run_job, ensure_env,
                 exec, logs, stop, rm, list, reap
    errors.py    CosError hierarchy
  mcp_server/
    server.py    FastMCP server: container_run/ensure/exec/logs/stop/rm/list/reap
  cli/
    main.py      `cos ping|run|ps|logs|exec|stop|rm|reap|network|image|gc|serve`
tests/
  test_spec.py            unit (no docker)
  test_backend_live.py    live vs the daemon (skips if unreachable)
  test_mcp_server_live.py end-to-end: `cos serve` driven by a real MCP client

The model

• EnvSpec — how to get the image: image (pull), build (a context), or base + provision (base + RUN steps → synthesized Dockerfile, cached by hash). Exactly one is set.
• WorkloadSpec — env + command + stdin + mounts + env_vars + limits + network (default none) + lifecycle (ephemeral | persistent).
• run_job → one-shot, returns {exit_code, stdout, stderr}, auto-removes.
• ensure_env → persistent find-or-create by cos.name label (idempotent).
• ensure_network / remove_network / list_networks — user-defined bridge networks (labeled cos.managed=true) for inter-container DNS. run_job / ensure_env auto-create the network when spec.network isn't none/bridge.
• build_image / remove_image / list_images — build-once-run-many. Named, cos.managed-labeled images (docker-py build(labels=...)); reference by tag from many containers. Kills the "docker build in bash" escape.
• prune_containers / prune_networks / prune_images / gc — GC. gc = stopped containers + empty networks + unused images, in that order (containers free the refs first). Never removes running containers. Internal builds (cos-gen:*, cos-build:*) are now labeled managed so they're reclaimable.