Signet Daemon HTTP API

The Signet Daemon exposes a REST API on http://localhost:3850 by default. All requests and responses use JSON unless otherwise noted. The base URL and port are configurable via environment variables (see Configuration).

Path note: $SIGNET_WORKSPACE means your active Signet workspace path. Default is ~/.agents, configurable via signet workspace set <path>.

Connection

Base URL: http://localhost:3850
SIGNET_PORT  — override port (default: 3850)
SIGNET_HOST  — daemon host for local calls (default: 127.0.0.1)
SIGNET_BIND  — bind host override (defaults to the configured network mode:
               127.0.0.1 for localhost mode, 0.0.0.0 for tailscale mode)

Request and response conventions

• JSON is the default request and response format.
• Authenticated modes use Authorization: Bearer <token>.
• Most list endpoints accept limit and offset or a route-specific bounded limit. Out-of-range values return 400 or are clamped where noted.
• Errors generally use { "error": "human-readable message" }; route-specific errors may include structured fields such as status, code, or missingCapabilities.

Authentication

The daemon supports three Auth modes, set in agent.yaml:

• local — no authentication required. All requests are trusted. This is the default for single-user local installs.
• team — all requests require a Bearer token in the Authorization header.
• hybrid — requests from localhost are trusted without a token; requests from any other origin require a Bearer token.

Tokens use Signet’s signed bearer-token format with a role and optional scope. Dashboard password login uses POST /api/auth/login to exchange the configured admin username/password for an admin session token. The dashboard shell, /api/auth/login, /api/auth/methods, /api/auth/whoami, and reserved /api/auth/sso/* and /api/auth/saml/* provider paths are reachable without an existing bearer token so users can sign in. Other daemon API routes remain protected in team mode.

Roles and their permissions:

Token scopes (project, agent, user) restrict mutations to records matching the scope. Admin role bypasses scope checks. Unscoped tokens have full access within their role.

Rate limits apply in team and hybrid modes:

Errors follow a consistent shape:

{ "error": "human-readable message" }

Rate-limit rejections return 429. Auth failures return 401. Permission violations return 403. Version conflicts and state violations return 409. Mutations blocked by the kill switch return 503.

Reference sections

Maintenance

Route details live in docs/api/ so the root API page stays readable. When adding or changing daemon routes, update the matching reference file and run bun scripts/doc-drift.ts --markdown.