Tracked folders · Daemon API

On this page

List tracked folders

GET/tracked-dirs

Operation listTrackedDirsAuthBearer token

Responses

Status Description Body

200 Tracked folders TrackedDirsList

maxDepthrequired integer

directoriesrequired array<TrackedDirEntry>

4 fields of directories

`path`required	string	As stored in settings.trackedDirectories
`exists`required	boolean
`agentCount`required	integer	.adf files an autostart scan finds (maxDirectoryScanDepth)
`loadedCount`required	integer	Of those, loaded in this daemon

Errors 401 · 403 · 503

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

Error bodies use the error format.

Example

Request

curl "http://127.0.0.1:7385/tracked-dirs" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Track a folder and autostart its agents

POST/tracked-dirs

Operation trackDirAuthBearer token

1. path must be an absolute, existing directory; it is stored canonicalized (resolved, symlinks and 8.3 names expanded, no trailing separator). 2. It is persisted to settings.trackedDirectories; a new parent replaces tracked subfolders it covers (absorbed). 3. The live daemon (mesh tracked roots) is updated at once. 4. The folder gets the same autostart pass as daemon boot, with the review gate: unreviewed agents are not loaded and are listed in needsReview (accept with POST /agents/review/accept). agents is every agent in the folder after the pass. Tracking never creates, moves or deletes files; scans use maxDirectoryScanDepth (default 5).

Request bodyapplication/json · TrackDirBody · required

Field	Type	Description
`path`required	string	Absolute path to an existing directory

Responses

Status Description Body

201 Tracked TrackDirResult

entryrequired object

4 fields of entry · TrackedDirEntry

`path`required	string	As stored in settings.trackedDirectories
`exists`required	boolean
`agentCount`required	integer	.adf files an autostart scan finds (maxDirectoryScanDepth)
`loadedCount`required	integer	Of those, loaded in this daemon

directoriesrequired

array<string>

The tracked list after the change

absorbedrequired

array<string>

Tracked subfolders the new folder replaced

autostartrequired object

4 fields of autostart · AutostartReport

scannedrequired

integer

.adf files found

startedrequired array<object>

4 fields of started

`agentId`required	string
`filePath`required	string
`name`required	string
`startupTriggered`required	boolean

skippedrequired array<object>

4 fields of skipped

`filePath`required	string
`name`required	string
`reason`required	string	One of `already_loaded`, `not_autostart`, `password_protected`, `unreviewed`
`agentId`	string

failedrequired array<object>

3 fields of failed

`filePath`required	string
`name`required	string
`error`required	string

needsReviewrequired

array<object>

Autostart skips with reason unreviewed

agentsrequired array<FolderAgent>

7 fields of agents

`filePath`required	string
`name`required	string
`agentId`	string
`status`required	string	One of `loaded`, `needs_review`, `not_autostart`, `stopped`, `password_protected`, `unreadable`
`autostart`required	boolean
`reviewed`required	boolean
`error`	string	Load error or why the file is unreadable

Errors 400 · 401 · 403 · 405 · 409 · 500 · 503

400 Invalid 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

401 Missing or wrong bearer token (unauthorized)

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

405 Settings store is read-only TrackedDirErrorResponse

`error`required	string
`coveredBy`	string	409 only: the tracked folder that already covers the path

409 Already tracked, itself or through a parent (coveredBy) TrackedDirErrorResponse

`error`required	string
`coveredBy`	string	409 only: the tracked folder that already covers the path

500 Unexpected runtime failure

503 The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request

curl -X POST "http://127.0.0.1:7385/tracked-dirs" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"path":"/home/me/agents"}'

Untrack a folder (files are never deleted)

DELETE/tracked-dirs

Operation untrackDirAuthBearer token

path matches the stored string exactly or names the same folder under another spelling; a folder gone from disk can still be untracked by its stored string. unload=true also unloads every loaded agent whose file is under it (files stay on disk); the default leaves them running.

Query parameters

Name	Type	Description
`path`required	string	The tracked folder
`unload`	string	Also unload the agents loaded from under it One of `true`, `false`

Responses

Status Description Body

200 Untracked UntrackDirResult

removedrequired string

directoriesrequired array<string>

unloadedrequired array<object>

3 fields of unloaded

`agentId`required	string
`filePath`required	string
`name`required	string

Errors 400 · 401 · 403 · 404 · 405 · 500 · 503

401 Missing or wrong bearer token (unauthorized)

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 Not a tracked folder TrackedDirErrorResponse

`error`required	string
`coveredBy`	string	409 only: the tracked folder that already covers the path

405 Settings store is read-only TrackedDirErrorResponse

`error`required	string
`coveredBy`	string	409 only: the tracked folder that already covers the path

500 Unexpected runtime failure

503 The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request

curl -X DELETE "http://127.0.0.1:7385/tracked-dirs?path=PATH" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

The agents of one tracked folder and what each needs

GET/tracked-dirs/agents

Operation listTrackedDirAgentsAuthBearer token

status: loaded; needs_review (never reviewed here: POST /agents/review/accept); not_autostart (reviewed, loads on request); stopped (should have loaded but did not: error has the load error when known); password_protected; unreadable (error says why).

Query parameters

Name	Type	Description
`path`required	string	The tracked folder example: /home/me/agents

Responses

Status Description Body

200 Folder agents FolderAgentsList

pathrequired string

agentsrequired array<FolderAgent>

7 fields of agents

`filePath`required	string
`name`required	string
`agentId`	string
`status`required	string	One of `loaded`, `needs_review`, `not_autostart`, `stopped`, `password_protected`, `unreadable`
`autostart`required	boolean
`reviewed`required	boolean
`error`	string	Load error or why the file is unreadable

Errors 400 · 401 · 403 · 404 · 500 · 503

401 Missing or wrong bearer token (unauthorized)

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 Not a tracked folder TrackedDirErrorResponse

`error`required	string
`coveredBy`	string	409 only: the tracked folder that already covers the path

500 Unexpected runtime failure

503 The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request

curl "http://127.0.0.1:7385/tracked-dirs/agents?path=/home/me/agents" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"

Every tracked folder with its agents

GET/tracked-dirs/agents/all

Operation listAllTrackedAgentsAuthBearer token

One read for a fleet view that lists stopped agents next to loaded ones. Each .adf is peeked read-only (sidecars a peek creates are removed), cached per file by the modification time and size of the file and its -wal, so polling opens only files that changed. The last load error an autostart pass hit (boot, POST /agents/autostart, POST /tracked-dirs) stays as error until the agent loads.

Responses

Status Description Body

200 Folders with agents TrackedAgentsList

maxDepthrequired integer

foldersrequired array<object>

5 fields of folders

pathrequired

string

As stored in settings.trackedDirectories

existsrequired boolean

agentCountrequired

integer

.adf files an autostart scan finds (maxDirectoryScanDepth)

loadedCountrequired

integer

Of those, loaded in this daemon

agentsrequired array<FolderAgent>

7 fields of agents

`filePath`required	string
`name`required	string
`agentId`	string
`status`required	string	One of `loaded`, `needs_review`, `not_autostart`, `stopped`, `password_protected`, `unreadable`
`autostart`required	boolean
`reviewed`required	boolean
`error`	string	Load error or why the file is unreadable

Errors 401 · 403 · 500 · 503

401	Missing or wrong bearer token (`unauthorized`)
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`
500	Unexpected runtime failure
503	The subsystem is not configured on this daemon

Error bodies use the error format.

Example

Request

curl "http://127.0.0.1:7385/tracked-dirs/agents/all" \
  -H "Authorization: Bearer $ADF_DAEMON_TOKEN"