Skip to content

agents.md

Latest commit

 

History

History
162 lines (115 loc) · 6.14 KB

agents.md

File metadata and controls

162 lines (115 loc) · 6.14 KB

Using AI Coding Agents with Dev Containers

This project ships with a Dev Container configuration that enables AI coding agents to run autonomously inside a sandboxed environment with network-level restrictions.

Claude Code is pre-installed and configured out of the box, but the setup also works with other agents such as OpenAI Codex CLI and opencode.

This setup is ideal for letting AI agents work on your Symfony project autonomously while ensuring they cannot reach arbitrary internet hosts.

Prerequisites

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:

{
  "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 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:

# 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):

    ipset=/.../api.openai.com/allowed-domains

  2. Install and run Codex inside the container:

    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:

    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, including:

To use Claude Code from the terminal inside the container:

claude

To start directly in YOLO mode from the CLI:

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.