Manage the shared nginx-proxy Docker container and its network connections. Auto-discovers app containers via VIRTUAL_HOST labels. Start this first — it crea...
---
name: Proxy Manager
slug: proxy-manager
version: 1.1.0
description: "Manage the shared nginx-proxy Docker container and its network connections. Auto-discovers app containers via VIRTUAL_HOST labels. Start this first — it creates the shared Docker network used by mysql-manager and worktree-manager."
changelog: "v1.1.0: Pin image to jwilder/nginx-proxy:1.3.1, bind port 80 to 127.0.0.1, restrict auto-connect to PROJECT_PREFIX networks only with confirmation prompt, document Docker socket privilege and restart persistence."
triggers:
- "start proxy"
- "stop proxy"
- "nginx status"
- "proxy status"
- "conectar proxy"
- "connect proxy"
- "proxy-manager"
- "rotas do nginx"
- "nginx routes"
metadata: {"clawdbot":{"emoji":"🔀","requires":{"bins":["docker"]},"os":["linux","darwin"]}}
---
# Proxy Manager
Manages the shared nginx-proxy Docker container (`jwilder/nginx-proxy`) and the Docker network (`nginx-proxy_net`) used by all dev instances.
The proxy auto-discovers containers with `VIRTUAL_HOST` labels and creates routes. It also owns the shared Docker network that allows MySQL and app containers to communicate.
## Architecture
```
proxy-manager/
├── docker-compose.yml # nginx-proxy container + codai_net network
└── run.sh # lifecycle + network connection CLI
```
Start order: **proxy-manager first** (creates the network), then mysql-manager, then worktree-manager.
## Commands
```bash
./run.sh start # start nginx-proxy (creates codai_net network)
./run.sh stop # stop nginx-proxy
./run.sh status # show status, connected networks, active routes
./run.sh connect <instance> # connect proxy to instance's Docker network
./run.sh disconnect <instance> # disconnect proxy from instance network
./run.sh auto-connect # connect proxy to ALL project networks
./run.sh reload # reload nginx config without restart
```
## How to Execute Tasks
### First-time setup
```bash
cd proxy-manager && ./run.sh start
```
Creates the shared `nginx-proxy_net` Docker network and starts the proxy on port 80.
### After starting an app instance
After `worktree-manager start <name>`, connect the proxy so routes become available:
```bash
./run.sh connect <name>
```
Routes: `http://<name>.frontend.localhost` and `http://<name>.backend.localhost`
### After restarting Docker or the host
Proxy reconnects automatically via `restart: unless-stopped`. If routes are missing, run:
```bash
./run.sh auto-connect
```
### Check active routes
```bash
./run.sh status
```
## Startup Order
1. `proxy-manager start` — creates network, starts proxy
2. `mysql-manager start` — joins the shared network
3. `worktree-manager start <instance>` — starts app containers
4. `proxy-manager connect <instance>` — activates routing
## Configuration
| Variable | Default | Purpose |
|------------------|---------------------|----------------------------------|
| `PROXY_CONTAINER`| `codai_nginx_proxy` | nginx-proxy container name |
| `CODAI_NETWORK` | `nginx-proxy_net` | Shared Docker network name |
| `PROJECT_PREFIX` | `codai-dev` | Docker Compose project prefix |
## How VIRTUAL_HOST Routing Works
1. App containers declare `VIRTUAL_HOST=<name>.frontend.localhost` as a label
2. `jwilder/nginx-proxy` reads Docker socket events and generates nginx config
3. Proxy container must share at least one Docker network with the app container
4. `./run.sh connect <instance>` connects proxy to the instance's network
## Security Notes
- **Docker socket**: The proxy mounts `/var/run/docker.sock:ro` to auto-discover containers. This is required for VIRTUAL_HOST routing but grants the container read access to Docker daemon state. Only run on trusted development machines.
- **Port 80**: Bound to `127.0.0.1` — routes are reachable from the host only, not from other machines on the network.
- **Image provenance**: Pinned to `jwilder/nginx-proxy:1.3.1`. Review image updates before pulling a newer tag.
## Rules
- Start proxy-manager **before** mysql-manager and worktree-manager.
- After `worktree-manager start <name>`, always run `proxy-manager connect <name>` to activate routes.
- `auto-connect` only connects to networks matching `PROJECT_PREFIX` and requires confirmation — use `connect <instance>` for targeted single-instance connections.
- `stop` does NOT remove the Docker network. Other containers on the network remain reachable.
- The container uses `restart: unless-stopped` — it survives Docker daemon restarts. Run `./run.sh stop` when done.
## Related Plugins
- `mysql-manager` — shared MySQL container (start after proxy-manager)
- `worktree-manager` — app instances and git worktrees (start after both)
don't have the plugin yet? install it then click "run inline in claude" again.