Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/irchaosclub/FANGS/llms.txt

Use this file to discover all available pages before exploring further.

The FANGS orchestrator runs a lightweight HTTP server that handles all communication between the orchestrator process and one or more runner agents. Seven endpoints are mounted under the /v1/ prefix; they cover the full scan lifecycle — from runner registration through job dispatch, event streaming, and final result reporting. The API is not a general-purpose REST API: the fangs CLI accesses the SQLite database directly for most read operations, while /v1/scans is the entry point used by fangs scan submit and fangs package add to queue work.

​
Base URL

The orchestrator listens on http://127.0.0.1:8443 by default. Override the address with the -addr flag at startup. 
http://127.0.0.1:8443
All request and response bodies are JSON. Set Content-Type: application/json on every POST request body. Responses also carry Content-Type: application/json.

​
Transport security

The server defaults to plain HTTP for development convenience. Two upgrade modes are available:
ModeConfiguration
Plain HTTPDefault — no flags needed
HTTPS (server TLS)Pass -tls-cert and -tls-key paths at startup
mTLS (mutual TLS)Also pass -tls-client-ca; every runner must present a cert signed by that CA
When mTLS is active, the CA file forms the orchestrator’s trust anchor for runner identity. TLS 1.2 is the minimum negotiated version.

​
Protocol versioning

All runners must send proto_version: 1 in their registration body. This value maps to the CurrentProtoVersion constant in the protocol package. The orchestrator rejects registration requests with a mismatched version and returns HTTP 400, preventing version-skew issues when the wire format evolves.

​
Endpoint index

GET /v1/health

Liveness probe. Returns orchestrator ID and build version. No authentication required.

POST /v1/runners/register

Introduces a runner to the orchestrator. Must be called before polling for jobs or submitting heartbeats.

POST /v1/runners/{id}/heartbeat

Keeps a runner’s registration alive. Runners not seen for 90 seconds are pruned automatically.

GET /v1/runners/{id}/jobs

Long-poll for the next assigned job. Server waits up to 25 seconds before returning 204 No Content.

POST /v1/scans

Queues a sandbox scan for a specific package and version on a named runner. Returns a run_id for tracking.

POST /v1/runs/{run_id}/events

Streams captured eBPF events from runner to orchestrator as NDJSON EventBatch objects.

POST /v1/runs/{run_id}/result

Finalizes a run after the sandbox and sensor complete. Records status, drop counts, and duration.

​
Health check

The health endpoint is the simplest liveness probe and requires no credentials. 
GET /v1/health HTTP/1.1
Host: 127.0.0.1:8443
Response — 200 OK 
{
  "status": "ok",
  "orchestrator_id": "fangs-orchestrator",
  "version": "dev"
}
​
status
string
Always "ok" when the orchestrator is running and reachable.
​
orchestrator_id
string
Stable identifier set at startup. Runners echo this back in heartbeat logs for cross-referencing.
​
version
string
Build version string injected at compile time. "dev" in local builds.

​
Error responses

All error responses follow the same envelope regardless of which endpoint produced them: 
{"error": "human-readable description"}
Standard HTTP status codes are used throughout:
CodeMeaning
200Success
202Accepted (scan queued)
204No Content (job poll timed out, no work)
400Bad request — missing or invalid field
404Not found — runner not registered, run not found
500Internal server error

​
Stale-runner pruning

The orchestrator runs a background pruner that evicts runners not seen for more than 90 seconds (3× the default 30-second heartbeat interval). The pruner walks the in-memory registry every 30 seconds and removes stale entries. This keeps the registered-runner list accurate after a runner process dies without explicitly deregistering. A runner that receives unknown_runner: true in a heartbeat response must re-register.

Build docs developers (and LLMs) love

Get started for freeTalk to us