Daemon Authentication
Polytoken runs a local HTTP daemon to manage sessions, tools, and model interaction. Every request to that daemon carries a bearer token. This keeps other processes on your machine from issuing commands to the daemon.
How it works
Section titled “How it works”When Polytoken starts a daemon, it generates a random bearer token and writes it to a
credential file inside the session directory. The daemon loads the token at startup and
requires it on every request. The CLI and TUI read the same credential file and include
the token in the Authorization header of each request they make.
Requests without a valid token receive HTTP 401 before the handler runs.
The daemon synchronization routes use the same bearer-token boundary. Use GET /sync
for a checkpoint and GET /events?after=<cursor> for ordered replay; clients must
retain the daemon epoch and cursor returned by the sync snapshot. The CLI exports the
replay record union as JSON Schema with polytoken print sync-event-schema. See
Client Protocol for cursor reset, epoch mismatch, and
operation-correlation behavior.
Automatic in normal use
Section titled “Automatic in normal use”Normal polytoken new and polytoken continue usage creates and supplies credentials
automatically.
The credential file
Section titled “The credential file”When Polytoken spawns a daemon, it creates a file called credential.json in the
session subdirectory. This file contains the bearer token. The file is created with
0600 permissions: readable and writable only by your user account. The session
directory itself uses 0700 permissions.
Specifying a credential file
Section titled “Specifying a credential file”Advanced users or external tooling can supply a pre-existing credential file through the
--credential-file flag or the POLYTOKEN_DAEMON_CREDENTIAL_FILE environment variable.
A daemon process requires this flag at startup: the CLI generates a credential file and
passes it automatically, so in normal use you never need to provide one yourself.
Security model
Section titled “Security model”The bearer token is a high-entropy random value. Polytoken generates it fresh for each session. Polytoken compares incoming tokens against the expected value using a constant-time comparison to prevent timing attacks.
If the daemon cannot load a credential at startup, it rejects every request. A misconfigured daemon never serves unauthenticated.
Polytoken never writes the token to logs, error messages, or debug output.
MCP OAuth callback
Section titled “MCP OAuth callback”The Model Context Protocol (MCP) OAuth callback listener runs on a separate ephemeral port during the OAuth redirect flow. The daemon does not require a bearer token on that listener because the browser redirect carries no token. The main daemon’s own OAuth callback route is authenticated, since the CLI or TUI calls it programmatically with the token already in hand.
Direct daemon access and Outpost proxy access
Section titled “Direct daemon access and Outpost proxy access”A direct request to a daemon always uses that daemon’s bearer token. The token has no
Outpost scope vocabulary. Missing or invalid credentials receive 401 before the
daemon route runs.
An Outpost proxy request uses the Outpost bearer token at the public boundary. Outpost authenticates that token, checks the route scope, and injects the selected daemon’s internal bearer token when it forwards the request. The client never sends the daemon token through the Outpost proxy.
| Request surface | Required authority | Target rule |
|---|---|---|
| Direct daemon route | Daemon bearer token | The token authenticates that one daemon. |
| Outpost session proxy from a daemon principal | Implicit current_session authority | The principal may target only its own session. |
| Outpost session proxy from a machine client | Registered machine scope | The client may target a session selected by the machine-authorized route. |
| Outpost session proxy from a human principal | Human authentication plus the route’s scope check | A human operator may manage sessions; delegated device-flow tokens remain limited to their approved scopes. |
| Outpost fleet catalog, fleet events, stopped history, and attachments | machine scope | The caller must use the machine-authorized fleet surface. |
Scope authorization and object authorization are separate checks. A scope can permit a class of action, while the target-session check prevents a daemon principal from reaching a different session. See Client Protocol for the retry, epoch, cursor, and stopped-history rules that apply after authentication succeeds.