One host per project
Give each project folder its own host, for you and for coding agents.
When you work on several projects, or run a coding agent in each, give every project folder its own host. Their containers, ports and volumes never meet, two stacks can both use port 3000, and an agent in one folder can't stop the other's database.
Set up a folder
Create a host for the project
Name it after the project, such as
shop-api. How many hosts you may have is set by your workspace's admin; see rules.Run its setup in the folder
On the Docker hosts page, press Use in a folder under the host, pick what runs Docker there (Claude Code, Codex or another agent, or just your terminal), and run the one command it gives you in the project folder. The window ticks off the last step when the host sees your first
dockercommand. The command is safe to run twice, and never overwrites a file you already have. It:- creates a Docker context named after the host;
- sets
DOCKER_CONTEXTin.claude/settings.local.json, for Claude Code; - adds
export DOCKER_CONTEXT=…to.envrc, for your terminal with direnv; - for another agent, adds a line to
AGENTS.mdtelling it to use that context; - keeps the files out of git through
.git/info/exclude, leaving your.gitignorealone.
Check it
docker context show # prints shop-api docker version # the Server section answers from the host
From then on, every docker and docker compose command run in that folder, by you or an agent, goes to its host.
Doing it by hand
For your terminal, with direnv:
export DOCKER_CONTEXT=shop-apiFor Claude Code, in the folder's .claude/settings.local.json:
{
"env": { "DOCKER_CONTEXT": "shop-api" }
} Codex and other agents don't read Claude Code's settings. Start them from a terminal in the folder, so they inherit DOCKER_CONTEXT, and add this to the folder's AGENTS.md:
Docker runs on a remote host. Use the context in $DOCKER_CONTEXT, which is set
for this folder. Never run `docker context use`, and never switch to another context.Good to know
- A folder's own
DOCKER_CONTEXTwins over the default context. Set a default once withdocker context useif you like, but don't switch it while working: it changes every folder without its own at once. DOCKER_HOSTbeatsDOCKER_CONTEXT. If your shell profile exports it, remove it there.- A git worktree is a folder of its own. Run the setup in each, pointing at a different host if both run stacks at once.
- Two folders can share a host when they never run at the same time. Give each its own
COMPOSE_PROJECT_NAMEand keep their published ports apart. - Each host stops by itself when nobody uses it, so idle projects cost nothing.