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

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.

Automatic in normal use

Normal polytoken new and polytoken continue usage creates and supplies credentials automatically.

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

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

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

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.

Feedback artifact routes

The daemon serves two authenticated routes that support the /feedback form. GET /feedback/artifacts returns the immutable catalog of diagnostic artifacts. GET /feedback/artifacts/{id} retrieves a specific artifact. Both routes require a valid bearer token, and the retrieval route also requires an opaque version token that identifies the exact snapshot to retrieve.