# "VPN on Zerops"


## Keywords
vpn, wireguard, zcli vpn, vpn up, vpn down, local development, service access, mtu

## TL;DR
Zerops VPN uses WireGuard via `zcli vpn up <project-id>` — connects to one project at a time, services accessible by hostname, but env vars are NOT available through VPN.

## Commands
```bash
zcli vpn up <project-id>                    # Connect
zcli vpn up <project-id> --auto-disconnect  # Auto-disconnect on terminal close
zcli vpn up <project-id> --mtu 1350        # Custom MTU (default 1420)
zcli vpn down                               # Disconnect
```

## Behavior
- All services accessible via hostname (e.g., `db`, `api`) — `.zerops` suffix optional
- **One project at a time** — connecting to another disconnects the current
- Automatic reconnection with daemon
- **Environment variables NOT available** through VPN — use GUI or API to read them

## Hostname Resolution
- Both plain hostname (`db`) and suffixed (`db.zerops`) work — VPN configures a DNS search domain
- Plain hostname is resolved via the `.zerops` search domain automatically (e.g., `db` → `db.zerops`)
- Example: `postgresql://user:pass@db:5432/mydb` or `postgresql://user:pass@db.zerops:5432/mydb`
- Note: CLI tools like `dig`, `nslookup`, `host` bypass the system resolver and may show false NXDOMAIN — use `dscacheutil -q host -a name db` on macOS to verify, or just test with `nc -zv db 5432`

## Troubleshooting

| Problem | Solution |
|---------|----------|
| Interface already exists | `zcli vpn down` then `zcli vpn up` |
| Hostname not resolving | Try `db.zerops` suffix. On Windows, add `zerops` to DNS suffix list. Note: `dig`/`nslookup` bypass system resolver — use `nc -zv db 5432` to test |
| WSL2 not working | Enable systemd in `/etc/wsl.conf` under `[boot]` |
| Conflicting VPN | Use `--mtu 1350` |
| Ubuntu 25.* issues | Install AppArmor utilities |

## Gotchas
1. **No env vars via VPN**: Must read env vars from GUI or API — VPN only provides network access
2. **One project at a time**: Cannot connect to multiple projects simultaneously
3. **Hostname resolution**: Both `hostname` and `hostname.zerops` work (VPN sets up DNS search domain). Use plain hostname for simplicity. If resolution fails on Windows, add `zerops` to DNS suffix list in Advanced TCP/IP Settings.

## See Also
- zerops://guides/networking
- zerops://guides/firewall