Security & authentication

Default network behavior

By default, Prokop binds to 0.0.0.0 and does not require authentication. That is convenient on localhost, an air-gapped machine, or a private network you fully trust.

Do not make the default server reachable from the public internet. Authentication controls who can connect. TLS prevents credentials and session traffic from crossing the network in plain text.

Enable authentication

Set a token in ~/.prokopai/.env:

PROKOPAI_AUTH_TOKEN=replace-this-with-a-long-random-token

Restart the daemon:

prokop restart

Check the current state without printing the full token:

prokop auth

Once enabled, protected API routes and all WebSocket connections require the token. HTTP clients can send it as a bearer token or query parameter; WebSocket clients use the supported connection URL flow.

Authorization: Bearer your-secret-token

Equal-length tokens are compared without an early exit. Tokens are stored as plain environment values, so protect ~/.prokopai/.env with appropriate filesystem permissions.

Enable TLS

For traffic over an untrusted network, configure a certificate and private key:

PROKOPAI_TLS_ENABLED=true
PROKOPAI_TLS_CERT_FILE=/path/to/cert.pem
PROKOPAI_TLS_KEY_FILE=/path/to/key.pem

When TLS is enabled, Prokop can keep plain HTTP on loopback for clients on the same machine. The HTTPS listener uses the configured TLS port, the main port when bound to a specific non-loopback address, or the next port when needed to avoid overlap.

For a Tailscale setup, bind PROKOPAI_HOST to the machine’s Tailscale IP when you want HTTPS to use the main port. A reverse proxy such as Caddy or nginx can also terminate TLS in front of Prokop.

Public routes

A small set of API routes stays available without the server auth token so clients can discover and check the server. The embedded client shell and its static assets are also public, while protected data still requires authentication. Attachment content routes are exempt from server-token auth, but require the random access key included in an attachment URL. Treat that URL as sensitive.

Tool permissions

Tool permissions are separate from network authentication. They control agent actions after a user has connected.

Sensitive operations can pause for approval, including writes, deletion, shell commands, network access, and access outside the workspace. Depending on the request, you can approve once, create a scoped reusable grant, or deny it.

Permissions belong to a workspace and persist in SQLite. Review and revoke grants from Workspace Settings. Malformed or missing permission responses fail closed.

Remote access checklist

1. Keep the server on localhost or a private network when possible.
2. Set PROKOPAI_AUTH_TOKEN before allowing other devices to connect.
3. Use HTTPS for untrusted networks.
4. Protect ~/.prokopai/.env, TLS keys, provider credentials, and the SQLite database.
5. Review workspace tool grants and enable only the capabilities each workspace needs.
6. Keep Prokop updated with prokop update.

See Configuration for the full environment reference.