Quick start

Quick start

1. Expose Gluetun's HTTP proxy on the host

# in your existing Gluetun docker-compose.yml
ports:
  - 8887:8888   # or whichever port you have configured

environment:
  HTTPPROXY: "on"
  HTTPPROXY_LOG: "off"
  # HTTPPROXY_USER: ""       # optional — set in the UI Settings if needed
  # HTTPPROXY_PASSWORD: ""

2. Mount the Gluetun compose directory

The companion needs write access to the directory containing your Gluetun docker-compose.yml so it can write a docker-compose.override.yml and restart the service.

Unraid / DockerMan If Gluetun is managed by Unraid's Docker Manager (net.unraid.docker.managed=dockerman), Companion auto-detects that backend and does not use docker compose for switches. Mount the Unraid template directory as writable, for example - /boot/config/plugins/dockerMan/templates-user:/boot/config/plugins/dockerMan/templates-user, so changes are persisted back into the DockerMan template before the container is recreated. CONTROL_BACKEND=unraid can force this mode if automatic detection is not enough.

3. Run the companion

services:

  socket-proxy:
    image: tecnativa/docker-socket-proxy
    container_name: socket-proxy
    restart: always
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    environment:
      CONTAINERS: 1
      IMAGES: 1
      NETWORKS: 1
      VOLUMES: 1
      POST: 1
      DELETE: 1
    networks:
      - companion-net

  gluetun-companion:
    image: ghcr.io/aerya/gluetun-companion:latest
    container_name: gluetun-companion
    restart: always
    ports:
      - 8765:8765
    volumes:
      - /path/to/data:/data
      - /path/to/gluetun/stack:/compose   # ← adapt this path
      - /path/to/gluetun/openvpn:/openvpn
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      - TZ=Europe/Paris
      - SECRET_KEY=replace-with-a-random-string   # openssl rand -hex 32
      - DATA_DIR=/data
      - GLUETUN_HOST=host.docker.internal
      - GLUETUN_PROXY_PORT=8887
      - GLUETUN_CONTAINER=gluetun-airvpn   # exact name of your Gluetun container (Compose service name is auto-detected)
      - COMPOSE_DIR=/compose
      - OPENVPN_CONFIG_DIR=/openvpn
      - OPENVPN_CONTAINER_DIR=/gluetun/openvpn
      - DOCKER_HOST=tcp://socket-proxy:2375
      # Optional: protect /metrics with a Bearer token.
      # Leave unset (or empty) for open access — standard for internal Prometheus scrapes.
      # - METRICS_TOKEN=your-secret-token
    networks:
      - companion-net
    depends_on:
      - socket-proxy

networks:
  companion-net:

docker compose up -d

Why socket-proxy? The Docker socket gives near-total access to the host. The Tecnativa proxy sits between Companion and the socket, restricting access to the required operations: reading containers/images/networks/volumes, plus POST/DELETE needed to create and remove temporary sidecar containers. It blocks direct daemon access (exec, info, swarm…). Fully transparent for the user, reduced attack surface.

Open http://localhost:8765 — first login: enter the credentials you want (account created automatically).

Unraid / DockerMan: a temporary XML template is available in templates/unraid for manual install or Private Apps, pending a possible Community Applications publication.

Companion in the same stack as Gluetun? Remove extra_hosts and use the service name: GLUETUN_HOST: gluetun. On a switch, the companion only targets the Gluetun service (docker compose up -d <service>) — it never restarts itself.

4. Import servers

Servers → Import from Gluetun: the companion reads SERVER_NAMES, SERVER_COUNTRIES, etc. directly from the running container and imports each value with its filter type. The Gluetun catalogue can also import servers by country, city, region, hostname or name, with server-type filtering when the provider exposes it (for example P2P, Streaming, Secure Core, Tor or Free on ProtonVPN). Manual addition is also available on the same screen.

Each entry is a Gluetun target. SERVER_NAMES=CH#12 targets that exact server. SERVER_COUNTRIES=Switzerland targets the country: Companion requests “Switzerland”, then Gluetun selects a compatible endpoint in that country, just as it does on its own. To compare Proton servers individually, open the Gluetun Catalogue and import their names. More candidates may improve selection, but make benchmarks longer.

---