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:
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:
- Stand up
connect serversomewhere reachable by your agents — see Server Configuration Reference and Production Operations for a minimal deployment. - Point the agent at it instead of the hosted endpoint:
tunnel-defaults: endpoint: https://your-server.example.com:8119/connect/https - 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
- Tunnel Types — configure and use the built-in server types (HTTP reverse proxy, TCP, file sharing, CoreDNS, mail routing, and more).
- Agent Configuration Reference / Server Configuration Reference — every config key.
- Authentication — agent identity and tunnel-traffic auth.
- CLI Reference — every command and flag.