Hardening dev containers

The standard dev container example is for a cooperative development environment. Watcher and the coding agent run as the same user, and the container can read the host's Watcher sign-in. A process in the workspace can stop Watcher, edit the agent hooks, read the shared credentials, or call the local Watcher API.

Do not use that example as a security boundary against code running in the workspace. If the workspace is untrusted, design the boundary around your container platform, agent configuration, and authentication requirements.

Choose the boundary first

Decide which components are trusted before adding container controls:

• The Docker host and anyone who can change the image or Compose definition control the whole deployment.
• Repository code controls dev container lifecycle commands unless those files are protected by policy outside the repository.
• Agent hook input comes from the workspace and must be treated as untrusted.
• A developer can always start a different, unmonitored agent unless launch is controlled outside the workspace.

Container hardening can restrict an unprivileged workspace process. It cannot protect against the Docker host, image builder, or repository administrator.

Design options

The following controls can be combined into a stronger deployment. They are design guidance, not a copyable hardened template.

Concern	Possible control	Remaining limitation
Watcher credentials and state	Run Watcher in a separate sidecar and give only that sidecar its credentials and state volume.	The container host can still inspect both containers.
Hook integrity	Install root-owned managed hooks in the image and enable each agent's managed-hooks-only setting.	The deployment must pin and test agent versions that enforce those settings.
Process isolation	Use separate PID and network namespaces, drop Linux capabilities, remove passwordless sudo, and do not mount a container-runtime socket.	Both containers still depend on the host kernel and configuration.
Communication with Watcher	Expose a narrow Unix socket that accepts only known hook events instead of the full local API.	The relay becomes security-sensitive code and needs its own validation and resource limits.
Transcript access	Pass bounded snapshots for the current hook instead of mounting the repository or agent home into the Watcher sidecar.	Snapshot selection must reject symlinks, path escapes, oversized input, and unexpected file types.
Availability	Check Watcher and relay health, restart failed services, and decide which permission hooks should fail closed during an outage.	Lifecycle events can still be missing during an extended outage.
Artifact integrity	Pin Watcher and agent versions, verify downloaded checksums, and make protected image paths read-only.	Anyone allowed to rebuild or replace the image remains trusted.

Runtime reliability

The standard example checks that Watcher starts, then leaves it running in the background. A deployment that needs stronger runtime guarantees can:

• supervise the Watcher process and restart it after repeated health failures;
• check authentication separately, then warn or block according to local policy; and
• reinstall hooks after agent changes and verify that a real session reaches the Analyzer.

Failing closed improves monitoring coverage, but turns a Watcher outage into a development outage.

Authentication

Do not pass the desktop credential directory into an untrusted workspace. A sidecar can use a separate browser sign-in, or an unattended deployment can use an organization API key with only the permissions it needs. Keep either form of authentication out of the workspace container.

Reusing the desktop sign-in is appropriate for the standard example because it assumes the workspace is trusted and keeps setup small. It is not compatible with a boundary whose purpose is to prevent workspace processes from reading Watcher credentials.

Validation

Test the finished deployment against its threat model. At minimum, verify that the workspace cannot:

• read Watcher credentials or state;
• replace or disable managed hooks;
• signal the Watcher process or reach its control API;
• modify the relay or its socket directory;
• mount the Docker or containerd socket; or
• make permission-bearing hooks continue silently when Watcher is unavailable.

Also run an agent turn and confirm the session reaches the Analyzer. Isolation checks do not prove that authentication, hook discovery, and upload work together.