AlexBa16
163 lines
6.1 KiB
Markdown
163 lines
6.1 KiB
Markdown
# Using AI Coding Agents with Dev Containers
|
|
|
|
This project ships with a [Dev Container](https://containers.dev/) configuration that enables
|
|
AI coding agents to run autonomously inside a sandboxed environment with network-level restrictions.
|
|
|
|
[Claude Code](https://claude.ai/claude-code) is pre-installed and configured out of the box,
|
|
but the setup also works with other agents such as [OpenAI Codex CLI](https://github.com/openai/codex)
|
|
and [opencode](https://opencode.ai).
|
|
|
|
This setup is ideal for letting AI agents work on your Symfony project autonomously
|
|
while ensuring they cannot reach arbitrary internet hosts.
|
|
|
|
## Prerequisites
|
|
|
|
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) (or any Docker-compatible runtime)
|
|
- [Visual Studio Code](https://code.visualstudio.com/) with the [Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) extension
|
|
- A valid subscription or API key for the agent you want to use
|
|
|
|
## Quick Start
|
|
|
|
1. Open the project in Visual Studio Code.
|
|
2. When prompted "Reopen in Container", click **Reopen in Container**.
|
|
Alternatively, open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`) and run
|
|
**Dev Containers: Reopen in Container**.
|
|
3. Wait for the container to build and start. On each container start, the
|
|
`postStartCommand` configures the firewall automatically.
|
|
4. Claude Code is pre-installed and configured in YOLO mode — open the Claude Code
|
|
panel in Visual Studio Code or run `claude` in the integrated terminal to start using it.
|
|
|
|
That's it. Claude Code will run without permission prompts, and the firewall ensures
|
|
network access is restricted to only the necessary services.
|
|
|
|
## What Is YOLO Mode?
|
|
|
|
YOLO mode (also known as "bypass permissions" mode) allows Claude Code to execute
|
|
commands, edit files, and perform actions without asking for confirmation at each step.
|
|
This dramatically speeds up autonomous coding workflows.
|
|
|
|
The Dev Container configuration enables this via two Visual Studio Code settings:
|
|
|
|
```json
|
|
{
|
|
"claudeCode.allowDangerouslySkipPermissions": true,
|
|
"claudeCode.initialPermissionMode": "bypassPermissions"
|
|
}
|
|
```
|
|
|
|
## Network Sandboxing
|
|
|
|
Running an AI agent with full autonomy requires guardrails. The Dev Container includes
|
|
a firewall script (`.devcontainer/init-firewall.sh`) that locks down outbound network
|
|
access using `iptables` and `ipset`. Only the following destinations are allowed:
|
|
|
|
| Destination | Reason |
|
|
| ------------------------------------------------- | ------------------------------- |
|
|
| GitHub (`github.com`, `api.github.com`) | Git operations, API access |
|
|
| Anthropic (`anthropic.com`) | Claude Code backend |
|
|
| npm registry (`registry.npmjs.org`) | Node.js dependencies |
|
|
| Packagist (`packagist.org`, `repo.packagist.org`) | PHP/Composer dependencies |
|
|
| Visual Studio Code Marketplace | Extension downloads |
|
|
| Sentry, Statsig | Telemetry (used by Claude Code) |
|
|
| Host gateway IP | Communication with Docker host |
|
|
|
|
All other outbound connections are **rejected**. The firewall uses
|
|
[dnsmasq](https://thekelleys.org.uk/dnsmasq/doc.html) to dynamically resolve
|
|
and whitelist IPs for allowed domains, handling CDN IP rotation gracefully.
|
|
|
|
Inbound connections from the host gateway IP are allowed on all ports,
|
|
and ports 80, 443 (TCP), and 443 (UDP/HTTP3) are open to any source
|
|
so you can access your Symfony app from the host browser.
|
|
|
|
## Customizing the Allowed Domains
|
|
|
|
To allow additional domains (e.g., a private registry or API), edit
|
|
`.devcontainer/init-firewall.sh` and add them to the `ipset` line in the
|
|
dnsmasq configuration section:
|
|
|
|
```bash
|
|
# Domains are '/'-separated, ending with the ipset name
|
|
ipset=/github.com/anthropic.com/your-domain.com/allowed-domains
|
|
```
|
|
|
|
Then rebuild the Dev Container for the changes to take effect.
|
|
|
|
## Using Other Agents
|
|
|
|
The Dev Container's network sandbox and project context (`.devcontainer/AGENTS.md`) work
|
|
with any AI coding agent. You just need to install the agent and whitelist the domains it
|
|
needs to reach.
|
|
|
|
### OpenAI Codex CLI
|
|
|
|
1. Add the OpenAI API domain to the firewall allowlist in `.devcontainer/init-firewall.sh`
|
|
(see [Customizing the Allowed Domains](#customizing-the-allowed-domains)):
|
|
|
|
```bash
|
|
ipset=/.../api.openai.com/allowed-domains
|
|
```
|
|
|
|
2. Install and run Codex inside the container:
|
|
|
|
```console
|
|
npm install -g @openai/codex
|
|
export OPENAI_API_KEY=your-key
|
|
codex --full-auto
|
|
```
|
|
|
|
### opencode
|
|
|
|
1. Add the required API domain to the firewall allowlist (e.g., `api.anthropic.com`,
|
|
`api.openai.com`, or your provider's domain).
|
|
|
|
2. Install and run opencode inside the container:
|
|
|
|
```console
|
|
curl -fsSL https://opencode.ai/install | bash
|
|
opencode
|
|
```
|
|
|
|
### Other Agents
|
|
|
|
For any other agent, follow the same pattern:
|
|
|
|
1. Add the agent's API domain(s) to the firewall allowlist.
|
|
2. Install the agent inside the container.
|
|
3. Run it — the `.devcontainer/AGENTS.md` file provides project context
|
|
to agents that support the convention.
|
|
|
|
## Using Without Visual Studio Code
|
|
|
|
The Dev Container configuration works with any tool that supports the
|
|
[Dev Container specification](https://containers.dev/), including:
|
|
|
|
- [Dev Container CLI](https://github.com/devcontainers/cli) (`devcontainer up`)
|
|
- [GitHub Codespaces](https://github.com/features/codespaces)
|
|
- JetBrains IDEs (with the Dev Containers plugin)
|
|
|
|
To use Claude Code from the terminal inside the container:
|
|
|
|
```console
|
|
claude
|
|
```
|
|
|
|
To start directly in YOLO mode from the CLI:
|
|
|
|
```console
|
|
claude --dangerously-skip-permissions
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Firewall blocks a required domain
|
|
|
|
If your agent or Composer/npm fails to reach a service, check the firewall
|
|
logs and add the domain to the dnsmasq allowlist as described above.
|
|
|
|
### Container fails to start
|
|
|
|
Ensure Docker is running and that you have allocated enough resources
|
|
(at least 2 GB of RAM for the container). The firewall setup requires
|
|
`NET_ADMIN` capability, which the Dev Container configures automatically
|
|
via Docker Compose.
|