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.

⚠️ Companion benchmarks each server individually, by name. Setting SERVER_COUNTRIES, SERVER_REGIONS or SERVER_CITIES adds a single entry (e.g. "France") — Companion does not automatically discover individual servers in that country. Add each server by its name (SERVER_NAMES) for benchmarking to work. Minimum 2 named servers required.

---