wanctl — Architecture

Control another device across the public internet from a terminal (or an AI agent's shell), over an end-to-end-encrypted, relayed channel. A web portal issues tokens and manages sharing; a Postgres-backed relay authenticates and brokers; devices enforce a local, approval-based permission policy.

Devices use persistent UUIDs for routing and associations, independently of their display names and TLS fingerprints. See device identity and upgrading.

controller (you/agent) ──┐                            ┌── device (wanctl agent)
   wanctl exec/push/logs  │   relay (public broker)   │     policy engine + approval
                          ├── byte-pipe + registry ───┤     JSONL event log
                          │   token auth + ACL + audit│
   E2E mutual-TLS ════════╪════════ over the pipe ════╪════ (relay sees only ciphertext)
                          │                           │
   portal (web, SSO) ─────┘  issues tokens, ACL ──────┘  (thin proxy to relay /admin/*)

Components

One Go binary; the role is chosen at runtime:

wanctl relay — the public broker. Postgres-backed (DATABASE_URL): hashed-token resolve, cross-namespace ACL, metadata audit, device registry. Serves the signed-manifest /dl/<artifact> distribution and the /skills document for AI controllers. Falls back to a static WANCTL_TOKENS env map when no database is attached. The secret-gated admin API /admin/* backs the portal.
wanctl portal — the web app. No database of its own: a thin proxy to the relay's /admin/* using a shared WANCTL_ADMIN_SECRET, scoped to the namespace resolved from the authenticated identity. The portal is also a first-class controller: it holds its own Ed25519 identity and a privileged dial token, and drives a live device console over the same E2E tunnel.
wanctl agent — the controlled device. Outbound-only to the relay; each session does a server-side TLS handshake, TOFU authorization, then policy-gated exec/file serving. Writes a JSONL event log.
wanctl exec|push|pull|peers|id|trust|rules|logs|net|docs|update — controller commands.

Package map: transport (Ed25519 identity, mutual TLS, TOFU), protocol (framed wire format), wsconn (WebSocket↔net.Conn), httpconn (HTTP long-poll↔net.Conn — the proxy-agnostic carrier), relay (broker + http transport + pgstore + admin + dist), agent, client, server (shell+files), policy (rules+approver), console (transport-neutral approval queue), portal, eventlog, sessionauth (relay-issued capability grants).

The opt-in WebFetch adapter adds URL-only AI clients. Its owner approval and short-lived device scopes live in the existing portal/token store; the adapter is an ordinary E2E controller with a distinct identity per grant. Unlike the opaque broker, this explicitly enabled controller component sees the plaintext it sends and receives. Device-local action policy remains the authority. Delegated metadata is preserved across admission and both carriers; namespace-only legacy paths refuse delegated credentials.

Transports

Two carriers speak the same TLS + framed protocol:

WebSocket (wsconn) — for deployments whose ingress preserves WebSocket upgrades (direct exposure, or a reverse proxy configured for upgrades).
HTTP long-poll (httpconn) — the proxy-agnostic default: WANCTL_TRANSPORT=http. Up-channel is one POST per write; down-channel is a long-poll GET that returns available bytes / 204 retry / 410 EOF. Every response is finite, which survives edges that strip Connection: Upgrade and buffer streaming responses (a plain streaming GET deadlocks behind such an edge — this was measured, not theorized).

Measured on an 8 MB payload, WebSocket buys 4–5× push and ~2× pull throughput; interactive exec latency and line-by-line streaming spacing are equivalent on long-poll. Pick WebSocket for file-transfer-heavy fleets, long-poll for maximum ingress compatibility.

Trust model

Three independent layers; compromising one does not collapse the others:

Relay admission — a bearer token (wanctl_<40 hex>) maps to a namespace. Tokens are stored as SHA-256 hashes, may carry labels and expiry, and are revocable. The relay authorizes dials by namespace and ACL; it cannot see inside sessions.
End-to-end identity — controller and device each hold a self-signed Ed25519 certificate; sessions run mutual TLS 1.3 over the relayed pipe with fingerprint pinning (TOFU on both sides). A relay or database compromise leaks metadata only. Devices additionally refuse pairing prompts from controllers that do not identify themselves with a label.
Device-local policy — a rules engine gated by human approval (Claude-Code-style: yes / always-this-dir / always-global / no). Command rules match a single simple command only — anything with shell operators, substitutions, or redirects requires an exact match. File rules bind the actual opens to a directory root (no symlink escape). bypass mode auto-allows but still logs; elevated exec is its own class, never covered by an ordinary exec rule, and covered by bypass only on a device whose elevation channel is switched on as well — two separate opt-ins, both off by default. Headless with no approver subscribed means deny, not hang.

Cross-namespace sharing is a relay-side ACL grant (owner, device, grantee, manage). A share inherits the owner's use of the device: the relay stamps a grantee's session with UseCapabilities — exec, read, write, logs — over the authenticated agent control channel. The acl.perms column still exists and is written as the constant full, but nothing reads it (ADR 0007). A controlled device runs one agent bound to one account, so sharing is how a machine gets a second user; a permission matrix here would be a second, weaker model layered over the device's own, and it is the device's model that decides each request.

What constrains a grantee is therefore the device, not the grant. Its single mode and rule set apply to everyone: left on per-request approval, the owner answers for the grantee's commands; put into bypass, the grantee is bypassed too, elevated exec included if the device's elevation channel is on.

Management — the device console: approvals, rules, mode, trusted controllers — is the one thing a share varies, through acl.manage (migration 008), off unless the owner turns it on. It adds Console to that grantee's sessions and opens the portal's console for them. Two independent checks still guard it: the relay's switch says whether the owner agreed, and the device's own portal_admins set says which controller identity may act, so a grantee's own controller cannot administer the device directly even with the switch on. Unbinding, renaming, revoking a share, and the owner's notification settings are never granted.

/peers reports the grantee's own online devices under devices, unchanged, and the devices granted to them under shared, each with its owner namespace, route, label and online state — a grantee has no other way to learn the owner namespace a --target needs. A --target with no namespace resolves in the caller's own namespace first and then, if exactly one grant matches by route, name or alias, against the shared devices; a label two owners both use is refused rather than guessed. A refusal names the target only when it was asked for in the caller's own namespace; a target in a namespace the caller holds no grant on gets a bare forbidden, which reveals nothing about what is there.

Remote device console

The portal opens a live console to a device over the E2E tunnel: pending approvals, rules, mode, and the activity log, pushed in real time (KindApprovalNotif carries the full console state). Approval decisions from a local TTY and from the portal feed one queue; first answer wins. The device pre-trusts portal identities through an explicit portal_admins set, seeded at enrollment and manageable with wanctl portal-admins add|list|remove (removing the last one is refused). Rotating a portal identity is an overlap migration: seed old+new, deploy, verify, then remove old.

Because the platform edge may buffer streams, the portal's browser-facing event channel is a 25-second long-poll rather than SSE.

Server logs

Relay and portal tee process logs to a bounded in-memory ring (2,000 lines / 2 MiB) and expose the secret-gated GET /admin/logs. The portal serves its own ring and proxies the relay's, so it is the single entry point:

WANCTL_ADMIN_SECRET=... wanctl logs --service portal
WANCTL_ADMIN_SECRET=... wanctl logs --service relay --since 30m --grep <term>

Both services redact token/secret/password/API-key labelled values, bearer credentials, and base64-like strings ≥ 32 chars before applying grep, so a secret passed as a grep term cannot confirm its own presence. --follow is deliberately unsupported; the command errors instead of pretending to stream.

Release distribution

/dl is an allowlist, not a directory listing: the relay serves exactly the artifacts named by an offline-signed manifest (Ed25519), verified again on every read; anything else 404s. Installers are the trust-bootstrap exception — they are served unsigned by necessity, so prefer fetching them from the project's release page for machines that matter, and compare SHA-256 out-of-band. Install scripts verify an RSA signature instead of Ed25519 because a stock macOS LibreSSL and PowerShell 5.1 cannot verify Ed25519 — see docs/release-signing.md.

wanctl update verifies the manifest signature, swaps the binary, and — on platforms where a supervisor may own the running agent under another account — checks whether it can actually terminate the old process instead of reporting success while the old version keeps serving. After any upgrade, trust the running process's start time against the binary's mtime, not the version on disk.

Satellite relays

A relay without a database can resolve tokens against the main relay (WANCTL_UPSTREAM_RELAY + WANCTL_ADMIN_SECRET, 5-minute cache), so portal-issued tokens work on every relay without sharing the DB. That is how a self-hoster gets intranet latency: run a relay inside the network and point the devices and controllers there with wanctl config set relay=…. A ws:// relay is acceptable only inside an encrypted overlay (WireGuard or similar); otherwise use wss://.

Field notes (hard-won, don't relearn)

PaaS edges lie twice: the same edge that strips WebSocket upgrades will also buffer streaming responses and ignore X-Accel-Buffering. Long-poll (every response finite) is the shape that survives both.
/healthz may be shadowed by a platform edge that answers it with its own JSON; probe a real application route to test reachability.
When a platform hides a secret (masked DATABASE_URL, write-only env editors), change the architecture instead of fishing for it — the portal-as-proxy design exists because the portal could not be given the DSN.
The SSO identity header is an assertion from the proxy. The proxy must strip any client-supplied value for that header; the app cannot authenticate it by itself.
Detaching a process over ssh: setsid CMD & exit 0 sometimes dies. Use nohup setsid CMD >log 2>&1 </dev/null & disown.
Passwordless sudo changes installer semantics: a root-owned /usr/local/bin/wanctl from an earlier sudo install makes a later non-sudo reinstall silently fall back to ~/.local/bin. Pin with WANCTL_BIN.
A retry loop that logs nothing produces the least debuggable failure there is. The agent's poll loop logs the first failure, then ~one per minute, then the recovery. Apply the same rule to any loop that retries forever.
A "verified on the device" claim is only worth the invocation form it used. Verify a new platform by running the published installer and then the bare command off PATH — not a hand-copied binary.
Android breaks four Unix assumptions (resolver, HOME, /bin/sh, traversal permissions) and Termux breaks two more (linker argv duplication, no exec from an app's private dir). The full account, including why the APK's lib/<abi>/ directory is the one place an app may exec from, lives in docs/android.md.

Local smoke test (no external services)

go build -o /tmp/wanctl .
WANCTL_TOKENS="tk1:teamA" /tmp/wanctl relay --addr :18080 &
WANCTL_CONFIG_DIR=/tmp/wc-agent /tmp/wanctl agent --relay ws://127.0.0.1:18080 --token tk1 --name lab-pc --yes &
WANCTL_CONFIG_DIR=/tmp/wc-ctl WANCTL_RELAY=ws://127.0.0.1:18080 WANCTL_TOKEN=tk1 /tmp/wanctl peers
WANCTL_CONFIG_DIR=/tmp/wc-ctl WANCTL_RELAY=ws://127.0.0.1:18080 WANCTL_TOKEN=tk1 /tmp/wanctl exec --target lab-pc "echo ok"

wanctl — 架构

从一个终端（或者一个 AI agent 的 shell）跨公网控制另一台设备，走的是一条端到端加密、由 relay 转发的通道。网页门户签发令牌、管理共享；由 Postgres 支撑的 relay 负责认证和撮合；设备本地执行一套基于审批的权限策略。

设备用一个长期不变的 UUID 做路由和关联，与它的显示名、TLS 指纹都无关。见设备身份与升级。

controller (you/agent) ──┐                            ┌── device (wanctl agent)
   wanctl exec/push/logs  │   relay (public broker)   │     policy engine + approval
                          ├── byte-pipe + registry ───┤     JSONL event log
                          │   token auth + ACL + audit│
   E2E mutual-TLS ════════╪════════ over the pipe ════╪════ (relay sees only ciphertext)
                          │                           │
   portal (web, SSO) ─────┘  issues tokens, ACL ──────┘  (thin proxy to relay /admin/*)

组成

一个 Go 二进制，角色在运行时决定：

wanctl relay —— 公网撮合方。由 Postgres 支撑（DATABASE_URL）：令牌哈希解析、跨命名空间 ACL、元数据审计、设备注册表。同时提供由签名清单约束的 /dl/<artifact> 分发，以及给 AI 控制端读的 /skills 文档。没有接数据库时退回到静态的 WANCTL_TOKENS 环境变量映射。受 secret 保护的管理接口 /admin/* 是门户的后端。
wanctl portal —— 网页应用。它自己没有数据库：它是 relay /admin/* 的一层薄代理，用共享的 WANCTL_ADMIN_SECRET 通信，作用域收在已认证身份所解析出的那个命名空间里。门户同时也是一等的控制端：它持有自己的 Ed25519 身份和一个特权拨号令牌，通过同一条端到端隧道驱动实时设备控制台。
wanctl agent —— 被控设备。只向 relay 发起出站连接；每个会话先做一次服务端 TLS 握手，再做 TOFU 授权，然后才是受策略约束的命令执行与文件服务。它写一份 JSONL 事件日志。
wanctl exec|push|pull|peers|id|trust|rules|logs|net|docs|update —— 控制端命令。

包结构：transport（Ed25519 身份、双向 TLS、TOFU）、protocol（分帧的线上格式）、 wsconn（WebSocket↔net.Conn）、httpconn（HTTP 长轮询↔net.Conn，那个与代理无关的载体）、 relay（撮合 + http 传输 + pgstore + admin + dist）、agent、client、 server（shell + 文件）、policy（规则 + 审批者）、console（与传输无关的审批队列）、 portal、eventlog、sessionauth（relay 签发的能力授予）。

可选的 WebFetch 接入层支持只会读取 URL 的网页 AI。申请、审批、设备范围、过期和吊销使用现有门户与 Token 存储；适配器以每份授权独立的控制端身份连接设备。这个主动启用的控制端组件能看到自己收发的指令和结果，普通 broker 仍然只转发加密字节。操作权限仍由设备决定；委托凭证不会在旧的 namespace-only 接口中被降级为账号全权凭证。

传输层

两种载体说的是同一套 TLS + 分帧协议：

WebSocket（wsconn）—— 给那些入口保留 WebSocket 升级的部署（直接暴露，或者反向代理配好了升级）。
HTTP 长轮询（httpconn）—— 与代理无关的默认项：WANCTL_TRANSPORT=http。上行是每次写一个 POST；下行是一个长轮询 GET，返回可读的字节 / 204 重试 / 410 EOF。每个响应都是有限的，这一点让它能穿过那些既剥掉 Connection: Upgrade 又缓冲流式响应的边缘（普通的流式 GET 在这种边缘后面会直接死锁——这是实测出来的，不是推理出来的）。

在 8 MB 负载上实测，WebSocket 的 push 吞吐是 4~5 倍、pull 约 2 倍；交互式 exec 的时延和逐行流式输出的间隔在长轮询上是等价的。传文件为主的机群选 WebSocket，要最大入口兼容性就选长轮询。

信任模型

三层彼此独立，攻破一层不会让其余两层跟着塌：

relay 准入 —— 一个 bearer 令牌（wanctl_<40 hex>）映射到一个命名空间。令牌以 SHA-256 哈希存储，可以带标签和过期时间，随时可吊销。relay 按命名空间和 ACL 授权拨号；它看不见会话内部。
端到端身份 —— 控制端和设备各持一张自签的 Ed25519 证书；会话在被转发的管道之上跑双向 TLS 1.3，两端按指纹互相钉住（都是 TOFU）。relay 或数据库被攻破只泄漏元数据。设备还会拒绝那些不用标签表明自己是谁的控制端发来的配对请求。
设备本地策略 —— 一个由人工审批把关的规则引擎（Claude Code 那种形态：允许 / 这个目录一直允许 / 所有目录一直允许 / 拒绝）。命令规则只匹配单条简单命令—— 凡是带 shell 操作符、替换或重定向的，都要求精确匹配。文件规则把实际的打开操作绑定到一个目录根上（软链接逃不出去）。bypass 模式自动放行但照样记录；提权执行自成一类，永远不被普通 exec 规则覆盖，只有在设备的提权通道也开着时才被 bypass 覆盖——两个独立的开关，默认都是关的。无人值守、没有任何审批者订阅时的结果是拒绝，不是挂起。

跨命名空间共享是 relay 侧的一条 ACL 授予 (owner, device, grantee, manage)。一条共享继承主人对这台设备的使用权：relay 通过已认证的 agent 控制通道，给被共享方的会话盖上 UseCapabilities——exec、read、write、logs。acl.perms 这一列还在，写入常量 full，但没有任何地方再去读它（ADR 0007）。被控端只跑一个绑定到一个账号的 agent，共享就是一台机器拿到第二个使用者的方式；在这里再摆一张权限矩阵，等于在设备自己的权限模型之上叠一套更弱的第二模型，而真正决定每一次请求的是设备那一套。

所以约束被共享方的是设备，不是这条授予。设备只有一份模式和一份规则，对所有人生效：停在逐条确认，主人就要替对方的命令点头；开了 bypass，对方也跟着放行——设备的提权通道也开着的话，提权执行同样跟着放行。

管理权——设备控制台：审批、规则、模式、受信控制端——是一条共享唯一可变的那一项，由 acl.manage（migration 008）控制，主人不打开就是关的。打开后它给这个被共享方的会话补上 Console，门户也会为他打开设备控制台。守着它的仍然是两道互不依赖的检查： relay 这边的开关表示主人是否同意，设备那边的 portal_admins 集合表示哪个控制端身份可以动手——所以即使开关打开，被共享方自己的控制端也不能直接管理这台设备。解绑、改名、撤销共享，以及主人的通知设置，任何时候都不在共享范围内。

/peers 里 devices 依旧只是调用方自己的在线设备，含义不变；别人共享给他的设备另放在 shared 字段，带上主人 namespace、路由、标签和在线状态——否则被共享方根本无从知道 --target 需要的那个主人 namespace。不带 namespace 的 --target 先在调用方自己的 namespace 里解析，解析不到再去共享设备里找，按路由、名字或别名恰好命中一条才算数；两个主人用了同一个标签时直接拒绝，不去猜。拒绝信息只在目标问的是调用方自己的 namespace 时才说出目标名；问的是没有授权的 namespace 时只回一个光秃秃的 forbidden，不透露那边有没有这台设备。

远程设备控制台

门户通过端到端隧道给设备开一条实时控制台：待审批、规则、模式和活动日志，全部实时推送（KindApprovalNotif 带的是完整的控制台状态）。本地 TTY 上的审批决定和门户上的审批决定汇进同一个队列，先答的那个算数。设备通过一个显式的 portal_admins 集合预先信任门户身份，这个集合在接入时播种，用 wanctl portal-admins add|list|remove 管理（要删掉最后一个会被拒绝）。轮换门户身份是一次有重叠期的迁移：先把新旧一起播种，部署，核验，然后再删掉旧的。

因为平台边缘可能缓冲流，门户面向浏览器的事件通道用的是 25 秒长轮询，而不是 SSE。

服务端日志

relay 和门户把进程日志同时写进一个有界的内存环（2,000 行 / 2 MiB），并通过受 secret 保护的 GET /admin/logs 暴露出来。门户提供自己那份环，同时代理 relay 的那份，所以它是唯一的入口：

WANCTL_ADMIN_SECRET=... wanctl logs --service portal
WANCTL_ADMIN_SECRET=... wanctl logs --service relay --since 30m --grep <term>

两个服务都会在应用 grep 之前脱敏掉标着 token/secret/password/API-key 的值、 bearer 凭据，以及长度 ≥ 32 的类 base64 字符串——所以拿一个 secret 当 grep 关键词，是问不出它在不在里面的。--follow 是刻意不支持的；这个命令会直接报错，而不是假装自己在流式输出。

发布分发

/dl 是一份白名单，不是目录列表：relay 只提供离线签名清单（Ed25519）点名的那些产物，每次读取时再验一遍；其余一律 404。安装脚本是信任引导上的例外—— 它们不得不以未签名的形式提供，所以对要紧的机器，优先从项目的发布页去取，再带外比对 SHA-256。安装脚本验的是 RSA 签名而不是 Ed25519，因为原生的 macOS LibreSSL 和 PowerShell 5.1 验不了 Ed25519——见 docs/release-signing.md。

wanctl update 会验证清单签名、换掉二进制，并且——在那些可能由某个 supervisor 以另一个账户持有运行中 agent 的平台上——检查自己到底能不能真的终止旧进程，而不是在旧版本还在服务的时候报告成功。任何一次升级之后，去信运行进程的启动时间对上二进制的 mtime，别信磁盘上的版本号。

卫星 relay

没有数据库的 relay 可以把令牌拿到主 relay 去解析（WANCTL_UPSTREAM_RELAY + WANCTL_ADMIN_SECRET，5 分钟缓存），这样门户签发的令牌在每个 relay 上都能用，不必共享数据库。想要内网延迟就是这么做的：在内网里自己跑一个 relay，用 wanctl config set relay=… 把设备和控制端指过去。ws:// 的 relay 只有在加密覆盖网（WireGuard 之类）里面才可以接受；否则请用 wss://。

现场笔记（都是踩出来的，别再踩一遍）

PaaS 的边缘会骗你两次：剥掉 WebSocket 升级的那个边缘，同样会缓冲流式响应，并且无视 X-Accel-Buffering。长轮询（每个响应都有限）是两样都能扛过去的那个形状。
/healthz 可能被顶掉：平台边缘可能拿自己的 JSON 来回答它；要测可达性，去探一条真实的应用路由。
当平台把一个 secret 藏起来的时候（打码的 DATABASE_URL、只写不读的环境变量编辑器），改架构，别去捞它——门户即代理这个设计之所以存在，就是因为门户拿不到那个 DSN。
SSO 身份头是代理做出的一个断言。 代理必须剥掉客户端自己带的同名头；应用自己没法认证它。
通过 ssh 让进程脱离：setsid CMD & exit 0 有时候会死。用 nohup setsid CMD >log 2>&1 </dev/null & disown。
免密 sudo 会改变安装器的语义：早先某次 sudo 安装留下的、属主是 root 的 /usr/local/bin/wanctl，会让后来一次非 sudo 的重装静默退回到 ~/.local/bin。用 WANCTL_BIN 钉死它。
一个什么都不打日志的重试循环，是世上最难调的那种故障。 agent 的轮询循环会记下第一次失败，之后大约每分钟一条，然后记下恢复。任何一个会永远重试下去的循环，都照这条办。
一句「已在设备上验证过」，只值它当时用的那个调用形式。验证一个新平台，要跑真正发布出去的那个安装器，然后从 PATH 上敲裸命令—— 不是手工拷过去的一个二进制。
Android 打破了四条 Unix 假设（解析器、HOME、/bin/sh、目录穿越权限）， Termux 又多打破两条（linker 会重复 argv、不能从 app 私有目录执行）。完整的账，包括为什么 APK 的 lib/<abi>/ 目录是一个 app 唯一能执行的地方，都在 docs/android.md 里。

本地冒烟测试（不依赖任何外部服务）

go build -o /tmp/wanctl .
WANCTL_TOKENS="tk1:teamA" /tmp/wanctl relay --addr :18080 &
WANCTL_CONFIG_DIR=/tmp/wc-agent /tmp/wanctl agent --relay ws://127.0.0.1:18080 --token tk1 --name lab-pc --yes &
WANCTL_CONFIG_DIR=/tmp/wc-ctl WANCTL_RELAY=ws://127.0.0.1:18080 WANCTL_TOKEN=tk1 /tmp/wanctl peers
WANCTL_CONFIG_DIR=/tmp/wc-ctl WANCTL_RELAY=ws://127.0.0.1:18080 WANCTL_TOKEN=tk1 /tmp/wanctl exec --target lab-pc "echo ok"