Self-hosting wanctl

This guide runs Postgres, the relay, and the portal on one host. The host needs two DNS names, inbound HTTPS, Docker Engine, and Docker Compose, plus roughly 1.5 GB of disk for images: the first start builds wanctl from source inside Docker, which pulls the Go and Postgres base images and compiles for a few minutes. The examples use wanctl-relay.z10.dev and wanctl.z10.dev; replace both everywhere.

1. Create a GitHub OAuth App

Open GitHub Settings -> Developer settings -> OAuth Apps and choose New OAuth App.
Set Homepage URL to https://wanctl.z10.dev.
Set Authorization callback URL to https://wanctl.z10.dev/auth/callback. The scheme, host, and port must exactly match the portal's public origin.
Create a client secret and keep the client ID and secret for the next step.

2. Configure and start the services

All compose commands in this guide run from the selfhost/ directory, where Compose picks up .env and docker-compose.yml on its own:

cd selfhost
cp .env.example .env
chmod 600 .env

Edit .env: set RELAY_PUBLIC_ORIGIN and PORTAL_PUBLIC_ORIGIN to your two public origins, set WANCTL_GITHUB_CLIENT_ID and WANCTL_GITHUB_CLIENT_SECRET from step 1, and generate each local secret as described in its comment. The file holds all of the deployment's secrets, hence the chmod. Then start the stack:

docker compose up -d

The first start compiles wanctl inside Docker before anything comes up. If the host cannot reach proxy.golang.org, the build fails on module download timeouts — set GOPROXY in .env to a mirror you can reach (for example GOPROXY=https://goproxy.cn,direct) and run docker compose build again.

The relay waits for Postgres, runs its embedded migrations, and then reports healthy. The portal starts only after that. Inspect startup with:

docker compose ps
docker compose logs relay portal

Two log lines on a fresh deployment read like failures but are expected: release distribution disabled: read manifest: ... (no signed release directory is mounted) and lark approval disabled: ... (the optional Lark integration is not configured). Neither affects anything in this guide.

Postgres and the portal identity live in named volumes. docker compose down keeps them; docker compose down -v permanently removes them.

3. Put HTTPS in front

Both application ports bind only to loopback. A minimal Caddyfile is:

wanctl-relay.z10.dev { reverse_proxy 127.0.0.1:8080 }
wanctl.z10.dev { reverse_proxy 127.0.0.1:8081 }

Equivalent nginx server blocks are:

server {
    listen 443 ssl;
    server_name wanctl-relay.z10.dev;
    # Configure ssl_certificate and ssl_certificate_key for this name.
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
    }
}

server {
    listen 443 ssl;
    server_name wanctl.z10.dev;
    # Configure ssl_certificate and ssl_certificate_key for this name.
    location / {
        proxy_pass http://127.0.0.1:8081;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
    }
}

wanctl uses finite HTTP long-poll requests by default, so WebSocket upgrade support and streaming-specific timeouts are not required. Disabling nginx response buffering is sufficient; no other special proxy behavior is needed.

Before moving on, confirm each leg of the chain:

curl -s http://127.0.0.1:8080/healthz             # relay, direct: prints "ok"
curl -s https://wanctl-relay.z10.dev/healthz          # relay, through the proxy: "ok"
curl -s https://wanctl.z10.dev/healthz         # portal, through the proxy: "ok"
curl -s -o /dev/null -w '%{http_code}\n' https://wanctl.z10.dev/   # 303 (redirect to login)

The two /healthz endpoints are also the right targets for uptime monitoring; note that the applications answer GET, not HEAD.

Open https://wanctl.z10.dev. On a new database, the first GitHub account to complete login becomes the administrator. Later accounts remain on the pending page until invited.

Create an invite code for a second user with the admin CLI already inside the relay container (nothing beyond Docker is needed on the host):

docker compose exec -e WANCTL_RELAY=http://127.0.0.1:8080 relay wanctl admin invite

Alternatively, pre-approve a specific GitHub login by appending --github LOGIN. Give the one-time code to the user; the pending page accepts it.

On a device, install the signed binary from the project release page, point it at your instance (persisted; wanctl config shows and edits it later), then enroll and start it:

curl -fsSL https://github.com/Daily-AC/wanctl/releases/latest/download/install.sh | sh
wanctl config set relay=https://wanctl-relay.z10.dev portal=https://wanctl.z10.dev
wanctl start

The last command opens the portal, asks for the one-time enrollment code shown there, stores the issued token, and starts the agent. The agent makes outbound connections only. (wanctl start with nothing configured prompts for the two URLs on a terminal. Bare wanctl prints the help and does nothing, so running it on a machine you only control from leaves that machine alone.)

Optional: enable the portal device console

The portal can issue tokens and enroll devices without a portal token. Its live device console additionally needs a privileged token in the reserved portal namespace. After the relay is running, export the admin secret and issue one:

export WANCTL_ADMIN_SECRET='<value from selfhost/.env>'
curl -fsS https://wanctl-relay.z10.dev/admin/tokens/issue \
  -H "X-Admin-Secret: $WANCTL_ADMIN_SECRET" \
  -H 'Content-Type: application/json' \
  --data '{"namespace":"portal","label":"self-hosted portal","days":0}'

Set the returned wanctl_... value as WANCTL_PORTAL_TOKEN in selfhost/.env, then apply it with:

docker compose up -d portal

Optional: enable the hosted MCP endpoint

An AI host that cannot start a local wanctl process — a browser chat, a cloud agent runner — can talk to the relay's built-in MCP server over HTTP instead. Give the relay a seed and recreate it:

openssl rand -hex 32   # paste the value into WANCTL_MCP_SEED in selfhost/.env
docker compose up -d --no-deps relay

The relay logs MCP server enabled at /mcp on startup and serves https://wanctl-relay.z10.dev/mcp. If your edge proxy has already claimed the /mcp prefix, point hosts at https://wanctl-relay.z10.dev/wanctl-mcp instead: it is an alias onto the same handler and the same sessions, so nothing else changes. Each MCP session signs in separately through the portal; Connect an AI over MCP is the guide for whoever does that. Keep the seed stable — changing it signs every session out and voids every saved rebind credential.

A hosted session keeps its device trust in memory only, so the first time it reaches a device it stops at a fingerprint it cannot confirm by itself: the session can list devices but run nothing. Accepting that your own relay is not the attacker this guards against is what the opt-in costs; leave it unset and the endpoint stays read-only:

# selfhost/.env, then: docker compose up -d --no-deps relay
WANCTL_MCP_ALLOW_UNSAFE_TRUST_SERVER=1

A connector that opens a new MCP session per tool call — ChatGPT's does — can never hold a session-keyed login. Such clients authenticate with an OAuth 2.1 bearer instead, and the relay turns that on by itself once it has all three of a database, a public origin and a portal:

# selfhost/.env, then: docker compose up -d --no-deps relay
WANCTL_PUBLIC_ORIGIN=https://wanctl-relay.z10.dev
WANCTL_PORTAL=https://wanctl.z10.dev

The relay logs MCP OAuth enabled and publishes /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server; the consent page a person actually sees is served by the portal at /oauth/authorize. Clients register themselves, which grants nothing on its own — access begins when a signed-in person approves the request, and each approval appears in their token list labelled with the client's name, revocable there. Nothing changes for clients that send no bearer: they keep the per-session login. Migration 010 adds the two tables this needs, so back up the database before the first start on this version, as with any other schema change.

Optional: serve signed releases to devices

With release distribution enabled, devices install with one line and later upgrade with wanctl update, both verified against the project's release signature. Download a release's assets from GitHub Releases into selfhost/dist/, then tell the relay which signing key to trust — the trust anchor is compiled in at build time, deliberately not runtime config:

gh release download v0.2.0 --repo Daily-AC/wanctl --dir dist   # or curl each asset
# Derive the raw base64 key the relay build expects from the release's PEM:
openssl pkey -pubin -in dist/release-public.pem -outform DER | tail -c 32 | base64

Set that value as WANCTL_RELEASE_PUBLIC_KEYS in .env, then rebuild and restart the relay:

docker compose build relay && docker compose up -d relay

The relay log switches from release distribution disabled to serving /dl/*, and a device on a network that cannot reach GitHub installs from the mirror:

curl -fsSL https://wanctl-relay.z10.dev/install.sh | sh

irm https://wanctl-relay.z10.dev/install.ps1 | iex

Nothing has to be exported: a relay rewrites the installers it serves to point at its own /dl, since whoever could fetch the script from this relay can reach this relay — and often cannot reach the release page the script was built for. WANCTL_RELAY and WANCTL_DIST_BASE still override it, and a copy taken from the GitHub release page is unaffected. This requires RELAY_PUBLIC_ORIGIN (the compose file passes it to the relay as WANCTL_PUBLIC_ORIGIN).

Binaries installed this way still run wanctl update against the release page baked in at build time. On a network that cannot reach it, point them at the mirror once:

wanctl config set release_base=https://wanctl-relay.z10.dev/dl

This mirror is optional: official binaries and installers default to the project's GitHub release page for both install and wanctl update, so most deployments never need to serve /dl at all.

Devices do not wait to be told. A running wanctl agent checks the same signed manifest a minute after it starts and every six hours after that, and installs a newer release itself — verifying the signature, then restarting in place while keeping its pid. It skips the check while a session or job is running, and a binary in a directory it cannot write logs that sudo wanctl update is needed rather than attempting to elevate. wanctl config set auto_update=off on a device opts it out. When the release page is unreachable but the relay's mirror is configured, the automatic check falls back to the mirror exactly as wanctl update does.

Troubleshooting

GitHub reports a callback URL error. The OAuth App callback must exactly match PORTAL_PUBLIC_ORIGIN plus /auth/callback. Check the scheme, hostname, port, and any stale example value in selfhost/.env.

The portal exits with a session-secret error. WANCTL_SESSION_SECRET is measured in bytes and must be at least 32 bytes. openssl rand -hex 32 produces a suitable 64-character value. Recreate the portal after changing it.

The relay cannot connect to DATABASE_URL. It pings Postgres before serving and exits if the connection or embedded migration fails. Compose then restarts it under restart: unless-stopped; inspect docker compose logs relay postgres, and verify the database credentials. Do not disable migrations on a fresh database.

自己部署一套 wanctl

这份指南在同一台主机上跑起 Postgres、relay 和门户。这台主机需要两个 DNS 名字、入站 HTTPS、Docker Engine 和 Docker Compose，还要大约 1.5 GB 磁盘放镜像：第一次启动会在 Docker 里从源码构建 wanctl，要拉 Go 和 Postgres 的基础镜像，编译几分钟。例子里用的是 wanctl-relay.z10.dev 和 wanctl.z10.dev，两个都请全文替换掉。

1. 创建一个 GitHub OAuth App

打开 GitHub Settings -> Developer settings -> OAuth Apps，选 New OAuth App。
Homepage URL 填 https://wanctl.z10.dev。
Authorization callback URL 填 https://wanctl.z10.dev/auth/callback。协议、主机名和端口必须跟门户对外的 origin 完全一致。
创建一个 client secret，把 client ID 和 secret 留着，下一步要用。

2. 配置并启动服务

这份指南里所有 compose 命令都在 selfhost/ 目录下跑，Compose 会自己在那里认出 .env 和 docker-compose.yml：

cd selfhost
cp .env.example .env
chmod 600 .env

编辑 .env：把 RELAY_PUBLIC_ORIGIN 和 PORTAL_PUBLIC_ORIGIN 设成你那两个对外的 origin，把第 1 步拿到的 WANCTL_GITHUB_CLIENT_ID 和 WANCTL_GITHUB_CLIENT_SECRET 填进去，其余每个本地 secret 都按它注释里写的办法生成。这个文件装着这套部署的全部秘钥，chmod 就是为它准备的。然后启动整个栈：

docker compose up -d

第一次启动会先在 Docker 里把 wanctl 编出来，什么都还没起。如果主机连不上 proxy.golang.org，构建会卡在模块下载超时上——在 .env 里把 GOPROXY 设成一个你连得上的镜像（比如 GOPROXY=https://goproxy.cn,direct），再跑一次 docker compose build。

relay 会等 Postgres，跑完它内嵌的 migration，然后才报健康。门户在那之后才启动。用这两条看启动过程：

docker compose ps
docker compose logs relay portal

全新部署上有两行日志看着像出错，其实是预期之内的： release distribution disabled: read manifest: ...（没挂签名过的发布目录）和 lark approval disabled: ...（可选的 Lark 集成没配）。这两样都不影响本指南里的任何事。

Postgres 和门户身份放在具名卷里。docker compose down 会保留它们； docker compose down -v 会永久删掉。

3. 前面架上 HTTPS

两个应用端口都只绑在 loopback 上。一份最小的 Caddyfile 是：

wanctl-relay.z10.dev { reverse_proxy 127.0.0.1:8080 }
wanctl.z10.dev { reverse_proxy 127.0.0.1:8081 }

等价的 nginx server 块是：

server {
    listen 443 ssl;
    server_name wanctl-relay.z10.dev;
    # Configure ssl_certificate and ssl_certificate_key for this name.
    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
    }
}

server {
    listen 443 ssl;
    server_name wanctl.z10.dev;
    # Configure ssl_certificate and ssl_certificate_key for this name.
    location / {
        proxy_pass http://127.0.0.1:8081;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_buffering off;
    }
}

wanctl 默认用有限长度的 HTTP 长轮询请求，所以不需要 WebSocket 升级支持，也不需要为流式做特别的超时设置。把 nginx 的响应缓冲关掉就够了，没有别的代理行为需要特殊照顾。

往下走之前，把这条链路的每一段都确认一遍：

curl -s http://127.0.0.1:8080/healthz             # relay, direct: prints "ok"
curl -s https://wanctl-relay.z10.dev/healthz          # relay, through the proxy: "ok"
curl -s https://wanctl.z10.dev/healthz         # portal, through the proxy: "ok"
curl -s -o /dev/null -w '%{http_code}\n' https://wanctl.z10.dev/   # 303 (redirect to login)

这两个 /healthz 端点也正是可用性监控该盯的目标；注意应用回应的是 GET，不是 HEAD。

4. 登录并接入设备

打开 https://wanctl.z10.dev。在一个全新的数据库上，第一个走完 GitHub 登录的账号成为管理员。之后的账号会停在等待页上，直到被邀请。

用 relay 容器里已经带着的管理 CLI 给第二个用户开一个邀请码（主机上除了 Docker 什么都不需要）：

docker compose exec -e WANCTL_RELAY=http://127.0.0.1:8080 relay wanctl admin invite

也可以加上 --github LOGIN 直接预先放行某个 GitHub 账号。把一次性的码给那个人，等待页收这个码。

在设备上，从项目发布页装上签名过的二进制，把它指向你这套实例（会持久化；之后用 wanctl config 查看和修改），然后接入并启动：

curl -fsSL https://github.com/Daily-AC/wanctl/releases/latest/download/install.sh | sh
wanctl config set relay=https://wanctl-relay.z10.dev portal=https://wanctl.z10.dev
wanctl start

最后那条命令会打开门户，问你门户上显示的那个一次性接入码，存下签发的令牌，然后把 agent 启动起来。agent 只发起出站连接。（什么都没配的情况下跑 wanctl start，它会在终端里问你要这两个 URL。直接跑 wanctl 只打印帮助，什么都不做—— 在只用来当控制端的机器上敲它，不会把那台机器变成被控设备。）

可选：打开门户的设备控制台

门户不需要门户令牌就能签发令牌、接入设备。它那个实时设备控制台则额外需要一个在保留命名空间 portal 里的特权令牌。relay 起来之后，导出管理 secret，签发一个：

export WANCTL_ADMIN_SECRET='<value from selfhost/.env>'
curl -fsS https://wanctl-relay.z10.dev/admin/tokens/issue \
  -H "X-Admin-Secret: $WANCTL_ADMIN_SECRET" \
  -H 'Content-Type: application/json' \
  --data '{"namespace":"portal","label":"self-hosted portal","days":0}'

把返回的 wanctl_... 值填进 selfhost/.env 的 WANCTL_PORTAL_TOKEN，然后让它生效：

docker compose up -d portal

可选：打开托管的 MCP 端点

起不了本地 wanctl 进程的 AI 宿主——网页版聊天、云端 agent 运行器——可以改用 HTTP 连 relay 内置的 MCP server。给 relay 一个种子，然后重建它：

openssl rand -hex 32   # paste the value into WANCTL_MCP_SEED in selfhost/.env
docker compose up -d --no-deps relay

relay 启动时会打印 MCP server enabled at /mcp，并开始提供 https://wanctl-relay.z10.dev/mcp。如果你的边缘代理已经占掉了 /mcp 前缀，就让宿主改填 https://wanctl-relay.z10.dev/wanctl-mcp：它是同一个 handler、同一批会话的别名，别的什么都不用改。每个 MCP 会话各自通过门户登录；让 AI 通过 MCP 连上来是写给登录的人看的那一篇。种子要稳定—— 换掉它等于把所有会话登出，所有存下来的 rebind 凭证一起作废。

托管会话的设备信任只存在内存里，所以它第一次连上某台设备时会停在一个自己无法确认的指纹上：这个会话能列出设备，但什么都跑不了。打开那个开关的代价，就是承认你自己的 relay 不是它要防的那个攻击者；不打开，这个端点就只能读：

# selfhost/.env, then: docker compose up -d --no-deps relay
WANCTL_MCP_ALLOW_UNSAFE_TRUST_SERVER=1

可选：让网页 AI 用 OAuth 登录

每调用一次工具就新开一个 MCP 会话的连接器——ChatGPT 就是——永远拿不住一份按会话存的登录。这类客户端改用 OAuth 2.1 的 bearer 认人，而只要 relay 同时备齐数据库、公网 origin 和门户三样，它自己就会把这条路打开：

# selfhost/.env, then: docker compose up -d --no-deps relay
WANCTL_PUBLIC_ORIGIN=https://wanctl-relay.z10.dev
WANCTL_PORTAL=https://wanctl.z10.dev

relay 会打印 MCP OAuth enabled，并开始提供 /.well-known/oauth-protected-resource 和 /.well-known/oauth-authorization-server；人真正看见的那张同意页由门户在 /oauth/authorize 上提供。客户端是自己注册的，注册本身不给任何权限——权限从一个已登录的人点头那一刻才开始，每次点头都会以客户端名字出现在他的令牌列表里，也在那里吊销。不带 bearer 的客户端什么都不变，照旧按会话登录。这需要迁移 010 建两张表，所以跟任何一次结构变更一样，升上这个版本前先备份数据库。

可选：给设备提供签名过的发布包

打开发布分发之后，设备一行就能装上，之后用 wanctl update 升级，两者都对着项目的发布签名验过。从 GitHub Releases 把某个版本的产物下载到 selfhost/dist/，然后告诉 relay 该信任哪把签名密钥——这个信任锚是构建时编进去的，刻意不做成运行时配置：

gh release download v0.2.0 --repo Daily-AC/wanctl --dir dist   # or curl each asset
# Derive the raw base64 key the relay build expects from the release's PEM:
openssl pkey -pubin -in dist/release-public.pem -outform DER | tail -c 32 | base64

把那个值填成 .env 里的 WANCTL_RELEASE_PUBLIC_KEYS，然后重新构建并重启 relay：

docker compose build relay && docker compose up -d relay

relay 的日志会从 release distribution disabled 变成开始提供 /dl/*，一台连不上 GitHub 的设备就能从这个镜像装：

curl -fsSL https://wanctl-relay.z10.dev/install.sh | sh

irm https://wanctl-relay.z10.dev/install.ps1 | iex

什么都不用导出：relay 会把它自己提供的安装脚本改写成指向它自己的 /dl—— 因为能从这台 relay 取到脚本的人就能到达这台 relay，而这些人往往到不了脚本原本编译时指向的那个发布页。WANCTL_RELAY 和 WANCTL_DIST_BASE 仍然能覆盖它，从 GitHub 发布页取的那份副本则不受影响。这需要 RELAY_PUBLIC_ORIGIN （compose 文件把它作为 WANCTL_PUBLIC_ORIGIN 传给 relay）。

这样装上的二进制，wanctl update 仍然是对着构建时烤进去的那个发布页跑的。在一个到不了它的网络里，把它们一次性指向镜像：

wanctl config set release_base=https://wanctl-relay.z10.dev/dl

这个镜像是可选的：官方二进制和安装器在安装和 wanctl update 上都默认走项目的 GitHub 发布页，所以大多数部署根本不需要提供 /dl。

设备不用等人来通知。正在跑的 wanctl agent 会在启动一分钟后、之后每六小时，去读同一份签名清单，发现更新的版本就自己装：验签之后原地重启，pid 保持不变。有会话或后台任务在跑时它会跳过；二进制所在目录写不了时，它只记一行「请手动运行 sudo wanctl update」，不会尝试提权。某台设备想退出，在那台上跑 wanctl config set auto_update=off。发布页够不到而 relay 镜像配好了的时候，自动检查会像 wanctl update 一样退回镜像。

排障

GitHub 报 callback URL 错误。 OAuth App 的 callback 必须精确等于 PORTAL_PUBLIC_ORIGIN 加上 /auth/callback。检查协议、主机名、端口，以及 selfhost/.env 里有没有残留的示例值。

门户以 session-secret 错误退出。 WANCTL_SESSION_SECRET 是按字节算的，至少要 32 字节。openssl rand -hex 32 生成的那个 64 字符的值正合适。改完之后重建门户容器。

relay 连不上 DATABASE_URL。 它在开始服务之前会 ping Postgres，连接或内嵌 migration 失败就退出。Compose 随后会按 restart: unless-stopped 把它重启起来；去看 docker compose logs relay postgres，核对数据库凭据。不要在一个全新的数据库上关掉 migration。