On this page

Network diagnostics (host, mesh, WebSockets, agents)

GET/network

Operation getNetworkDiagnosticsAuthBearer token

Responses

StatusDescriptionBody
200DiagnosticsNetworkDiagnostics
hostrequiredobject
2 fields of host · LanAddressInfo
hostnamerequiredstring
addressesrequiredarray<object>
4 fields of addresses
ifacerequiredstring
addressrequiredstring
familyrequiredstring

One of IPv4, IPv6

macrequiredstring
meshrequiredobject
4 fields of mesh
enabledSettingrequiredboolean
lanrequiredboolean
portrequiredinteger
statusrequiredMeshStatus | null
5 fields of status
meshEnabledrequiredboolean
meshServerRunningrequiredboolean
meshServerrequiredobject
5 fields of meshServer · MeshServerStatus
runningrequiredboolean
portrequiredinteger
hostrequiredstring
lanAddressesarray<string>

Non-loopback addresses listening now. LAN mode (host 0.0.0.0: the Network switch, or an agent with lan or public visibility) listens on private-network and Tailscale addresses of allowed networks only (remote-access.md §3.3, §3.3.1), never on a public address. MESH_HOST set: [MESH_HOST] unless it is loopback.

warningstring

Present while an agent with public visibility has no allowed network to listen on (it is reachable from this computer only, e.g. on a headless server with only a public address). It names MESH_HOST, which binds an address of the operator's choice.

agentsrequiredarray<MeshAgentStatus>
8 fields of agents
filePathrequiredstring
handlerequiredstring
didstring
agentIdstring
iconstring
staterequiredstring

Display (fleet-map) state of an agent

One of active, idle, hibernate, suspended, off

statusstring
modelstring
debugrequiredobject

Mesh manager internals (unstable)

websocketrequiredobject
3 fields of websocket
activeConnectionsrequiredinteger
inboundConnectionsrequiredinteger
outboundConnectionsrequiredinteger
agentsrequiredarray<object>
10 fields of agents
agentIdrequiredstring
handlestring
namerequiredstring
filePathrequiredstring | null
receiverequiredboolean
sendModerequiredstring | null
networkrequiredstring | null
wsConnectionsConfiguredrequiredinteger
servingRoutesrequiredinteger
publicServingEnabledrequiredboolean
Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
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

Error bodies use the error format.

Example

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

Network diagnostics (same as GET /network)

GET/runtime/network

Operation getRuntimeNetworkAuthBearer token

Responses

StatusDescriptionBody
200DiagnosticsNetworkDiagnostics

Fields as in NetworkDiagnostics above.

Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
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

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/runtime/network" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Live mesh status

GET/network/mesh

Operation getMeshStatusAuthBearer token

Responses

StatusDescriptionBody
200Mesh statusMeshStatus
meshEnabledrequiredboolean
meshServerRunningrequiredboolean
meshServerrequiredobject
5 fields of meshServer · MeshServerStatus
runningrequiredboolean
portrequiredinteger
hostrequiredstring
lanAddressesarray<string>

Non-loopback addresses listening now. LAN mode (host 0.0.0.0: the Network switch, or an agent with lan or public visibility) listens on private-network and Tailscale addresses of allowed networks only (remote-access.md §3.3, §3.3.1), never on a public address. MESH_HOST set: [MESH_HOST] unless it is loopback.

warningstring

Present while an agent with public visibility has no allowed network to listen on (it is reachable from this computer only, e.g. on a headless server with only a public address). It names MESH_HOST, which binds an address of the operator's choice.

agentsrequiredarray<MeshAgentStatus>
8 fields of agents
filePathrequiredstring
handlerequiredstring
didstring
agentIdstring
iconstring
staterequiredstring

Display (fleet-map) state of an agent

One of active, idle, hibernate, suspended, off

statusstring
modelstring
debugrequiredobject

Mesh manager internals (unstable)

Errors 401 · 403 · 503
401Missing or wrong bearer token (unauthorized)
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
503The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/network/mesh" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Enable mesh registration (persisted)

POST/network/mesh/enable

Operation enableMeshAuthBearer token

Persists meshEnabled: true and re-registers the loaded agents. No body. With persist=0 the setting is left as it is.

Query parameters

NameTypeDescription
persiststring

0 or false: change the live mesh only and leave meshEnabled as it is (Studio's Mesh switch; its Autostart switch writes meshEnabled). Default 1.

One of 1, 0, true, false

Responses

StatusDescriptionBody
200EnabledMeshToggleResponse
successrequiredboolean
meshEnabledrequiredboolean
agentsrequiredarray<MeshAgentStatus>
8 fields of agents
filePathrequiredstring
handlerequiredstring
didstring
agentIdstring
iconstring
staterequiredstring

Display (fleet-map) state of an agent

One of active, idle, hibernate, suspended, off

statusstring
modelstring
Errors 401 · 403 · 405 · 500 · 503
401Missing or wrong bearer token (unauthorized)
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
405Not available on this daemon (the subsystem is read-only or lacks this operation)
500Unexpected runtime failure
503The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/network/mesh/enable" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Disable mesh registration (persisted)

POST/network/mesh/disable

Operation disableMeshAuthBearer token

Persists meshEnabled: false and unregisters mesh agents without unloading them. No body. With persist=0 the setting is left as it is.

Query parameters

NameTypeDescription
persiststring

0 or false: change the live mesh only and leave meshEnabled as it is (Studio's Mesh switch; its Autostart switch writes meshEnabled). Default 1.

One of 1, 0, true, false

Responses

StatusDescriptionBody
200DisabledMeshToggleResponse

Fields as in MeshToggleResponse above.

Errors 401 · 403 · 405 · 500 · 503
401Missing or wrong bearer token (unauthorized)
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
405Not available on this daemon (the subsystem is read-only or lacks this operation)
500Unexpected runtime failure
503The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/network/mesh/disable" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Recent tool calls per mesh agent

GET/network/mesh/recent-tools

Operation getRecentMeshToolsAuthBearer token

Query parameters

NameTypeDescription
limitinteger

Calls per agent (default 5)

Responses

StatusDescriptionBody
200Recent callsRecentMeshToolsResponse
toolsrequiredmap<string, array<object>>

By agent handle

4 fields of tools
namerequiredstring
argsstring
isErrorboolean
timestamprequiredinteger
Errors 400 · 401 · 403 · 405 · 503
400Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY
401Missing or wrong bearer token (unauthorized)
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
405Not available on this daemon (the subsystem is read-only or lacks this operation)
503The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/network/mesh/recent-tools" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

This host's name and LAN addresses

GET/network/mesh/lan-addresses

Operation getLanAddressesAuthBearer token

Responses

StatusDescriptionBody
200AddressesLanAddressesResponse
addressesrequiredobject

Fields as in LanAddressInfo above.

Errors 401 · 403 · 503
401Missing or wrong bearer token (unauthorized)
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
503The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/network/mesh/lan-addresses" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Remote mesh runtimes discovered on the LAN

GET/network/mesh/discovered-runtimes

Operation getDiscoveredRuntimesAuthBearer token

Query parameters

NameTypeDescription
forcestring

Wait for a full scan (the refresh button): 1/true

One of 1, 0, true, false

Responses

StatusDescriptionBody
200Runtimes (the daemon does not discover yet: empty)DiscoveredRuntimesResponse
runtimesrequiredarray<object>
Errors 400 · 401 · 403 · 503
400Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY
401Missing or wrong bearer token (unauthorized)
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
503The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/network/mesh/discovered-runtimes" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

The discovery feed: ADF computers on this network and the tailnet

GET/network/peers

Operation getNetworkPeersAuthBearer token

One feed per computer (remote-access.md §5.1): the one _adf-runtime._tcp browser (plus the legacy _adf-daemon._tcp one for a release) and the one tailnet sweep. Each entry carries both capabilities: its mesh (when visible to other computers) and its remote access (when on). Studio's Discovered list and adf pair read it; the mesh peer list is its mesh half. Local-only: this machine's own clients with the local proof; a device token is refused (it would show the owner's view of the computers around this one). Keeps discovery running for a minute after the call. Changes are pushed to this computer's own sessions as remote_access {type: "peers_changed"}.

Query parameters

NameTypeDescription
waitinteger

Milliseconds to listen first, 0-5000 (a browser that just started hears answers)

range: 0–5000

Responses

StatusDescriptionBody
200The peersobject
peersrequiredarray<NetworkPeer>
5 fields of peers
keyrequiredstring

The runtime id, or fp:<fingerprint> for a computer known only through remote access

namerequiredstring
sourcerequiredstring

One of mdns, tailnet, manual

meshrequiredobject | null

Its mesh, when visible to other computers

2 fields of mesh
urlrequiredstring
portrequiredinteger
remoterequiredobject | null

Its remote access, when on: the tailnet address wins over the LAN one

6 fields of remote
urlrequiredstring
portrequiredinteger
fingerprintrequiredstring

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

pairingOpenrequiredboolean
kindrequiredstring

One of lan, tailnet

clashrequiredinteger | null

One fingerprint seen at this many addresses (more than one on the LAN or on the tailnet): each address is its own entry, never one replacing another; null when not

Errors 400 · 401 · 403 · 503
400Invalid request: missing or malformed field, query parameter or body. A body Fastify cannot parse gets Fastify's own shape (statusCode, code, error, message).bad_requestFST_ERR_CTP_EMPTY_JSON_BODY
401Missing or wrong bearer token (unauthorized)
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
503The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/network/peers" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Mesh HTTP server status

GET/network/server

Operation getMeshServerStatusAuthBearer token

Responses

StatusDescriptionBody
200StatusMeshServerStatus
runningrequiredboolean
portrequiredinteger
hostrequiredstring
lanAddressesarray<string>

Non-loopback addresses listening now. LAN mode (host 0.0.0.0: the Network switch, or an agent with lan or public visibility) listens on private-network and Tailscale addresses of allowed networks only (remote-access.md §3.3, §3.3.1), never on a public address. MESH_HOST set: [MESH_HOST] unless it is loopback.

warningstring

Present while an agent with public visibility has no allowed network to listen on (it is reachable from this computer only, e.g. on a headless server with only a public address). It names MESH_HOST, which binds an address of the operator's choice.

Errors 401 · 403 · 405 · 503
401Missing or wrong bearer token (unauthorized)
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
405Not available on this daemon (the subsystem is read-only or lacks this operation)
503The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/network/server" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"
Response 200
{
  "running": true,
  "port": 7295,
  "host": "127.0.0.1"
}

Start the mesh HTTP server (persisted)

POST/network/server/start

Operation startMeshServerAuthBearer token

The mesh server (port 7295 by default, separate from this API) serves agent cards, health, ALF inbox delivery and agent web/API routes under /agents/{handle}/*. It is on by default; this persists meshServerEnabled: true. No body. With persist=0 the setting is left as it is.

Query parameters

NameTypeDescription
persiststring

0 or false: change the running server only and leave meshServerEnabled as it is (Studio's start/stop, as embedded Studio). Default 1.

One of 1, 0, true, false

Responses

StatusDescriptionBody
200StartedMeshServerActionResponse
successrequiredboolean
runningrequiredboolean
portrequiredinteger
hostrequiredstring
lanAddressesarray<string>

Non-loopback addresses listening now. LAN mode (host 0.0.0.0: the Network switch, or an agent with lan or public visibility) listens on private-network and Tailscale addresses of allowed networks only (remote-access.md §3.3, §3.3.1), never on a public address. MESH_HOST set: [MESH_HOST] unless it is loopback.

warningstring

Present while an agent with public visibility has no allowed network to listen on (it is reachable from this computer only, e.g. on a headless server with only a public address). It names MESH_HOST, which binds an address of the operator's choice.

Errors 401 · 403 · 405 · 500 · 503
401Missing or wrong bearer token (unauthorized)
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
405Not available on this daemon (the subsystem is read-only or lacks this operation)
500Unexpected runtime failure
503The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/network/server/start" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Stop the mesh HTTP server (persisted)

POST/network/server/stop

Operation stopMeshServerAuthBearer token

Persists meshServerEnabled: false, so it stays off across restarts until started again. No body. With persist=0 only the running server stops; the setting is left as it is.

Query parameters

NameTypeDescription
persiststring

0 or false: change the running server only and leave meshServerEnabled as it is (Studio's start/stop, as embedded Studio). Default 1.

One of 1, 0, true, false

Responses

StatusDescriptionBody
200StoppedMeshServerActionResponse

Fields as in MeshServerActionResponse above.

Errors 401 · 403 · 405 · 500 · 503
401Missing or wrong bearer token (unauthorized)
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
405Not available on this daemon (the subsystem is read-only or lacks this operation)
500Unexpected runtime failure
503The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/network/server/stop" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Restart the mesh HTTP server

POST/network/server/restart

Operation restartMeshServerAuthBearer token

No body.

Responses

StatusDescriptionBody
200RestartedMeshServerActionResponse

Fields as in MeshServerActionResponse above.

Errors 401 · 403 · 405 · 500 · 503
401Missing or wrong bearer token (unauthorized)
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
405Not available on this daemon (the subsystem is read-only or lacks this operation)
500Unexpected runtime failure
503The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request
curl -X POST "http://127.0.0.1:7385/network/server/restart" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Probe a peer agent’s /health

GET/network/peers/health

Operation getPeerAgentHealthAuthBearer token

5 s timeout.

Query parameters

NameTypeDescription
urlrequiredstring

The peer agent’s health URL (http or https)

Responses

StatusDescriptionBody
200OKPeerHealthResult
okrequiredboolean
statusstring
statestring
errorstring
Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
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

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/network/peers/health?url=URL" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Fetch a peer agent’s shared file

GET/network/peers/shared-file

Operation getPeerSharedFileAuthBearer token

10 s timeout, 2 MB cap; binary content is base64.

Query parameters

NameTypeDescription
baseUrlrequiredstring

The peer agent’s base URL

pathrequiredstring

Relative shared file path

Responses

StatusDescriptionBody
200OKPeerSharedFileResult
okrequiredboolean
mimestring
sizeinteger
binaryboolean

True: content is base64

contentstring
errorstring
Errors 401 · 403
401Missing or wrong bearer token (unauthorized)
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

Error bodies use the error format.

Example

Request
curl "http://127.0.0.1:7385/network/peers/shared-file?baseUrl=BASE_URL&path=PATH" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"