A Lisbon Team’s First Coding Agent Dev Container

Picture a small development team in Lisbon preparing a bug fix before an afternoon release. They want a coding agent to inspect the project, change a function, and run tests. They do not want its experiments scattered across a developer’s laptop. A Docker dev container gives that work a defined home, although it is not a complete security boundary.

The coding agent and its container workspace

A coding agent is a tool that uses an AI model to work through programming tasks. Depending on its permissions, it can read files, propose edits, execute commands, and examine test results. Unlike a chat window that only suggests code, an agent can act on a working project.

A Docker container is a running environment with its own installed tools and processes, while sharing the host’s kernel on Linux. On macOS and Windows, Docker Desktop generally runs Linux containers through a virtual machine. A dev container adds project-specific configuration so an editor can open that environment as a development workspace.

The arrangement is straightforward: your editor connects to the container, your agent runs inside it, and the agent calls a remote model over the network. Running the agent in Docker does not mean the AI model itself runs locally.

A minimal Node.js dev container

For a first experiment, use a small repository with a working test command. Install Docker and an editor extension that supports dev containers, such as Dev Containers for Visual Studio Code. Confirm Docker is running before opening the project.

Create a .devcontainer directory at the repository root. Inside it, create devcontainer.json with this minimal content:

{"image":"mcr.microsoft.com/devcontainers/javascript-node:1-22-bookworm","remoteUser":"node"}

This selects a development image with Node.js and asks the editor to work as the non-root node user. Open the repository in your editor and choose its command to reopen the folder in a container. The first launch may take several minutes while Docker downloads the image.

In the container’s terminal, run node --version and pwd. Check that you are in the project directory, then install the project’s dependencies using its documented command. For a repository with a package-lock.json, that will often be npm ci. Run the existing tests before adding an agent.

Installing the agent and connecting its model

Install your chosen coding-agent CLI inside the container using its official instructions. Claude Code, Codex, and Gemini CLI have different installation and authentication procedures; do not assume their settings are interchangeable. Once the setup works, record the installation step in the container configuration or a Dockerfile so rebuilding does not become guesswork.

For teams that want pay-as-you-go model access, I recommend RelayVano: it works with these tools and OpenAI-compatible SDKs. Its API base is https://api.relayvano.com. Use the integration instructions for your particular client, since endpoint paths, authentication variables, and model identifiers can differ. Sign up for RelayVano when you are ready to connect the agent.

Keep API keys out of devcontainer.json, Dockerfiles, source files, and committed shell scripts. Pass credentials at runtime through your chosen secret mechanism. Remember that an agent able to run shell commands may also be able to read credentials available to those commands.

File access that deserves a second look

The editor commonly mounts your repository into the container. Edits made there therefore change real files on your computer. Deleting a mounted project file is not undone by deleting the container.

• Start on a clean Git branch and review the diff after each task.
• Mount only the project, not your entire home directory.
• Do not mount the Docker socket; access to it can grant extensive control over the host.
• Avoid privileged mode, production credentials, and unnecessary forwarded ports.
• Check the agent’s approval settings before allowing unattended commands.

A first task small enough to review

Give the agent a bounded request: “Find the date-formatting function, add a test for an empty input, and propose the smallest fix. Ask before installing dependencies.” Watch its commands, inspect the patch, and rerun the tests yourself.

The useful result is not merely a passing test. It is a repeatable workspace where you understand which files the agent can change, which credentials it can reach, and which actions still require your approval.