Troubleshooting

SSH agent issues

Symptom	Fix
ssh-add -l says "Could not open connection to agent"	Check SSH_AUTH_SOCK is set in devcontainer.json remoteEnv. If SSH_AUTH_SOCK is unset, entrypoint.sh logs ERROR: SSH_AUTH_SOCK is not set at startup (non-fatal — the container still runs)
ssh-add -l says "Error connecting to agent"	Run colima ssh -- ls -la /run/host-services/ssh-auth.sock to check the VM socket
Socket missing in VM	Restart Colima: colima stop && colima start --ssh-agent
Socket exists in VM but "Permission denied"	Fix socket perms: colima ssh -- chmod 777 /run/host-services/ssh-auth.sock
ssh-add -l says "The agent has no identities"	Ensure the host SSH_AUTH_SOCK points to the 1Password socket (see Getting Started step 3), verify 1Password → Settings → Developer → "Use the SSH agent" is enabled, then restart Colima with --ssh-agent
Works in VM but not in container	Verify the bind mount in devcontainer.json matches the VM socket path

Firewall issues

Symptom	Fix
curl: (7) Failed to connect to an allowed host	Re-run sudo /usr/local/bin/firewall.sh apply (DNS may have rotated the resolved IPs out of the snapshot)
Startup fails: firewall.sh exits 1 with EGRESS_ALLOWLIST is set but file not found	EGRESS_ALLOWLIST (set in devcontainer.json remoteEnv) points at a missing file. Create .devcontainer/egress-allowlist.txt with your project's required hostnames (copy examples/egress-allowlist.txt)
All outbound blocked, no firewall rules applied	iptables is unavailable, so entrypoint.sh logs WARN: NET_ADMIN capability not available. Skipping egress firewall. Ensure the container runs with the privileges iptables needs (runArgs: ["--privileged"] in devcontainer.json)
WARN: EGRESS_ALLOWLIST not set at startup	EGRESS_ALLOWLIST is unset, so only loopback and DNS are allowed. Set it in devcontainer.json remoteEnv to your project's allowlist file

See Manage Egress for the canonical two-layer procedure to add a new HTTPS host.

Observability issues

Symptom	Fix
UNABLE_TO_VERIFY_LEAF_SIGNATURE	mitmproxy CA cert not yet in the system bundle. Run sudo /usr/local/bin/install-mitm-ca.sh ~/.mitmproxy/mitmproxy-ca-cert.pem, then source /etc/profile.d/mitm-certs.sh (or open a new terminal) and restart Claude Code
ERR_BAD_RESPONSE for a domain	The domain is blocked. Allow it at both layers, iptables first: (1) add it to .devcontainer/egress-allowlist.txt, then sudo /usr/local/bin/firewall.sh apply; (2) add the same domain to .devcontainer/proxy.yaml, then PROXY_YAML=.devcontainer/proxy.yaml generate-proxy-filter. Adding it to proxy.yaml alone leaves traffic REJECTed at the iptables layer. See Manage Egress
HTTP_PROXY empty in terminal	devcontainer.json remoteEnv is the source — rebuild the container to pick up changes, or source /etc/profile.d/mitm-certs.sh manually
Monitor dashboard not reachable	The dashboard is published on a host port chosen by env.sh (scanned from 9090–9190) and mapped to the container's fixed 9090. Make sure you ran source .devcontainer/env.sh before opening VS Code so MY_PROJECT_MONITOR_PORT is set — if it is empty the appPort mapping is invalid. The actual host URL is shown in the VS Code Ports panel. Inside the container the dashboard is always at http://localhost:9090
Proxy feed shows nothing	Run pgrep privoxy to confirm it's running; check /tmp/privoxy.log for startup errors
Privoxy not running	start_proxy skips privoxy and logs WARN: No proxy.yaml found when .devcontainer/proxy.yaml is missing. Copy examples/proxy.yaml to .devcontainer/proxy.yaml and restart
mitmdump not running	Check /tmp/mitm.log. On first run, mitmproxy generates its CA key during postCreateCommand (may take 60–120 s in low-entropy environments such as a fresh Colima VM)

Container runtime issues

Symptom	Fix
WARN: Podman initialization failed at startup	Rootless Podman could not initialize its mount namespace. This requires runArgs: ["--privileged"] in devcontainer.json; confirm it is present and rebuild the container
WARN: mise install failed / tunnel error: Connection refused during setup	Expected when a project .mise.toml pins a runtime version the image never baked: the egress policy blocks runtime downloads and the proxy is not up during setup. Runtime version overrides are unsupported — change the version in the image's .mise.toml and rebuild. The warning is non-fatal; setup still completes
python/ruby/go/ansible/chef-cli "command not found" after first open	The baked runtimes at ~/.local/share/mise are being shadowed. Almost always a stale project still mounting a ${project}-mise-data volume over that path — remove that mount from devcontainer.json (the current templates don't mount it; see ADR 0014) and rebuild

Build issues

Symptom	Fix
op --version fails during build	gcompat may not work for this op version; see ADR 0001
Python/Ruby compilation fails	Check build-base and dev packages are installed; see Dockerfile Layer A
mise install hangs during make build	Network access is needed at build time to compile/download runtimes; check Docker network settings. (At container runtime the baked runtimes are used directly from the image — no build-time network is involved there.)
mise "config not trusted" errors	Should not happen — MISE_TRUSTED_CONFIG_PATHS is set in the image. If using a custom path, add it to the env var or run mise trust <path>
Python/Ruby not on PATH in /workspaces	MISE_GLOBAL_CONFIG_FILE must point to the home .mise.toml; this is set in the Dockerfile