Skip to content

Quickstart

Three steps regardless of platform: install, set up and sign in (connect agent init), run (connect agent). Once running, connect agent status --endpoint-urls prints each tunnel's public URL, and the agent's local management console at http://localhost:4444 lists each tunnel and its state.

You need a Dioad Connect account. If you don't have one, you can create one for free on the sign-in page that setup opens.

This page covers the hosted service at connect.dioad.dev — the fastest way to try Dioad Connect, no server of your own required. For running your own Connect Server instead, see Self-hosted below.

macOS (Homebrew)

# 1. Install
brew install dioad/tap/connect

# 2. Set up & sign in (a wizard writes your config, then signs you in through your browser)
connect agent init

# 3. Start the agent
connect agent

Docker

The dioad/connect image supports both linux/amd64 and linux/arm64 (works on Raspberry Pi). The image's entrypoint is already connect agent, so commands after the image name are connect agent subcommands.

# 1. Set up and sign in (run once). The wizard writes your config and signs you in through your
#    browser; both are kept in a named volume.
docker run --rm -it -v dioad-connect-persist:/persist dioad/connect:fd25d71 init

# 2. Start the agent. It picks up the config the wizard wrote.
docker run -d --name dioad-connect --restart unless-stopped \
  -p 127.0.0.1:4444:4444 \
  -v dioad-connect-persist:/persist \
  dioad/connect:fd25d71

Print your tunnel's public URL with docker exec dioad-connect /connect agent status --endpoint-urls, or open the management console at http://localhost:4444 and sign in as admin with the password you chose in the wizard. To seed the admin password from the environment instead (for unattended deployments), see Production Operations.

To share a directory, use the -file image variant for both steps. Its wizard starts on the File tunnel and offers /data, where you mount your directory:

docker run --rm -it -v dioad-connect-persist:/persist dioad/connect:fd25d71-file init

docker run -d --name dioad-connect --restart unless-stopped \
  -p 127.0.0.1:4444:4444 \
  -v dioad-connect-persist:/persist -v /my/path/to/share:/data \
  dioad/connect:fd25d71-file

Docker Compose

The same two steps with Compose. Save this as compose.yaml:

compose.yaml
services:
  agent:
    image: dioad/connect:fd25d71
    restart: unless-stopped
    environment:
      # What the agent tells you to run to set up, start, or sign in later
      CONNECT_INIT_COMMAND: docker compose run --rm agent init
      CONNECT_START_COMMAND: docker compose up -d
      CONNECT_AUTH_COMMAND: docker compose run --rm agent auth
    ports:
      - "127.0.0.1:4444:4444"
    volumes:
      - persist:/persist

volumes:
  persist:
# 1. Set up and sign in (run once)
docker compose run --rm agent init

# 2. Start the agent
docker compose up -d

For the -file variant, use the dioad/connect:fd25d71-file image and add your directory to volumes as - /my/path/to/share:/data.

Linux

Available as apk (Alpine), deb (Debian/Ubuntu), rpm (RHEL/Fedora), or a plain tarball. arm64 builds are published alongside each amd64 one — substitute the architecture in the filename.

Alpine (apk):

curl -LO https://releases.lab.dioad.net/data/connect/fd25d71/dioad-connect_fd25d71_linux_amd64.apk
apk add --allow-untrusted ./dioad-connect_fd25d71_linux_amd64.apk

Debian / Ubuntu (deb):

curl -LO https://releases.lab.dioad.net/data/connect/fd25d71/dioad-connect_fd25d71_linux_amd64.deb
sudo dpkg -i ./dioad-connect_fd25d71_linux_amd64.deb

RHEL / Fedora (rpm):

curl -LO https://releases.lab.dioad.net/data/connect/fd25d71/dioad-connect_fd25d71_linux_amd64.rpm
sudo rpm -i ./dioad-connect_fd25d71_linux_amd64.rpm

Tarball (any distro):

curl -LO https://releases.lab.dioad.net/data/connect/fd25d71/connect_linux_amd64.tar.gz
tar -xzf connect_linux_amd64.tar.gz
sudo mv connect /usr/local/bin/connect

Then, for any of the above:

connect agent init
connect agent

The deb/rpm packages also install systemd units (connect-agent.service) if you'd rather run the agent as a service from the start — see Daemon and OS Service.

Windows (PowerShell)

# 1. Download & install
$dir = "$env:LOCALAPPDATA\Programs\Dioad\Connect"
Invoke-WebRequest -Uri https://releases.lab.dioad.net/data/connect/fd25d71/connect_windows_amd64.zip -OutFile connect.zip
Expand-Archive connect.zip -DestinationPath $dir -Force
# Add connect to your PATH, for new windows and this one
[Environment]::SetEnvironmentVariable("Path", [Environment]::GetEnvironmentVariable("Path", "User") + ";$dir", "User")
$env:Path += ";$dir"

# 2. Set up & sign in (a wizard writes your config, then signs you in through your browser)
connect agent init

# 3. Start the agent
connect agent

Use connect_windows_arm64.zip on ARM64 systems. Management console available at http://localhost:4444.

What connect agent init does

The interactive setup wizard asks two things: a tunnel type (and, for most types, what it should expose) and a password for the management console's admin user. It writes an agent.yaml to the default config location, then signs you in to Dioad Connect in the same session (equivalent to running connect agent auth separately — see Authentication). See Tunnel Types for what each type does and Agent Configuration Reference for every key.

Run connect agent init --advanced to also choose the tunnel name, the management console's address and admin username, and to review the config before it is written.

Self-hosted

Hosted vs. self-hosted

Everything above talks to the hosted connect.dioad.dev service. To use your own Connect Server instead:

  1. Stand up connect server somewhere reachable by your agents — see Server Configuration Reference and Production Operations for a minimal deployment.
  2. Point the agent at it instead of the hosted endpoint:
    tunnel-defaults:
      endpoint: https://your-server.example.com:8119/connect/https
    
  3. Configure how your server authenticates incoming agents — see Authentication.

The install/agent init/connect agent flow above is otherwise identical; only the endpoint and server-side auth setup differ.

Next steps