Moving a coding agent from the host into a container can change what the same model name and localhost address point at.
They can hide a different endpoint, a different credential, and a stale container-wide setting.
Environment fixed at container creation does not follow a later configuration change.
The agent inside also runs in a different process environment from the one on the host.
Our launcher script picks one of three paths for each session.
The host path runs the agent directly on the Mac.
A project container is built from the repository's own .devcontainer configuration.
A generic container comes from a reusable image we keep for repositories that have no .devcontainer.
We ran Claude Code on the host and in a generic container on OrbStack for macOS, and read how three other agents (Codex, OpenCode, and pi, a coding agent from the pi-mono project) document their credentials.
Before trusting a result, we answer six questions:
- Where did the agent run?
- Was a container created or reused?
- What did
localhostmean for that caller? - Which credential did it use?
- Did a small tool call complete?
- What state remained afterward?
Host execution has no container-creation phase
We prepare an existing container differently from one we are creating, and a host launch needs neither kind of preparation.
On the host, the launcher reads the agent's own configuration and credentials, then starts the agent process in the host's process environment. A host launch skips image build, container creation, and container start. A host agent can still run a tool somewhere else, for example through a remote MCP server, so when the agent invokes a tool, we find out where that tool actually runs.
The two container paths start from different definitions, and both then check whether a matching container already exists.
A project container starts from the repository's devcontainer.json.
A generic container starts from the reusable configuration our launcher keeps.
The Dev Container specification lets the tool that runs it (VS Code or the devcontainer CLI) decide how to handle a missing project configuration and whether to offer a generic fallback.
On either container path, we check whether a suitable container already exists, meaning one that matches the current definition: the same image, mounts, and environment. We reuse a suitable container that is already running and start or resume one that is stopped. Creation-time settings apply only at creation. Recreating a container that no longer matches is a separate decision, because anything written inside the old container outside a mount is lost.
For each path and container state, we check whether a container gets created and what we do before the agent process launches.
| Selected path and state | Container creation | Work before the agent process launches |
|---|---|---|
| Host | Not applicable | Resolve host configuration, credentials, and tool environment |
| Project or generic container, absent | Required | Read its devcontainer.json, prepare the image, create, start, and wait for the lifecycle commands (such as postCreateCommand) that waitFor requires |
| Project or generic container, suitable and stopped | No new creation | Start it and wait for the lifecycle commands that run on start |
| Project or generic container, suitable and running | No new creation | Confirm the lifecycle commands have finished and apply process settings for the new agent process |
| Existing container does not meet the selected definition | Separate decision | Decide whether to rebuild; until then the container keeps its old mounts and environment |
The specification distinguishes creation, stop, and resume events.
Its post-creation lifecycle lets waitFor decide which commands may keep running in the background, so some dependencies the agent needs may still be initializing after container creation is reported.
We check readiness for the specific dependencies the agent will call.

Figure text
The host path skips container creation. Project and generic container paths distinguish absent, suitable stopped, suitable running, and unsuitable existing containers before readiness and agent launch. Creation binds mounts and container environment; process settings apply at agent launch.
- Three launch paths, one creation moment
- Host path (outside the frame)
- Container path (into the frame)
- Set once at creation, then stays
- Creation settings stay with the container. A mismatch is our decision, not an automatic rebuild. This shows the launch procedure, not a run result.
- 1 Host, no container steps
- 2 Container, look for a match first
- 3 None yet, create it
- 4 Matches, stopped, start it, wait for setup
- 5 Matches, running, confirm it is ready
- 6 Does not match, stop
- 7 Set once, at creation
- 8 Ready, then process settings
- 9 Start the agent process
- Creation settings: Files shared in; Container-wide settings
- Which path?
- Agent on the host
- Matching container?
- Stop and decide
- Readiness check
- Process settings
- Agent in the container
- Process settings applied
- Per-process settings
- A container that no longer matches keeps its old settings until we decide whether to rebuild it.
Sources: [1] Dev Container metadata reference; [2] Development Container Specification; [3] docker container run | Docker Docs.
Creation settings and process settings have different lifetimes
Some settings live as long as the container and others only as long as one process, which is why we separate creation from later starts.
Mounts and container-wide environment are set at container creation.
In devcontainer.json, containerEnv is set on the container itself, and the metadata reference calls it static for the life of the container, so changing it needs a rebuild.
remoteEnv applies to the processes that VS Code or the devcontainer CLI starts in the container, and its value can change without a rebuild.
The Dev Container environment specification applies remoteEnv after the container's entrypoint has run.
Image and Dockerfile setups can use containerEnv, and Compose setups use the Compose service's environment instead.
So an existing container created with one containerEnv value keeps it after we change devcontainer.json.
A newly launched tool process can pick up an updated remoteEnv without a rebuild, and an agent that is already running may have its own reload mechanism.
We checked the plain Docker analogue of this split, which shows the Docker behavior but is not a test of a devcontainer tool:
- We created a plain container with
docker create -e, setting endpoint A in its container-wide environment. - We changed the desired endpoint to B.
- We stopped and started the container.
docker inspect showed the same .Created timestamp, so nothing was recreated, and a new process still saw A through printenv.
Only a process-level override with docker exec -e made printenv show B, and the next process saw A again.
Credentials have their own lifetime, set by each agent. The Claude Code settings reference lists which settings reload mid-session. pi's model documentation sets the precedence between stored and runtime credential sources. Even with configuration mounted, a container agent may still choose a different credential from the one that works on the host.
A read-only mount of a credential file stops the agent from changing it, and processes in the container can still read its contents. When comparing runs, we name the credential mechanism without copying credential contents into a log or command argument.
| Surface | Documented owner | Timing / precedence |
|---|---|---|
| Container environment | Dev Container configuration | Set at container creation. Image/Dockerfile mode can use containerEnv, and Compose uses its service environment. Development Container Specification |
| Remote environment | Remote tool / process environment | Applies to the remote process. The already-created container environment keeps its settings. Development Container Specification |
| Codex provider auth | Codex authentication surface | Codex's sign-in methods are listed on its authentication page. Authentication | ChatGPT Learn |
| Pi credentials | Pi provider credential resolution | Pi sets precedence among runtime, stored, model-file and environment credentials, and a stored credential belongs to its provider. pi ai pi models |
| Claude Code settings | Claude Code settings scopes | Settings-file scopes and per-setting environment precedence differ; most settings reload with documented exceptions. Settings files and precedence - Claude Code Docs |
| OpenCode credential store | OpenCode provider auth | Stored credentials are separate from provider configuration. Providers | OpenCode |
Sources: Settings files and precedence - Claude Code Docs Authentication | ChatGPT Learn pi ai pi models Providers | OpenCode Development Container Specification.
The caller determines what localhost means
After the agent process starts, we check which address it reaches when it uses localhost.
Loopback belongs to the caller's network namespace.
On an ordinary isolated container network, localhost inside the container means the container itself, so reaching a service on the Mac's loopback interface needs a separate route.
On macOS, Docker Desktop's networking architecture puts a Linux VM and host-side forwarding components between container and host traffic.
Docker's container-run reference says Docker Desktop resolves host.docker.internal automatically.
It also documents the host-gateway value for an explicit --add-host mapping in Docker Engine.
For Engine, that mapping points at the daemon's host, which is a different machine when DOCKER_HOST points the CLI at a remote daemon.
An alias maps a name to an address. We still check whether a service listens at that address and accepts the request.
Publishing or forwarding a port configures access in the other direction.
The Dev Container metadata reference separates forwardPorts from published application ports and notes that publishing can require a broader application bind address.
On the host side, Docker's port publishing with -p 8080:80 maps every host address to container port 80, which Docker calls insecure by default.
Putting the host's loopback address in front of the host port (-p HOST_IP:8080:80) restricts the published port to the host itself.

Figure text
The host and container lanes have their own localhost because loopback belongs to the caller. The dashed line marks the container-to-host service route; check it on your own host.
- The local address depends on who asks
- Host caller (starts outside)
- Container caller (starts inside)
- Dashed lane: route not tested here
- An alias only maps a name to an address. Check on your own host that a service listens there and accepts the request.
- 1 Host caller, its own local address
- 2 Container caller, its own local address
- 3 In through a published port; Forwarded into the Linux VM
- 4 Out to the host, not tested here; Check it on your own host
- Incoming traffic
- Service on the host
- Agent on the host
- Published host port
- Name for the host
- Docker Desktop forwarding
- Agent in the container
- Service in the container
- Host caller
- Container caller
- Going the other way, from the container to the host, needs a name that points at the host. This figure did not test that route.
Sources: [1] Dev Container metadata reference; [2] Networking on Docker Desktop | Docker Docs; [3] docker container run | Docker Docs.
How we traced a fixture read on the host and in a container
With those checks in mind, we ran one harmless request through the paths and recorded what each run did.
We ran a local test on OrbStack for macOS.
Claude Code pointed at a LiteLLM gateway on the Mac's loopback interface through ANTHROPIC_BASE_URL, with a placeholder token in ANTHROPIC_AUTH_TOKEN and a custom model alias that the gateway serves.
The fixture was a throwaway file holding a one-off token string, and the agent had to read it with its Read tool and reply with only that string.
The runs came in this order:
- One host launch and one generic container launch.
- Then the plain container we created and restarted with a changed desired endpoint, described above.
On the host, Claude Code 2.1.319 returned the fixture token in three turns and two Read calls.
Its first Read guessed a path outside the fixture directory and errored, and the second found the fixture.
The host run also fired the SessionStart hooks in our user-level Claude Code settings under ~/.claude, so it inherited our personal configuration, and the container run fired none.
The generic run launched a disposable container with the fixture mounted read-only and ran the agent as a non-root user.
Its endpoint was host.docker.internal at the gateway port, set for the agent process with docker exec -e.
Its image carried Claude Code 2.1.316, so we compared different host and container client versions.
Inside, the agent returned its token in two turns with one successful Read.
Claude Code warned that the model name was unrecognized, because the gateway alias is not in its list of known models; the warning appeared in the host run too and did not stop either request.
The full walkthrough for Ubuntu and Alpine is in Run Claude Code in a container, step by step. To see the generic path without a project definition, start an Ubuntu container, add a user, and install Claude Code inside it:
docker run --rm -it ubuntu:24.04 bash
apt-get update && apt-get install -y curl ca-certificates
useradd -m dev && su - dev
curl -fsSL https://claude.ai/install.sh | bash
~/.local/bin/claude --version
We ran the equivalent of these steps with a downloaded copy of the installer: Claude Code 2.1.319 installed for the dev user and printed its version.
The base image has no curl, so we install it first.
The installer puts the claude command in ~/.local/bin and warns that the directory is not on the PATH, which is why the last line calls it by its full path.
Three things change against the same agent on the host:
- the agent sees only the container's files, so a project has to be mounted (for example with
-v "$PWD":/work) before the agent can read it localhostnow means the container itself, as the localhost section above explains- a login completed inside the container lives in that container, so
--rmdiscards it when the container exits
What the host and container runs showed
The table below answers each of our questions for the runs we made.
| Question | What we saw |
|---|---|
| Where did the agent run? | Claude Code 2.1.319 ran on the host; 2.1.316 ran as a non-root container process. |
| Was a container created? | The generic run used docker run --rm; a separate container was created, stopped, and restarted for the endpoint check. |
| What did the endpoint address mean? | In OrbStack on macOS, container localhost at the host gateway port refused the connection, while host.docker.internal resolved and the gateway readiness check returned HTTP 200 without --add-host. |
| Which credential mechanism applied? | Our run records showed a placeholder gateway token and no API key source. |
| Did the tool action happen? | The host returned its token after two Read calls; the container returned its token after one Read call. |
| What state remained? | The --rm container and the created container were gone afterward; docker ps -a --filter label= with our test label returned no containers. |

- On the host: the agent reaches the gateway on the Mac's loopback interface.
- In the container:
localhostmeans the container itself, and the connection is refused. - Across the boundary:
host.docker.internalresolves to the host, and the gateway answers.
The generic container also ran with 1 CPU, 1 GiB of memory, and 256 PIDs; cgroup v2 reported cpu.max 100000 100000, memory.max 1073741824, and pids.max 256, and docker inspect agreed.
Setting resource limits for coding-agent containers explains how to set and read those limits, including runArgs and Compose service settings.
Before cleaning up, we list what the session used. A bind mount points at host files that outlive the container, files written inside the container go with it, and a reused container may still hold state from earlier sessions. The specification leaves stop timing to the tool that runs it, so the container may still be running after the agent closes. A local MCP server runs with the privileges of the client that starts it, so these mounts also decide what such a server can reach, and MCP servers your coding agent should not trust covers what one can do. The harness checks that decide which tool calls run at all are the subject of Tool-call trust in coding agents.

Figure text
Follow the decision tree from discovery-only results through endpoint, transport, auth, agent request, tool action, and cleanup checks. Test each layer and finish with a real agent request and tool action.
- Test the path, step by step
- Stop, write it down (record exit)
- Stop at the first failed step and write down what happened. This is a checklist to run on your host, not a result.
- 1 Leave the list, start testing
- 2 Go on only if each step passes
- Model list
- Caller and target
- 3 Reachable?
- 4 Credential accepted?
- 5 Agent request succeeds?
- 6 Small tool action succeeds?
- 7 What was left behind
- Written record
- Test
- Picker or catalog
- How the connection failed; Credential source, not the value; Request result; Tool result
- Last, look at what the session created and record what you find.
Sources: [1] pi models; [2] Dev Container metadata reference; [3] Development Container Specification; [4] Networking on Docker Desktop | Docker Docs.
What an attacker targets here
Whatever the agent's process can reach, on the host or through a container's mounts, a tool call or a local server can reach too.
- A local MCP server runs with the client's privileges, and a poisoned description can ask the model to read an SSH key. We start unfamiliar servers in a sandbox with minimal default privileges, as MCP servers your coding agent should not trust recommends.
- A path check in the harness can be raced by a process that swaps a directory for a symlink between the check and the open. A container that mounts only the workspace enforces the boundary in the operating system, as Tool-call trust in coding agents explains.
- A local Streamable HTTP server that skips the
Origincheck can be reached by a remote website through DNS rebinding. It must validateOriginand should bind only to localhost, as the MCP checklist says.