Configuration

Configuration directory

By default, Prokop keeps machine-level configuration under ~/.prokopai/. Set PROKOPAI_DATA_DIR in the process environment to move the root directory.

File or directory	Purpose
config.json	Initialization state and database path
models.json	Provider and model registry
.env	Credentials and server environment variables
AGENTS.md	Instructions applied to every workspace
preconfigs/	Agent definitions
agents/	Each agent’s home, memory, and skills
data/agent.db	SQLite database

The server reads ~/.prokopai/.env at startup. Settings can also come from the process environment. Restart the daemon after editing the file directly.

Runtimes

A session runs on one of three runtimes, chosen in the model picker:

Runtime	Runs on	You need
Prokop	The built-in agent runtime	A connected provider, see below
Claude Code	The installed claude CLI	Claude CLI 2.1.259 or newer, logged in on the server machine
Codex CLI	The installed codex CLI	Codex CLI 0.156.0 or newer, logged in on the server machine

To switch runtime mid-conversation, for example when Claude Code or Codex runs out of usage, pick a model from another runtime while the session is idle. The new runtime starts a fresh thread with a summary of the conversation; earlier turns don’t run again. After a switch, Fork is unavailable, and Edit and Undo are unavailable in Claude Code and Codex. Agents can pin a model from any runtime, and New Session follows the default agent’s pin.

• Settings → Server → Harnesses shows each CLI’s installed version and turns Claude Code or Codex off for new sessions and scheduled jobs without stopping existing sessions.
• Usage, a tab next to Sessions in the left dock, shows the 5-hour, weekly, and per-model limits of your Claude and Codex logins, with reset times. It can move to any dock and refreshes while it’s visible. The same view is in Settings → Usage. API-key logins show a note instead.
• Claude Code and Codex sessions need a physical project directory and accept images only as attachments. They keep working after you update the CLI.

Providers and models

Providers power the Prokop runtime. Connect them in Settings → Providers & models, which shows one row per provider with its connection and models.

• API key: OpenRouter, DeepSeek, MiniMax, and Z.AI (Coding Plan).
• Subscription: Codex, signed in with your ChatGPT account. You can keep several accounts and choose which one new runs use.

Anthropic and Google models may be available through OpenRouter. The Prokop runtime has no direct Anthropic or Google integration; Claude Code is available as its own runtime.

Providers come from models.json and the upstream registry; they cannot be created, renamed, or deleted in the app. Models within a provider can be edited. A model with reasoning variants, such as low, medium, high, xhigh, or max, always runs with a concrete variant; Providers & models sets the default one.

API key variables

Variable	Provider
PROKOPAI_LLM_OPENROUTER_API_KEY	OpenRouter
PROKOPAI_LLM_DEEPSEEK_API_KEY	DeepSeek
PROKOPAI_LLM_MINIMAX_API_KEY	MiniMax
PROKOPAI_LLM_ZHIPU_CODING_API_KEY	Z.AI (Coding Plan)

# ~/.prokopai/.env
PROKOPAI_LLM_OPENROUTER_API_KEY=sk-or-...
PROKOPAI_LLM_DEEPSEEK_API_KEY=sk-...

Model registry

prokop init writes the current model registry to ~/.prokopai/models.json. Merge new upstream entries without replacing your custom models:

prokop models sync

To replace the local file with the upstream registry:

prokop models sync --override

LLM behavior

Variable	Default	Purpose
PROKOPAI_LLM_TEMPERATURE	0.7	Default sampling temperature
PROKOPAI_LLM_MAX_TOKENS	32000	Maximum output tokens
PROKOPAI_LLM_MAX_STEPS	10 runtime fallback	Maximum steps for a regular agent turn
PROKOPAI_LLM_SUBAGENT_MAX_STEPS	50 runtime fallback	Maximum steps for a subagent

A standard prokop init writes both step limits as 500 in .env, so initialized installations use those values unless you change them. Agent and model settings can override some other defaults, and some model families ignore settings they do not support. These apply to the Prokop runtime.

Server and network

Variable	Default	Purpose
PROKOPAI_DATA_DIR	~/.prokopai	Root data and configuration directory
PROKOPAI_PORT	8742	Main server port
PROKOPAI_HOST	127.0.0.1	Bind address; this machine only
PROKOPAI_DATABASE_PATH	~/.prokopai/data/agent.db	SQLite database
PROKOPAI_PRECONFIGS_PATH	~/.prokopai/preconfigs	Agent definitions
PROKOPAI_MODELS_PATH	~/.prokopai/models.json	Custom model registry location
PROKOPAI_CLIENT_ENABLED	true	Serve the embedded web client
PROKOPAI_AUTH_TOKEN	None	Token for scripts and the CLI
PROKOPAI_AUTH	On	Set to off to accept unpaired devices on an isolated network

The server listens only on this machine by default. To use Prokop from another device, turn on remote access in Settings → Devices → Remote access or with prokop remote on, then pair the device. See Security & authentication before making a server reachable outside your machine.

TLS

Variable	Default	Purpose
PROKOPAI_TLS_ENABLED	false	Enable the HTTPS listener
PROKOPAI_TLS_CERT_FILE	None	Certificate path
PROKOPAI_TLS_KEY_FILE	None	Private key path
PROKOPAI_TLS_PORT	Automatic	Override the HTTPS port
PROKOPAI_LOCAL_HTTP	Follows TLS	Keep HTTP on loopback while TLS is enabled
PROKOPAI_LOCAL_HOST	127.0.0.1	Local HTTP bind address

Remote access can also set up Tailscale HTTPS for you, without managing certificates yourself.

Compaction

Prokop compacts older conversation history before it exceeds a model’s context window. Recent messages and selected tool results remain available while older material is summarized. Claude Code and Codex sessions use their CLI’s own compaction.

Variable	Default	Purpose
PROKOPAI_COMPACTION_MODEL	Session model	Model used for summaries
PROKOPAI_COMPACTION_PROVIDER	Session provider	Provider used for summaries
PROKOPAI_COMPACTION_MAX_TOKENS	8000	Summary output limit
PROKOPAI_COMPACTION_AUTO_THRESHOLD_RATIO	0.75	Context ratio that triggers compaction
PROKOPAI_COMPACTION_AUTO_RESERVE_CAP_TOKENS	32000	Cap on tokens reserved for recent messages
PROKOPAI_COMPACTION_AUTO_SAFETY_MARGIN_TOKENS	20000	Margin below the model context limit
PROKOPAI_COMPACTION_PRESERVE_RECENT_TOOL_COUNT	3	Recent tool pairs kept intact
PROKOPAI_COMPACTION_PRESERVE_SMALL_TOOL_CHARS	200	Always keep tool results below this size
PROKOPAI_COMPACTION_TOOL_CLEAR_CHARS_THRESHOLD	1000	Clear large tool payloads above this size
PROKOPAI_COMPACTION_MAX_PRUNED_TOOL_COUNT	50	Maximum tool results pruned in one pass

MCP servers

Configure MCP per workspace in <workspace>/.prokopai/mcp.json, or from the workspace’s MCP settings in the client.

{
  "servers": {
    "local-tools": {
      "type": "local",
      "command": ["npx", "-y", "@example/mcp-server"],
      "env": {},
      "timeout": 30000
    },
    "remote-service": {
      "type": "remote",
      "url": "https://mcp.example.com/sse",
      "headers": {}
    }
  }
}

Set "enabled": false to keep a definition without connecting it. Remote definitions can also provide request headers and a timeout.

Memory and learning

Memory, skill management, and workspace learning are set per workspace in Workspace Settings → Memory & Learning; each agent’s own memory and learning in Settings → Agents. See Workspaces & sessions for their behavior and storage paths.

Agents and instructions

Agents bundle a system prompt, tools, model defaults, skill scope, and subagent rules. Create and edit them in Settings → Agents. Their definitions live in ~/.prokopai/preconfigs/ as Markdown files with YAML frontmatter.

Model context can include several inspectable sources:

1. ~/.prokopai/AGENTS.md provides machine-wide rules.
2. <workspace>/AGENTS.md adds project rules.
3. The agent’s own memory, and the workspace’s memory when it is on.
4. Available skill descriptions tell the agent when to call the skill tool and load a full procedure.

The PROKOPAI_ environment prefix is canonical. Legacy JEAN2_ names are compatibility aliases and should not be used for new setups.