Remote access
Other computers reach this daemon (docs/design/remote-access.md): the toggle, device tokens, pairing. Management routes answer this machine only: the install's token, a loopback caller without proxy headers, and the local proof (X-ADF-Local-Proof) in every mode; a device token gets 403 device_token_refused. /remote/hello and /pair/* need no token and answer 404 remote_access_off while remote access is off.
On this page
Remote access status
/remote-accessThe toggle, addresses (with the network category), URLs, Tailscale, mDNS, firewall, devices and the open pairing window (with its code). refresh=1 re-reads the network, Tailscale and the firewall first.
Query parameters
| Name | Type | Description |
|---|---|---|
refresh | string |
Responses
| Status | Description | Body | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Status | RemoteAccessStatus | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
urlsrequiredarray<RemoteUrl> | 3 fields of | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
urlrequired | string | |
kindrequired | string | |
encryptedrequired | boolean | TLS (tailscale serve) or WireGuard (tailnet); plain LAN http is not |
hostNamesrequiredtailscalerequired4 fields of tailscale
staterequired | string | |
serverequired | string | |
httpsUrlrequired | string | null | |
serveCommandrequired | string | null |
mdnsrequired2 fields of mdns
announcingrequired | boolean | |
problemrequired | string | null |
firewallrequired3 fields of firewall
staterequired | string | |
messagerequired | string | |
commandsrequired | array<string> |
devicesrequired10 fields of devices
idrequired | string | |
labelrequired | string | |
originrequired | string | |
createdAtrequired | string | |
createdByrequired | string | |
lastSeenAtrequired | string | null | |
lastSeenAddressrequired | string | null | |
connectedrequired | boolean | An open client session or stream, or a request in the last 60 s |
connectionsrequired | integer | |
sessionsrequired | integer |
pairingrequiredThe open pairing window. code is shown on this computer only.
8 fields of pairing
coderequired | string | ||||||||||||||||||||||
namerequired | string | This computer's name, as GET /remote/hello shows it | |||||||||||||||||||||
fingerprintrequired | string | ||||||||||||||||||||||
openedAtrequired | string | ||||||||||||||||||||||
expiresAtrequired | string | ||||||||||||||||||||||
attemptsLeftrequired | integer | Wrong codes left in this window, all sources together; 0 closes it | |||||||||||||||||||||
lockedSourcesrequired | integer | Sources locked out of this window after 5 wrong codes each (the window stays open) | |||||||||||||||||||||
claimrequired | PairingClaimView | null | A correct claim waiting for the owner's Allow / Deny | |||||||||||||||||||||
7 fields of | |||||||||||||||||||||||
claimIdrequired | string | |
deviceNamerequired | string | |
clientKindrequired | string | |
addressrequired | string | |
viarequired | string | |
tailnetLoginrequired | string | null | |
atrequired | string |
networksrequiredThe networks this computer is on now (also while off)
7 fields of networks
idrequired | string | null | Null: cannot be identified yet (no gateway MAC); it cannot be allowed |
kindrequired | string | |
labelrequired | string | |
allowedrequired | boolean | |
osCategoryrequired | string | Windows' category (shown as a warning only; never consent); unknown elsewhere |
ifacesrequired | array<string> | |
addressesrequired | array<string> |
allowedNetworksrequiredThe networks the user allowed (remote-access.json; the mesh's LAN mode uses the same list)
4 fields of allowedNetworks
idrequired | string | |
kindrequired | string | |
labelrequired | string | |
addedAtrequired | string |
meshLanrequiredThe daemon's mesh listens on the LAN (it needs the same consent)
Errors 401 · 403 · 503
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | Not this machine: a non-local caller or no local proof (loopback_only), a device token (device_token_refused), or the request guard (host_not_allowed, cross_origin)device_token_refused | |
| 503 | Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/remote-access" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Turn remote access on or off, rename
/remote-accessLive: no daemon restart. Turning on mints the daemon id (fingerprint); it listens only on networks the user allowed (POST /remote-access/networks). Turning off closes every remote listener, ends device sessions and connections, keeps the devices.
Request bodyapplication/json · RemoteAccessPatch · required
| Field | Type | Description |
|---|---|---|
enabled | boolean | On: opens listeners on private and Tailscale addresses (no daemon restart); off: closes them, ends device sessions and connections. Devices are kept. |
name | string | The computer name other computers see: the runtime alias (settings runtimeAlias), else the host name |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Status after the change | RemoteAccessStatus |
Fields as in RemoteAccessStatus above. | ||
Errors 400 · 401 · 403 · 409 · 503
| 400 | Empty body, wrong types or a bad name (bad_request) | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | Not this machine: a non-local caller or no local proof (loopback_only), a device token (device_token_refused), or the request guard (host_not_allowed, cross_origin)device_token_refused | |
| 409 | env_bind: ADF_DAEMON_HOST binds the daemon to the network itself | |
| 503 | Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable) |
Error bodies use the error format.
Example
curl -X PUT "http://127.0.0.1:7385/remote-access" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{}'Allow on this network
/remote-access/networksThe user's consent for a network this computer is on now (owner decision 2026-10-18 b): remote access and the mesh's LAN mode listen there from now on. Works while remote access is off. Local-only: a device token cannot allow a network.
Request bodyapplication/json · object · required
| Field | Type | Description |
|---|---|---|
idrequired | string | A |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Status after the change | RemoteAccessStatus |
Fields as in RemoteAccessStatus above. | ||
Errors 400 · 401 · 403 · 404
| 400 | No or malformed id (bad_request) | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | Not this machine: a non-local caller or no local proof (loopback_only), a device token (device_token_refused), or the request guard (host_not_allowed, cross_origin)device_token_refused | |
| 404 | Not a network this computer is on now (network_not_found) |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/remote-access/networks" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"id":"string"}'Remove an allowed network
/remote-access/networks/{id}Removes the consent; the listeners on that network (remote access and the mesh's LAN mode) close now. Local-only.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Allowed network id |
Responses
| Status | Description | Body |
|---|---|---|
| 200 | Status after the change | RemoteAccessStatus |
Fields as in RemoteAccessStatus above. | ||
Errors 400 · 401 · 403 · 404
| 400 | Not a network id (bad_request) | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | Not this machine: a non-local caller or no local proof (loopback_only), a device token (device_token_refused), or the request guard (host_not_allowed, cross_origin)device_token_refused | |
| 404 | Not an allowed network (network_not_found) |
Error bodies use the error format.
Example
curl -X DELETE "http://127.0.0.1:7385/remote-access/networks/ID" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Create a device token (copy-paste)
/remote-access/devicesMints a device token and returns it once; only its SHA-256 is stored (daemon-devices.json). The token is as powerful as the owner seed phrase.
Request bodyapplication/json · RemoteDeviceInput · required
| Field | Type | Description |
|---|---|---|
labelrequired | string |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 201 | The device and its token | RemoteDeviceCreated | |||||||||||||||||||||||||||||||||||||||
tokenrequiredstring | Shown once: only its hash is stored. As powerful as the owner seed phrase. | ||||||||||||||||||||||||||||||||||||||||
Errors 400 · 401 · 403 · 503
| 400 | Bad label (bad_request) | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | Not this machine: a non-local caller or no local proof (loopback_only), a device token (device_token_refused), or the request guard (host_not_allowed, cross_origin)device_token_refused | |
| 503 | Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable) |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/remote-access/devices" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"label":"string"}'Revoke a device
/remote-access/devices/{id}Removes the device (a 30-day tombstone answers its token with 401 device_revoked), ends its client sessions (their stream gets session.ended first) and destroys its connections, streams included.
Path parameters
| Name | Type | Description |
|---|---|---|
idrequired | string | Device id |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | The revoked device and what was closed | RemoteDeviceRevoked | |||||||||
| |||||||||||
Errors 401 · 403 · 404 · 503
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | Not this machine: a non-local caller or no local proof (loopback_only), a device token (device_token_refused), or the request guard (host_not_allowed, cross_origin)device_token_refused | |
| 404 | Unknown device (device_not_found) | |
| 503 | Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable) |
Error bodies use the error format.
Example
curl -X DELETE "http://127.0.0.1:7385/remote-access/devices/ID" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Open the pairing window
/remote-access/pairingA new 6-digit code for 120 s; replaces an open window. 5 wrong codes close it. The mDNS announcement shows pair=1 while it is open.
Responses
| Status | Description | Body | ||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 201 | The window, with its code | PairingWindowView | ||||||||||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||||||||||||
Errors 401 · 403 · 409 · 503
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | Not this machine: a non-local caller or no local proof (loopback_only), a device token (device_token_refused), or the request guard (host_not_allowed, cross_origin)device_token_refused | |
| 409 | Remote access is off (remote_access_off) | |
| 503 | Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable) |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/remote-access/pairing" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Close the pairing window
/remote-access/pairingDiscards the code and any pending claim.
Responses
| Status | Description | Body |
|---|---|---|
| 204 | Closed (or none was open) |
Errors 401 · 403 · 503
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | Not this machine: a non-local caller or no local proof (loopback_only), a device token (device_token_refused), or the request guard (host_not_allowed, cross_origin)device_token_refused | |
| 503 | Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable) |
Error bodies use the error format.
Example
curl -X DELETE "http://127.0.0.1:7385/remote-access/pairing" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN"Allow or deny a pairing request
/remote-access/pairing/claims/{claimId}The owner's answer after a correct code. Allow mints the device (origin paired) and keeps its token for the claimant's poll; the window closes either way.
Path parameters
| Name | Type | Description |
|---|---|---|
claimIdrequired | string | Claim id (PairingClaimView) |
Request bodyapplication/json · PairingDecisionInput · required
| Field | Type | Description |
|---|---|---|
allowrequired | boolean |
Responses
| Status | Description | Body | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | The decision | PairingDecision · object | object | |||||||||||||||||||||
Option 2object | 1 field of | ||||||||||||||||||||||
staterequired | string |
Errors 400 · 401 · 403 · 404 · 409 · 503
| 400 | allow is not a boolean | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | Not this machine: a non-local caller or no local proof (loopback_only), a device token (device_token_refused), or the request guard (host_not_allowed, cross_origin)device_token_refused | |
| 404 | No such pending claim (claim_not_found) | |
| 409 | Already decided (claim_decided) | |
| 503 | Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable) |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/remote-access/pairing/claims/CLAIM_ID" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"allow":true}'Turn https through tailscale serve on or off
/remote-access/tailscale-serveRuns tailscale serve --bg <port> (on) or removes the https:443 entry when it forwards to this daemon (off). Clients call it only after the owner confirmed the command.
Request bodyapplication/json · TailscaleServeInput · required
| Field | Type | Description |
|---|---|---|
enabledrequired | boolean |
Responses
| Status | Description | Body | |||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Tailscale state and the command output | TailscaleServeResult | |||||||||||||||||||||
outputrequiredstring | | ||||||||||||||||||||||
Errors 400 · 401 · 403 · 502 · 503
| 400 | enabled is not a boolean | |
| 401 | Missing or wrong bearer token (unauthorized) | |
| 403 | Not this machine: a non-local caller or no local proof (loopback_only), a device token (device_token_refused), or the request guard (host_not_allowed, cross_origin)device_token_refused | |
| 502 | The tailscale command failed (tailscale_failed, with output and command) | |
| 503 | Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable) |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/remote-access/tailscale-serve" \
-H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
-H "Content-Type: application/json" \
-d '{"enabled":true}'Who is this daemon (no token)
/remote/helloThe mDNS announcement's content, for clients that cannot hear mDNS (tailnet peers, a typed address). No secret. 30 per minute per source address. With nonce, device and origin (all three, or none) it is the authenticated hello (docs/design/remote-access.md §5.2.1): the answer proves this daemon holds that device's record, and a client sends a saved device token, or saves a pairing, only after checking the proof. The proof is made only for an origin this request reached the daemon at, judged by its socket (a remote listener: its local address and port, or one of this computer's names; the loopback listener: a loopback origin with no proxy between, the tailscale serve URL, or an ADF_DAEMON_ALLOWED_HOSTS name). An authenticated hello for a known device counts in its own limit: 120 per minute per source and device.
Query parameters
| Name | Type | Description |
|---|---|---|
nonce | string | 32 random bytes, base64url (43 characters), new for each hello. |
device | string | The device id of the token the client holds ( |
origin | string | The origin the client dialed (scheme, host, port), as it goes into the proof. |
Responses
| Status | Description | Body | ||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | Name, fingerprint, pairing open; with the proof query, whether the device is known and the proof | RemoteHello | ||||||||||||||||||||||||
| ||||||||||||||||||||||||||
Errors 400 · 403 · 404 · 429
| 400 | nonce, device and origin are not all present and well formed (bad_request) | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Remote access is off (remote_access_off) | |
| 429 | Rate limited (rate_limited, Retry-After) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/remote/hello"Claim pairing with the host's code (no token)
/pair/claimA correct code puts the claim before the owner (202); the token comes only after the owner allows it (GET /pair/claims/{claimId}, with the collect secret). Wrong codes are answered after 1 s; 5 from one source lock that source out of the window (429 until it closes, the owner is told), 20 in total close it. Per source: one claim per 2 s, 10 per 10 minutes. A source is the socket address (forwarded headers are never read), or the tailnet user behind tailscale serve.
Request bodyapplication/json · PairClaimRequest · required
| Field | Type | Description |
|---|---|---|
coderequired | string | |
deviceNamerequired | string | Becomes the device label; control and bidi characters are refused |
clientKindrequired | string |
Responses
| Status | Description | Body | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| 202 | Waiting for the owner | PairClaimAccepted | |||||||||
| |||||||||||
Errors 400 · 403 · 404 · 409 · 429
| 400 | Bad code, device name or client kind (bad_request) | |
| 403 | Wrong code (wrong_code, with attemptsLeft: for this source and the window together), or the request guard (host_not_allowed, cross_origin) | |
| 404 | No open window (pairing_closed) or remote access is off (remote_access_off) | |
| 409 | Another claim waits for the owner (pairing_busy) | |
| 429 | Rate limited, or this source is locked out of the window after 5 wrong codes (rate_limited, Retry-After) |
Error bodies use the error format.
Example
curl -X POST "http://127.0.0.1:7385/pair/claim" \
-H "Content-Type: application/json" \
-d '{"code":"string","deviceName":"string","clientKind":"studio"}'Collect the result of a claim (no token)
/pair/claims/{claimId}Long poll: waits up to wait seconds while pending. Needs the claim's collect secret (X-ADF-Pair-Secret); the claim id alone collects nothing. An approved result (with the device token) is delivered once, then the claim is gone (404). Cache-Control: no-store.
Path parameters
| Name | Type | Description |
|---|---|---|
claimIdrequired | string | Claim id (POST /pair/claim) |
Query parameters
| Name | Type | Description |
|---|---|---|
wait | integer |
Header parameters
| Name | Type | Description |
|---|---|---|
X-ADF-Pair-Secretrequired | string | The claim's collectSecret (POST /pair/claim). Compared in constant time; a missing or wrong one answers 404 |
Responses
| Status | Description | Body | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| 200 | pending, denied, or approved with the token | PairClaimResult · object | object | object | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
Option 2object | 1 field of | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
staterequired | string |
Option 34 fields of Option 3
staterequired | string | ||||||||||||||||||||||
tokenrequired | string | Shown once: only its hash is stored. As powerful as the owner seed phrase. | |||||||||||||||||||||
devicerequired | object | ||||||||||||||||||||||
2 fields of | |||||||||||||||||||||||
idrequired | string | |
labelrequired | string |
daemonrequired3 fields of daemon
namerequired | string | ||||||||||
fingerprintrequired | string | ||||||||||
urlsrequired | array<RemoteUrl> | ||||||||||
3 fields of | |||||||||||
urlrequired | string | |
kindrequired | string | |
encryptedrequired | boolean | TLS (tailscale serve) or WireGuard (tailnet); plain LAN http is not |
Errors 400 · 403 · 404
| 400 | wait out of range | |
| 403 | The request guard refused it: Host header not allowed (host_not_allowed, DNS-rebinding protection) or a browser cross-site request (cross_origin)host_not_allowedcross_origin | |
| 404 | Unknown, expired or collected claim, or a missing or wrong collect secret (claim_not_found), or remote access is off (remote_access_off) |
Error bodies use the error format.
Example
curl "http://127.0.0.1:7385/pair/claims/CLAIM_ID"