Troubleshooting the Docker workspace

Container setups fail in a small number of recognizable ways. The useful first move is almost always identifying which layer answered you, because the same blank page can come from the dev server, the relay, or the host port mapping.

Symptom map

First checks

docker compose ps
docker compose logs --tail 100

Ports are worth knowing by heart, because “nothing is listening” and “the wrong thing is listening” look identical from a browser:

If a surface is unreachable from another device on your network, that is the default working as intended: both published ports bind to 127.0.0.1 until you change HOST_BIND_ADDRESS deliberately.

The agent is offline after recreating the container

A recreated container is a new machine identity unless its state volume came with it. Check the console’s machine list for a stale duplicate rather than assuming the connection failed — the fix is usually removing the old entry, not restarting anything.

The agent cannot see the project

Two different causes look the same. Either the working directory does not point where you think (CMDOP_AGENT_CWD), or the bind mount is not carrying the files you expect. Confirm the second before adjusting the first:

docker compose exec demo ls -la /workspace/demo

On Linux, a bind mount that is present but unwritable is a user-id mismatch: set HOST_UID and HOST_GID to the output of id -u and id -g, then rebuild.

A coding agent asks you to sign in again

The login lives in the ./agents directory on the host, mounted into the container. Being asked to sign in again means that directory did not arrive — usually because the container was started from a different working directory, or because the host directory is not writable by the container’s user.

The same user-id fix applies. A rebuild alone will not cause this: the whole point of keeping logins on the host is that rebuilds do not touch them.

Codex fails every command with a sandbox error

Codex sandboxes each command it runs, and containers frequently cannot create the namespace that sandbox needs. CMDOP_CODEX_SANDBOX=auto detects this at startup and falls back, so seeing this error usually means the sandbox was pinned on explicitly.

Changes land but no commit appears

The demo project is its own isolated Git repository, and committing is instructed behavior rather than something the agent does implicitly. If a verification step fails, the agent is expected to leave the change uncommitted and say so — an absent commit is often a report you have not read yet, not a silent failure.

Two copies of a UI library

A page that dies on a hook call with a null error is almost always two copies of the same library resolved at once, typically after dependencies were installed both in the image and into the volume that shadows it. Rebuild without cache and let one copy win.

Collecting a support bundle

These are safe to share:

docker compose ps
docker compose logs --tail 200
docker compose exec demo cmdop --version
docker compose exec demo sh -lc 'claude --version; codex --version'

Related

• Docker overview
• Configuration and persistence
• Coding agents
• Relay operation issues