---
name: container-networking
description: Use when configuring container networking, exposing ports, setting up tunnels, SSH access, VPNs, or Tor. Triggers for requests about port forwarding, public URLs, webhooks, network isolation, or container-to-container communication.
---

# Container Networking

Configure networking for gaol containers.

## Port Mapping

### In Spec Files
```yaml
network:
  ports:
    - 8080:80      # host:container
    - 3000:3000
```

### At Creation
```bash
gaol create webserver -p 80:80 -p 443:443 --start
```

## Dev Tunnels (Public URLs)

Expose containers to the internet via cloudflared:

```bash
# Start a tunnel
gaol tunnel start <container> <port>

# List active tunnels
gaol tunnel list

# Stop a tunnel
gaol tunnel stop <tunnel-id>

# Stop all tunnels for a container
gaol tunnel stop-all --container <name>
```

Tunnels provide temporary public URLs for:
- Webhook testing
- Demos
- Mobile app testing
- Sharing work in progress

## SSH Config

Generate SSH config entries for containers:

```bash
# Generate config entry
gaol ssh-config <container>

# Append to ~/.ssh/config
gaol ssh-config <container> --append

# Then connect with
ssh <container>
```

## Network Modes

```yaml
network:
  mode: shared    # Default: NAT through host
  mode: bridged   # Direct network access
  mode: host      # Share host network
  mode: none      # No networking
```

## Privacy Networking

### Tor Transparent Proxy
```bash
gaol create secure --profile tor-transparent --start
# All container traffic routes through Tor
```

### VPN Gateway
```bash
gaol network vpn-gateway create vpn1 --config ~/vpn/client.ovpn
```

### WireGuard Mesh
```bash
gaol network wireguard create mesh1 --subnet 10.200.0.0/24
gaol network wireguard add-peer mesh1 --peer-name peer1 --public-key KEY
```

## Container Groups (Networking)

For containers that need to communicate:

```yaml
# group.yaml
name: web-stack
shared_network: true
containers:
  db:
    image: postgres:16
  api:
    depends_on: [db]
    environment:
      DATABASE_URL: postgres://db:5432/app
  web:
    depends_on: [api]
    ports: ["80:80"]
```

```bash
gaol group up group.yaml
```

Containers can reach each other by name (e.g., `db`, `api`).
