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, database path, and a stored tools path
models.json	Provider and model registry
.env	Credentials and server environment variables
AGENTS.md	Instructions applied to every workspace
preconfigs/	Reusable agent configurations
tools/	User-prepared external tool modules
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.

Providers and models

The easiest route is Configuration in the client. Add a provider credential, use a supported OAuth account, then choose which models should appear in sessions.

Supported direct API-key providers currently include OpenAI, OpenRouter, DeepSeek, MiniMax, Zhipu, and Zhipu Coding Plan. Codex can use a ChatGPT subscription through OAuth. A credential enables the provider runtime, but a provider also needs model entries in models.json before those models appear in sessions.

API key variables

Variable	Provider
PROKOPAI_LLM_OPENAI_API_KEY	OpenAI
PROKOPAI_LLM_OPENROUTER_API_KEY	OpenRouter
PROKOPAI_LLM_DEEPSEEK_API_KEY	DeepSeek
PROKOPAI_LLM_MINIMAX_API_KEY	MiniMax
PROKOPAI_LLM_ZHIPU_API_KEY	Zhipu
PROKOPAI_LLM_ZHIPU_CODING_API_KEY	Zhipu Coding Plan

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

Model registry

prokop init writes the current model registry to ~/.prokopai/models.json. New upstream entries can be merged without replacing your custom models:

prokop models sync

To replace the local file with the upstream registry:

prokop models sync --override

You can also add providers and models from the client. Some models expose reasoning variants such as low, medium, high, xhigh, or max when supported by that provider.

LLM behavior

Variable	Default	Purpose
PROKOPAI_LLM_BASE_URL	OpenAI default	Override the OpenAI API base URL
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. Preconfig and model settings can override some other defaults. Certain model families also ignore settings they do not support.

Server and network

Variable	Default	Purpose
PROKOPAI_DATA_DIR	~/.prokopai	Root data and configuration directory
PROKOPAI_PORT	8742	Main server port
PROKOPAI_HOST	0.0.0.0	Bind address
PROKOPAI_DATABASE_PATH	~/.prokopai/data/agent.db	SQLite database
PROKOPAI_TOOLS_PATH	~/.prokopai/tools	External tool modules
PROKOPAI_PRECONFIGS_PATH	~/.prokopai/preconfigs	Preconfig files
PROKOPAI_MODELS_PATH	~/.prokopai/models.json	Custom model registry location
PROKOPAI_CLIENT_ENABLED	true	Serve the embedded web client
PROKOPAI_AUTH_TOKEN	None	Require authentication when set

See Security & authentication before making a server available outside a trusted network.

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

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.

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.

{
  "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.

Workspace capabilities

Enable Memory, Skills, Workflow, Session Search, and Scheduling from Workspace Settings > Capabilities. These settings belong to the workspace, not the whole server. Memory, Skills, Session Search, and Scheduling also have permission risk levels.

See Workspaces & sessions for their behavior and storage paths.

Preconfigs and instructions

Preconfigs live in ~/.prokopai/preconfigs/. They bundle an agent prompt, tools, model defaults, skill scope, and subagent rules. Create and edit them in the client or 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. Enabled memory adds the workspace’s saved preferences and facts.
4. Available skill descriptions tell the agent when to call the skill tool and load a full procedure.

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