Skip to content
SomewearDocs
Support

Install TVPN with Docker

Install

  1. Pull the latest image:
docker pull us-docker.pkg.dev/somewear-souvla/tvpn/somewear-tvpn:latest
  1. Create a compose.yaml file:
services:
  tvpn:
    image: us-docker.pkg.dev/somewear-souvla/tvpn/somewear-tvpn:latest
    container_name: somewear-tvpn
    restart: unless-stopped
    network_mode: host
    privileged: true
    devices:
      - /dev/net/tun:/dev/net/tun
    cap_add:
      - NET_ADMIN
    volumes:
      - /var/lib/somewear/tvpn:/var/lib/somewear/tvpn
  1. Create /var/lib/somewear/tvpn/config.toml:
# Log to stdout so docker captures the output
[log]
stdout = true
  1. docker compose up -d — starts the TVPN container.
  2. docker ps — confirm the somewear-tvpn container is running.
  3. docker exec -it somewear-tvpn sh -c "tvpn auth sign-in" — sign in and authenticate.

Ping test

  1. You’ll need at least 2 devices with TVPN installed for this test.
  2. sudo docker exec -it somewear-tvpn bash — start a shell session in the container.
  3. docker exec -it somewear-tvpn sh -c "tvpn ip list" — lists the virtual IPs in your Workspace. Copy one (not your own).
  4. ping <ip> — ping it. This may take a second or two if TVPN is still booting up in the background.
  5. Ctrl+C to stop the ping.

Configuration

TVPN’s configuration file is at /var/lib/somewear/tvpn/config.toml. Edit it and restart TVPN (docker exec -it somewear-tvpn sh -c "tvpn down && tvpn up") to apply changes. Run tvpn -h for the full list of settings.

Here’s a complete example:

[api]
key = "wk_1a2b3c4d5e6f:sk_9f8e7d6c5b4a3210"
# The API hostname. You only need to change this if you're using Somewear Self-Hosted
host = "api.somewear.co"


[log]
# The log level: trace, debug, info, warn, error, or off.
level = "info"
# The log style: compact or logfmt.
style = "logfmt"
# Whether to write to stdout.
stdout = true


[log.filesystem]
# The maximum size in MB to use for log files.
max-size-mb = 50
# The maximum number of log files to use.
max-files = 5


[tls]
# TLS cryptographic profile: PQ_HYBRID (default), CNSA_2_0, or CNSA_1_0.
profile = "PQ_HYBRID"
# TLS session rekey interval in seconds; sessions older than this trigger re-handshake.
rekey-interval = 3600
# When true, allow loading TLS certificates from filesystem as a fallback
# when IPC cert bundles are unavailable. Defaults to false.
cert-files = false


[endpoint-id.rotation]
# Endpoint ID rotation interval in seconds.
interval = 86400


[traffic-policy]
# Traffic policy toggle, default is false. When true, the daemon attempts to load traffic-policy.toml.
enabled = false


[tun]
# The MTU to use on the TUN device.
mtu = 1400


[interfaces]
# The list of interfaces which should not be used to route traffic through or receive traffic from.
disabled = ["eth1", "wlan2"]
# The list of interfaces that would be disabled by tvpn based on their name but
# we want to allow them to be used. Interfaces in here are still bound to the
# usual rules, like whether it's up, operational, etc.
allowed = ["br-lan"]
# Whether to allow virtual interfaces.
allow-virtual = false


[gateway-routes]
# Whether to enable the use of literal routes. This is needed on every endpoint if you're using literal routes
allow-literal = true
# The list of literal gateway routes.
literal = ["192.168.10.0/24"]


# The list of virtual routes; each maps a physical range to a virtual range.
[[gateway-routes.virtual]]
physical = "192.168.1.0/24"
virtual = "100.127.0.0/24"


[[gateway-routes.virtual]]
physical = "10.0.2.0/24"
virtual = "100.127.1.0/24"


[relays]
# The list of relay servers to use.
servers = ["uswest1-0.relay.somewear.app", "uscentral1-0.relay.somewear.app", "useast4-0.relay.somewear.app"]