Security & authentication

Default: local only, no login

By default, Prokop binds to 127.0.0.1, so only clients on the same machine can reach it, and they need no login.

Same-machine access is limited to real local clients:

• Requests arriving over loopback must address the server by a loopback name (localhost, 127.0.0.1, [::1], *.localhost). This blocks DNS-rebinding pages.
• Browser requests must come from the server’s own origin, a loopback origin such as a dev server on another port, or a browser extension. Other websites get 403.
• Requests from a paired device or with a valid PROKOPAI_AUTH_TOKEN skip both checks.

Use Prokop from another device

1. Choose how other devices reach the server in Settings → Devices → Remote access on the computer, or with prokop remote.
2. Open Prokop on the other device. It asks the computer for approval and shows a four-digit code.
3. On the computer, a prompt asks whether to allow the device. Check that the code matches, then choose Allow.

Remote access

Setup	What to do
Same Wi-Fi or LAN	Turn on Allow devices on my network (prokop remote on)
Tailscale, quickest	Turn on Allow devices on my network; Tailscale devices can then use the computer’s Tailscale IP or name
Tailscale with HTTPS, for the installable app and notifications on phones	Choose Set up next to Tailscale HTTPS (prokop remote tailscale on). Prokop runs tailscale serve and adds the https://<machine>.<tailnet>.ts.net address
WireGuard, ZeroTier, or another VPN	Turn on Allow devices on my network and use the VPN address shown
Caddy, nginx, Cloudflare Tunnel, or another proxy	Add the public address, for example https://prokop.example.com (prokop remote add <url>), and point the proxy at http://127.0.0.1:8742

Changes apply immediately without a restart. Turning network access off disconnects devices that connected over the network. Every address still requires pairing.

A proxy on the same machine forwards requests with its own hostname. Prokop accepts only hostnames saved as addresses, set in PROKOPAI_ALLOWED_HOSTS, or the machine’s own Tailscale name. PROKOPAI_HOST fixes the bind address and makes the network toggle read-only.

prokop remote                     # how other devices can reach Prokop
prokop remote on | off            # listen on your network or only on this computer
prokop remote add <url>           # add a VPN, proxy, or tunnel address
prokop remote remove <url>
prokop remote tailscale on | off  # share over Tailscale HTTPS

Pair with a code

Instead of approving a request, you can pair with a one-time code. Run prokop pair on the server, which prints a QR code, a /pair#code=... link, and the code, or open Settings → Devices → Pair a device. Scan the QR code, open the link on the other device, or paste it into Add Server. A code works once and expires after 5 minutes.

Manage devices

A device stays paired for 30 days after its last use. Settings → Devices on the computer lists waiting requests and paired devices; Remove revokes a device and closes its connections immediately.

prokop auth                     # list paired devices
prokop auth revoke <device-id>  # remove one

A paired device can unpair itself, but only the computer running Prokop can approve, pair, or remove other devices.

How it works

• Pairing codes and device tokens are stored only as SHA-256 hashes.
• Devices send their token in the Authorization: Bearer header. WebSockets use a 60-second, single-use ticket, so tokens never appear in socket URLs.
• Requests through a same-machine proxy arrive over loopback with the proxy’s hostname. They are treated as another device and must pair.

Turn authentication off

For an isolated network where every device should have access without pairing, set PROKOPAI_AUTH=off. Other websites are still refused.

Shared token for scripts

PROKOPAI_AUTH_TOKEN works as a shared password for scripts, the CLI, and any device:

# ~/.prokopai/.env
PROKOPAI_AUTH_TOKEN=replace-this-with-a-long-random-token

Send it as Authorization: Bearer <token>. It has no per-device revocation, so prefer pairing for devices, and protect ~/.prokopai/.env with appropriate filesystem permissions.

TLS

Remote access can set up Tailscale HTTPS for you. For other setups, 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, the main port keeps serving plain HTTP on loopback for clients on the same machine, and HTTPS moves to its own port: the same port when the server binds a specific non-loopback address, or one higher otherwise. TLS on the default 127.0.0.1 bind is reachable only from this machine. Disable the local listener with PROKOPAI_LOCAL_HTTP=false, and override the TLS port with PROKOPAI_TLS_PORT. A reverse proxy such as Caddy or nginx can also terminate TLS in front of Prokop.

Public routes

A small set of routes stays available without authentication so clients can discover and check the server. Attachment content routes require the random access key in the attachment URL, so treat that URL as sensitive. Attachments are served sandboxed, so an attached HTML page can’t run scripts or read your login.

Route	Purpose
GET /	Embedded client when available, otherwise server status
GET /api/health	Health status
GET /api/info	Server version and connection information
GET /api/sessions/:id/attachments/:attachmentId/content	Download an attachment with its access key

Tool permissions

Tool permissions are separate from authentication: authentication controls who can connect, and permissions control what an agent may do after that. Every session, workspace, and scheduled job runs in one permission mode:

Mode	Asks when a command or file operation
Standard (default)	Reaches outside the workspace, touches secrets, or is destructive
Extended	Touches secrets or is destructive; paths outside the workspace are allowed
Full	Is catastrophic, such as rm -rf /*

Catastrophic commands ask in every mode. Claude Code, Codex, and Prokop sessions follow the same rules. Grants belong to a workspace, persist in SQLite, and can be reviewed and revoked in Workspace Settings. Malformed or missing permission responses fail closed.

Remote access checklist

1. Keep the server local until you need another device, then pair it instead of using a shared token.
2. Use HTTPS, such as Tailscale HTTPS, for anything beyond a trusted local network.
3. Protect ~/.prokopai/.env, TLS keys, provider credentials, and the SQLite database.
4. Pick the permission mode each workspace needs, and review its grants.
5. Remove devices you no longer use, and keep Prokop updated with prokop update.

See Configuration for the full environment reference.