init
This commit is contained in:
AlexBa16
+162
@@ -0,0 +1,162 @@
|
||||
# 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.
|
||||
Reference in New Issue
Block a user