Container Launch

Container launch is one of server mode’s two launch vehicles (the other is Native Launch, a host subprocess on server_python): a nodeset that declares server_image is auto-hosted inside docker run instead of a native host process. The hard promise: the container serves the exact same protocol on the same kind of port, so everything downstream — proxy-node generation, env-panel bridge, multi-worker fan-out, the /mcp projection — is byte-identical to a conda-launched server, and images never contain framework code (the repo is bind-mounted read-only; the image carries only the model's dependencies). For the protocol itself and the conda path read Server Mode; for what a nodeset is read NodeSets.

How the code launches a server_image nodeset.

1. What it does

Some systems can't be expressed as a conda environment at all — a C++ SLAM stack with its own compiled world (ORB-SLAM3), or a GPL codebase that must stay out of the framework's process and env (pySLAM). Container launch lets such a system join the canvas the same way every server-mode nodeset does: the registry launches it, reads its /manifest, and generates proxy nodes. The only thing that changes is the launch vehicle — docker run instead of a conda interpreter. The container runs the stock auto_host.py from a read-only bind mount of the repo, so there is no per-nodeset bridge code, no in-image copy of the framework, and a framework upgrade never requires an image rebuild.

Before this existed, the one containerized nodeset (model_pyslam) carried its own private bridge — a hand-written _client.py/_server.py pair pretending to be a local-mode nodeset, invisible to the registry, the scheduler, and GPU admission. Container launch moves that mechanism into the framework: declare an image, get the whole server-mode feature set.

2. The smallest container nodeset

One ClassVar is the whole trigger — everything else is ordinary nodeset authoring:

class OrbSlam3NodeSet(BaseNodeSet):
    name = "model_orbslam3"
    server_image = "agentcanvas/orbslam3:latest"   # ← the whole trigger
    server_image_gpu = False                        # CPU SLAM core
    server_mounts = {"data/tum": "/opt/data/tum:ro"}
    # get_tools() returns the reset / track / get_trajectory nodes as usual

Loading it (POST /api/components/nodesets/model_orbslam3/load) auto-routes to server mode (registry.py · load_nodeset — the server_image check sits above the server_python one and wins when both are set) and ultimately runs this real command as a direct child of the backend:

docker run --rm --init --name ac_auto_model_orbslam3_9204 \
    -p 127.0.0.1:9204:9204 \
    --add-host host.docker.internal:host-gateway \
    -v /path/to/agentcanvas:/opt/agentcanvas-workspace:ro \
    -v /path/to/agentcanvas/data/tum:/opt/data/tum:ro \
    -e PYTHONPATH=/opt/agentcanvas-workspace/agentcanvas/backend:/opt/agentcanvas-workspace \
    -e AGENTCANVAS_EXECUTOR_URL=http://host.docker.internal:8000 \
    agentcanvas/orbslam3:latest \
    python3 -m app.server.auto_host \
        --module workspace.nodesets.model.model_orbslam3 \
        --class OrbSlam3NodeSet --port 9204

3. Declaration surface

Five ClassVars on BaseNodeSet (bases.py · BaseNodeSet) steer the container launch; server_env from the conda path also applies (its vars ride into the container's environment via -e):

4. Launch pipeline — what the registry assembles

registry.py · _build_container_server turns the nodeset declaration into a ContainerServer; three translations happen there, and only there:

• Path translation. The repo root is mounted at /opt/agentcanvas-workspace (container_server.py · WORKSPACE_MOUNT); every host path riding the inner command line (--file) or PYTHONPATH is rewritten under that prefix. A source file outside the repo root is a hard RuntimeError, not a silently wrong path.
• Mount resolution. server_mounts entries are expanded (expandvars + expanduser, relative → repo-root-relative) and appended after the repo mount; missing :ro host paths are skipped with a warning, missing rw host paths are created (output drops).
• Executor-URL rewrite. Loopback executor URLs (127.0.0.1/localhost) are unreachable from inside a container, so AGENTCANVAS_EXECUTOR_URL is rewritten to host.docker.internal, which ContainerServer maps to the host via --add-host host.docker.internal:host-gateway. This keeps the reverse log/error channel and cross-nodeset container access working from inside the container.

ContainerServer (container_server.py · ContainerServer) is a BaseServer subclass whose command is a foreground docker run: health polling, startup timeout, manifest fetch, and the pdeathsig chain all apply unchanged to the docker client, which proxies SIGTERM to PID 1 in the container (--init reaps). Everything after start() — proxy generation, env-panel bridge, worker fan-out bookkeeping, rollback on partial failure — is the shared server-mode path in registry.py · _load_nodeset_as_server, byte-identical for both vehicles.

5. Lifecycle, orphans, rootless

Container mode has one failure surface the conda path doesn't: the docker client can die (SIGKILL, OOM) while the container lives on — pdeathsig kills the client, not the daemon-owned container. Three mechanisms close it (container_server.py · ContainerServer):

• Deterministic names + pre-start reap. Every container is named ac_<label>_<port>; start() first runs docker rm -f on that name, so a leftover from a killed client is removed before the next launch (docker ≥ 23 exits 0 either way; the reap is logged only when something was actually removed).
• --rm + signal proxying. The attached client forwards SIGTERM; a normal stop removes the container.
• docker stop in stop(). The authoritative path goes through the daemon first, then falls back to BaseServer.stop() killing the client's process group.

The docker client always talks to the rootless daemon: DOCKER_HOST and XDG_RUNTIME_DIR are forced to the user socket (container_server.py · rootless_docker_env) regardless of what the backend inherited, because images live only in the rootless store. A missing image fails fast at start() with an actionable error (container_server.py · image_exists) instead of a docker-pull hang.

6. Image contract

An image is valid for container launch when the interpreter named by server_container_python can import the model's own dependencies plus the small serve set in agentcanvas/backend/requirements-serve.txt (fastapi, uvicorn, httpx, msgpack, numpy, pydantic, pyyaml; mcp optionally adds the /mcp projection). Framework code is never baked in — it arrives at run time via the read-only repo mount. Consequences worth stating:

• Framework upgrades reach containers with no image rebuild (same property the conda envs have).
• The image cannot be started standalone against a stale framework copy — there is none inside it.
• Model weights follow the established external-weights pattern: keep them under data/ and mount via server_mounts, so images stay code-only.

7. Where it deviates from the clean model

8. File reference