On this page

Remote access status

GET/remote-access

Operation getRemoteAccessAuthBearer token

The 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

NameTypeDescription
refreshstring

One of 1, true

Responses

StatusDescriptionBody
200StatusRemoteAccessStatus
enabledrequiredboolean
staterequiredstring

paused: on, but this computer's networks are not allowed, so nothing listens

One of off, on, paused, no_address, env_bind, error

messagerequiredstring

The status line, e.g. "Listening on 192.168.1.20." or "Paused on Wi-Fi (192.168.1.0/24)."

problemrequiredstring | null
namerequiredstring
fingerprintrequiredstring | null

pattern: ^[A-Z2-7]{4}-[A-Z2-7]{4}$

portrequiredinteger
addressesrequiredarray<RemoteAddress>
8 fields of addresses
addressrequiredstring
familyrequiredstring

One of IPv4, IPv6

kindrequiredstring

One of lan, tailnet

ifacerequiredstring
networkIdrequiredstring | null

The network it is on (NetworkView.id); null when it cannot be identified yet

allowedrequiredboolean

The user allowed that network

listeningrequiredboolean
problemrequiredstring | null
urlsrequiredarray<RemoteUrl>
3 fields of urls
urlrequiredstring
kindrequiredstring

One of tailscale-https, tailnet, lan, mdns-name

encryptedrequiredboolean

TLS (tailscale serve) or WireGuard (tailnet); plain LAN http is not

hostNamesrequiredarray<string>
tailscalerequiredobject
4 fields of tailscale
staterequiredstring

One of absent, stopped, running

serverequiredstring

One of on, off, unknown

httpsUrlrequiredstring | null
serveCommandrequiredstring | null
mdnsrequiredobject
2 fields of mdns
announcingrequiredboolean
problemrequiredstring | null
firewallrequiredobject
3 fields of firewall
staterequiredstring

One of ok, blocked, unknown

messagerequiredstring
commandsrequiredarray<string>
devicesrequiredarray<RemoteDevice>
10 fields of devices
idrequiredstring

pattern: ^[a-z2-7]{10}$

labelrequiredstring
originrequiredstring

One of paired, token

createdAtrequiredstring

format: date-time

createdByrequiredstring

One of studio, cli

lastSeenAtrequiredstring | null

format: date-time

lastSeenAddressrequiredstring | null
connectedrequiredboolean

An open client session or stream, or a request in the last 60 s

connectionsrequiredinteger

range: ≥ 0

sessionsrequiredinteger

range: ≥ 0

pairingrequiredPairingWindowView | null

The open pairing window. code is shown on this computer only.

8 fields of pairing
coderequiredstring

pattern: ^[0-9]{6}$

namerequiredstring

This computer's name, as GET /remote/hello shows it

fingerprintrequiredstring

pattern: ^[A-Z2-7]{4}-[A-Z2-7]{4}$

openedAtrequiredstring

format: date-time

expiresAtrequiredstring

format: date-time

attemptsLeftrequiredinteger

Wrong codes left in this window, all sources together; 0 closes it

range: 0–20

lockedSourcesrequiredinteger

Sources locked out of this window after 5 wrong codes each (the window stays open)

range: ≥ 0

claimrequiredPairingClaimView | null

A correct claim waiting for the owner's Allow / Deny

7 fields of claim
claimIdrequiredstring
deviceNamerequiredstring
clientKindrequiredstring

One of studio, cli

addressrequiredstring
viarequiredstring

One of lan, tailnet, proxy

tailnetLoginrequiredstring | null
atrequiredstring

format: date-time

networksrequiredarray<NetworkView>

The networks this computer is on now (also while off)

7 fields of networks
idrequiredstring | null

Null: cannot be identified yet (no gateway MAC); it cannot be allowed

pattern: ^(lan|tailnet)-[0-9a-f]{16}$

kindrequiredstring

One of lan, tailnet

labelrequiredstring
allowedrequiredboolean
osCategoryrequiredstring

Windows' category (shown as a warning only; never consent); unknown elsewhere

One of private, public, unknown

ifacesrequiredarray<string>
addressesrequiredarray<string>
allowedNetworksrequiredarray<AllowedNetwork>

The networks the user allowed (remote-access.json; the mesh's LAN mode uses the same list)

4 fields of allowedNetworks
idrequiredstring

pattern: ^(lan|tailnet)-[0-9a-f]{16}$

kindrequiredstring

One of lan, tailnet

labelrequiredstring
addedAtrequiredstring

format: date-time

meshLanrequiredboolean

The daemon's mesh listens on the LAN (it needs the same consent)

Errors 401 · 403 · 503
401Missing or wrong bearer token (unauthorized)
403Not 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
503Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable)

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/remote-access" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Turn remote access on or off, rename

PUT/remote-access

Operation updateRemoteAccessAuthBearer token

Live: 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

FieldTypeDescription
enabledboolean

On: opens listeners on private and Tailscale addresses (no daemon restart); off: closes them, ends device sessions and connections. Devices are kept.

namestring

The computer name other computers see: the runtime alias (settings runtimeAlias), else the host name

length: 1–63

Responses

StatusDescriptionBody
200Status after the changeRemoteAccessStatus

Fields as in RemoteAccessStatus above.

Errors 400 · 401 · 403 · 409 · 503
400Empty body, wrong types or a bad name (bad_request)
401Missing or wrong bearer token (unauthorized)
403Not 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
409env_bind: ADF_DAEMON_HOST binds the daemon to the network itself
503Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable)

Error bodies use the error format.

Example

Request
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

POST/remote-access/networks

Operation allowRemoteNetworkAuthBearer token

The 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

FieldTypeDescription
idrequiredstring

A networks[].id from GET /remote-access

pattern: ^(lan|tailnet)-[0-9a-f]{16}$

Responses

StatusDescriptionBody
200Status after the changeRemoteAccessStatus

Fields as in RemoteAccessStatus above.

Errors 400 · 401 · 403 · 404
400No or malformed id (bad_request)
401Missing or wrong bearer token (unauthorized)
403Not 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
404Not a network this computer is on now (network_not_found)

Error bodies use the error format.

Example

Request
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

DELETE/remote-access/networks/{id}

Operation forgetRemoteNetworkAuthBearer token

Removes the consent; the listeners on that network (remote access and the mesh's LAN mode) close now. Local-only.

Path parameters

NameTypeDescription
idrequiredstring

Allowed network id

Responses

StatusDescriptionBody
200Status after the changeRemoteAccessStatus

Fields as in RemoteAccessStatus above.

Errors 400 · 401 · 403 · 404
400Not a network id (bad_request)
401Missing or wrong bearer token (unauthorized)
403Not 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
404Not an allowed network (network_not_found)

Error bodies use the error format.

Example

Request
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)

POST/remote-access/devices

Operation createRemoteDeviceAuthBearer token

Mints 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

FieldTypeDescription
labelrequiredstring

length: 1–64

Responses

StatusDescriptionBody
201The device and its tokenRemoteDeviceCreated
devicerequiredobject

A computer with a device token. The token itself is never returned after creation.

10 fields of device · RemoteDevice
idrequiredstring

pattern: ^[a-z2-7]{10}$

labelrequiredstring
originrequiredstring

One of paired, token

createdAtrequiredstring

format: date-time

createdByrequiredstring

One of studio, cli

lastSeenAtrequiredstring | null

format: date-time

lastSeenAddressrequiredstring | null
connectedrequiredboolean

An open client session or stream, or a request in the last 60 s

connectionsrequiredinteger

range: ≥ 0

sessionsrequiredinteger

range: ≥ 0

tokenrequiredstring

Shown once: only its hash is stored. As powerful as the owner seed phrase.

pattern: ^adfd_[a-z2-7]{10}_[A-Za-z0-9_-]{43}$

Errors 400 · 401 · 403 · 503
400Bad label (bad_request)
401Missing or wrong bearer token (unauthorized)
403Not 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
503Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable)

Error bodies use the error format.

Example

Request
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

DELETE/remote-access/devices/{id}

Operation revokeRemoteDeviceAuthBearer token

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

NameTypeDescription
idrequiredstring

Device id

Responses

StatusDescriptionBody
200The revoked device and what was closedRemoteDeviceRevoked
devicerequiredobject

A computer with a device token. The token itself is never returned after creation.

Fields as in RemoteDevice above.

closedSessionsrequiredinteger

range: ≥ 0

closedConnectionsrequiredinteger

range: ≥ 0

Errors 401 · 403 · 404 · 503
401Missing or wrong bearer token (unauthorized)
403Not 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
404Unknown device (device_not_found)
503Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable)

Error bodies use the error format.

Example

Request
curl -X DELETE "http://127.0.0.1:7385/remote-access/devices/ID" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Open the pairing window

POST/remote-access/pairing

Operation openPairingAuthBearer token

A 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

StatusDescriptionBody
201The window, with its codePairingWindowView
coderequiredstring

pattern: ^[0-9]{6}$

namerequiredstring

This computer's name, as GET /remote/hello shows it

fingerprintrequiredstring

pattern: ^[A-Z2-7]{4}-[A-Z2-7]{4}$

openedAtrequiredstring

format: date-time

expiresAtrequiredstring

format: date-time

attemptsLeftrequiredinteger

Wrong codes left in this window, all sources together; 0 closes it

range: 0–20

lockedSourcesrequiredinteger

Sources locked out of this window after 5 wrong codes each (the window stays open)

range: ≥ 0

claimrequiredPairingClaimView | null

A correct claim waiting for the owner's Allow / Deny

7 fields of claim
claimIdrequiredstring
deviceNamerequiredstring
clientKindrequiredstring

One of studio, cli

addressrequiredstring
viarequiredstring

One of lan, tailnet, proxy

tailnetLoginrequiredstring | null
atrequiredstring

format: date-time

Errors 401 · 403 · 409 · 503
401Missing or wrong bearer token (unauthorized)
403Not 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
409Remote access is off (remote_access_off)
503Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable)

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/remote-access/pairing" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Close the pairing window

DELETE/remote-access/pairing

Operation closePairingAuthBearer token

Discards the code and any pending claim.

Responses

StatusDescriptionBody
204Closed (or none was open)
Errors 401 · 403 · 503
401Missing or wrong bearer token (unauthorized)
403Not 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
503Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable)

Error bodies use the error format.

Example

Request
curl -X DELETE "http://127.0.0.1:7385/remote-access/pairing" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Allow or deny a pairing request

POST/remote-access/pairing/claims/{claimId}

Operation decidePairingClaimAuthBearer token

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

NameTypeDescription
claimIdrequiredstring

Claim id (PairingClaimView)

Request bodyapplication/json · PairingDecisionInput · required

FieldTypeDescription
allowrequiredboolean

Responses

StatusDescriptionBody
200The decisionPairingDecision · object | object
Option 1object
2 fields of Option 1
staterequiredstring

Value approved

devicerequiredobject

A computer with a device token. The token itself is never returned after creation.

Fields as in RemoteDevice above.

Option 2object
1 field of Option 2
staterequiredstring

Value denied

Errors 400 · 401 · 403 · 404 · 409 · 503
400allow is not a boolean
401Missing or wrong bearer token (unauthorized)
403Not 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
404No such pending claim (claim_not_found)
409Already decided (claim_decided)
503Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable)

Error bodies use the error format.

Example

Request
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

POST/remote-access/tailscale-serve

Operation setTailscaleServeAuthBearer token

Runs 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

FieldTypeDescription
enabledrequiredboolean

Responses

StatusDescriptionBody
200Tailscale state and the command outputTailscaleServeResult
tailscalerequiredobject
4 fields of tailscale
staterequiredstring

One of absent, stopped, running

serverequiredstring

One of on, off, unknown

httpsUrlrequiredstring | null
serveCommandrequiredstring | null
outputrequiredstring
Errors 400 · 401 · 403 · 502 · 503
400enabled is not a boolean
401Missing or wrong bearer token (unauthorized)
403Not 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
502The tailscale command failed (tailscale_failed, with output and command)
503Remote access is not configured on this daemon (unavailable), or daemon-devices.json cannot be read (devices_unreadable)

Error bodies use the error format.

Example

Request
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)

GET/remote/hello

Operation remoteHelloAuthNone

The 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

NameTypeDescription
noncestring

32 random bytes, base64url (43 characters), new for each hello.

pattern: ^[A-Za-z0-9_-]{43}$

devicestring

The device id of the token the client holds (adfd_<id>_…).

pattern: ^[a-z2-7]{10}$

originstring

The origin the client dialed (scheme, host, port), as it goes into the proof.

length: ≤ 300

Responses

StatusDescriptionBody
200Name, fingerprint, pairing open; with the proof query, whether the device is known and the proofRemoteHello
vrequirednumber

Value 1

namerequiredstring
fingerprintrequiredstring

pattern: ^[A-Z2-7]{4}-[A-Z2-7]{4}$

pairingOpenrequiredboolean
clientApiVersionrequiredinteger
helloProofnumber

This daemon answers the authenticated hello. Absent: an older ADF, which clients refuse before they send a saved token or pair.

Value 1

devicestring

Only with nonce, device and origin: whether this daemon holds the device's record (revoked: removed in the last 30 days).

One of known, unknown, revoked

proofstring | null

Only with nonce, device and origin: base64url(HMAC-SHA256(key = SHA-256 of the device secret, message = "adf-remote-hello-v1", nonce, fingerprint, origin and device joined by newlines)); null unless device is known and origin is where this request reached the daemon.

Errors 400 · 403 · 404 · 429
400nonce, device and origin are not all present and well formed (bad_request)
403The 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
404Remote access is off (remote_access_off)
429Rate limited (rate_limited, Retry-After)

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/remote/hello"

Claim pairing with the host's code (no token)

POST/pair/claim

Operation claimPairingAuthNone

A 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

FieldTypeDescription
coderequiredstring

pattern: ^[0-9]{6}$

deviceNamerequiredstring

Becomes the device label; control and bidi characters are refused

length: 1–64

clientKindrequiredstring

One of studio, cli

Responses

StatusDescriptionBody
202Waiting for the ownerPairClaimAccepted
claimIdrequiredstring

The claim's id. The owner's clients see it (GET /remote-access); it does not collect the token

expiresAtrequiredstring

format: date-time

collectSecretrequiredstring

256-bit random, only in this answer: send it as X-ADF-Pair-Secret to collect the result (GET /pair/claims/{claimId})

Errors 400 · 403 · 404 · 409 · 429
400Bad code, device name or client kind (bad_request)
403Wrong code (wrong_code, with attemptsLeft: for this source and the window together), or the request guard (host_not_allowed, cross_origin)
404No open window (pairing_closed) or remote access is off (remote_access_off)
409Another claim waits for the owner (pairing_busy)
429Rate 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

Request
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)

GET/pair/claims/{claimId}

Operation pollPairingClaimAuthNone

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

NameTypeDescription
claimIdrequiredstring

Claim id (POST /pair/claim)

Query parameters

NameTypeDescription
waitinteger

range: 0–25

Header parameters

NameTypeDescription
X-ADF-Pair-Secretrequiredstring

The claim's collectSecret (POST /pair/claim). Compared in constant time; a missing or wrong one answers 404 claim_not_found, as an unknown claim does

Responses

StatusDescriptionBody
200pending, denied, or approved with the tokenPairClaimResult · object | object | object
Option 1object
1 field of Option 1
staterequiredstring

Value pending

Option 2object
1 field of Option 2
staterequiredstring

Value denied

Option 3object
4 fields of Option 3
staterequiredstring

Value approved

tokenrequiredstring

Shown once: only its hash is stored. As powerful as the owner seed phrase.

pattern: ^adfd_[a-z2-7]{10}_[A-Za-z0-9_-]{43}$

devicerequiredobject
2 fields of device
idrequiredstring
labelrequiredstring
daemonrequiredobject
3 fields of daemon
namerequiredstring
fingerprintrequiredstring
urlsrequiredarray<RemoteUrl>
3 fields of urls
urlrequiredstring
kindrequiredstring

One of tailscale-https, tailnet, lan, mdns-name

encryptedrequiredboolean

TLS (tailscale serve) or WireGuard (tailnet); plain LAN http is not

Errors 400 · 403 · 404
400wait out of range
403The 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
404Unknown, 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

Request
curl "http://127.0.0.1:7385/pair/claims/CLAIM_ID"