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

  1. 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.

  2. 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 docker command. 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_CONTEXT in .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.md telling it to use that context;
    • keeps the files out of git through .git/info/exclude, leaving your .gitignore alone.
  3. Check it

    in the project folder
    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:

.envrc
export DOCKER_CONTEXT=shop-api

For Claude Code, in the folder's .claude/settings.local.json:

.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:

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_CONTEXT wins over the default context. Set a default once with docker context use if you like, but don't switch it while working: it changes every folder without its own at once.
  • DOCKER_HOST beats DOCKER_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_NAME and keep their published ports apart.
  • Each host stops by itself when nobody uses it, so idle projects cost nothing.