gluetun/devrun/README.md

devrun

devrun is a small development helper for starting a local qmcgaw/gluetun Docker container with provider credentials stored in an encrypted file.

It solves two practical problems for local development:

• keeping VPN credentials out of the shell history and out of a plaintext file once setup is complete;
• quickly starting a Gluetun container for a specific provider and VPN type with a small set of extra Docker runtime options.

The tool has four commands:

• add-cred: add or replace credentials for one provider and one VPN type in the encrypted store credentials;
• delete-cred: remove credentials for one provider and one VPN type from the encrypted store credentials;
• dump-cred: print credentials for one provider and one VPN type from the encrypted store credentials;
• run: decrypt credentials on demand, build the required Gluetun environment variables, and run a qmcgaw/gluetun container.

Prerequisites

• Go installed locally
• Docker installed and a daemon available to the Docker client
• an interactive terminal, since the tool prompts for passwords without echoing them

The Docker client is created from the standard Docker environment, so settings such as DOCKER_HOST are honored.

Quick start

Add credentials

Add one credential entry to the encrypted store:

go run ./cmd/main.go add-cred protonvpn openvpn
go run ./cmd/main.go add-cred mullvad wireguard

Behavior:

• if credentials does not exist yet, add-cred asks for a new credentials password and creates the encrypted store;
• if credentials already exists, add-cred asks for the existing password first, decrypts the store, updates it, and writes it back encrypted;
• sensitive fields are read from stdin without echo.

Prompted values depend on the VPN type:

• openvpn: username and password
• wireguard: private key, optional address, optional preshared key

Running add-cred again for the same provider and VPN type replaces the existing values for that entry.

Delete credentials

Remove one credential entry from the encrypted store:

go run ./cmd/main.go delete-cred protonvpn openvpn

This asks for the credentials password first, decrypts the store, removes the requested provider and VPN type, and writes the store back encrypted.

Dump credentials

Print one credential entry from the encrypted store:

go run ./cmd/main.go dump-cred protonvpn openvpn

This asks for the credentials password first and then prints the selected provider and VPN type values.

Container run

Run a container using the image qmcgaw/gluetun and the encrypted credentials with the run command. For example:

go run ./cmd/main.go run mullvad wireguard
go run ./cmd/main.go run protonvpn wireguard -e PORT_FORWARDING=on -p 8000:8000/tcp

You will be prompted for the credentials password, the file credentials will be decrypted in memory, and the container will be started.

The following environment variables are always added by the tool:

• VPN_SERVICE_PROVIDER=<provider>
• VPN_TYPE=<vpn-type>
• LOG_LEVEL=debug

The tool also adds NET_ADMIN to the container capabilities by default.

Credential model

Internally, the encrypted file stores a binary-encoded map keyed by provider name. Each provider can define openvpn, wireguard, or both.

Conceptually, the stored data looks like this:

• provider mullvad: contains wireguard
• provider protonvpn: contains wireguard
• provider protonvpn: contains openvpn

You do not edit this directly. It is stored as encrypted binary data in credentials.

OpenVPN fields

• username is required;
• password is required;

At runtime these map to:

• OPENVPN_USER
• OPENVPN_PASSWORD

WireGuard fields

• private_key is required and must be a valid WireGuard private key;
• address is optional and must be a valid network prefix if set;
• preshared_key is optional and must be a valid WireGuard key if set.

At runtime these map to:

• WIREGUARD_PRIVATE_KEY
• WIREGUARD_ADDRESSES when address is set
• WIREGUARD_PRESHARED_KEY when preshared_key is set

Supported extra Docker flags

The run command only accepts a focused subset of Docker-style runtime flags. Unsupported flags return an error.

Supported flags:

• -e, --env KEY=VALUE
• -v, --volume SOURCE:TARGET[:mode]
• -p, --publish HOSTPORT:CONTAINERPORT[/proto]
• --dns IP
• --device SPEC
• --label KEY=VALUE
• --cap-add CAPABILITY

Signals and shutdown

While the container is running:

• the first Ctrl+C requests a graceful stop with a 5 second timeout;
• the second Ctrl+C sends a kill signal to the container;
• a further interrupt exits the tool immediately.

Notes and limitations

• The container image is fixed to qmcgaw/gluetun.
• The container name is fixed to gluetun.
• Credentials are decrypted in memory only during execution.
• If the requested provider or VPN type is not present in the encrypted credentials file, the command fails with an explicit error.
• The encrypted credential store file is named credentials.
• This tool is intended for local development convenience, not as a general replacement for docker run.