Configuration

Istok is designed to work with local defaults for its database, repository indexes, and managed artifacts.

Most users do not need to configure these storage paths.

For regular MCP usage, a stable actor identity is recommended so work remains attributable to the same coding agent across MCP process restarts.

Environment variables

Istok recognizes the following environment variables:

Database

Istok stores durable project state in a local SQLite database named:

istok.db

By default, the database is stored in the platform user data directory.

On Linux:

${XDG_DATA_HOME:-$HOME/.local/share}/istok/istok.db

On macOS:

$HOME/Library/Application Support/istok/istok.db

The database contains durable Istok state such as:

• registered projects;
• tasks and task state;
• project context;
• runs;
• validation records;
• context snapshots;
• related project metadata.

Custom database path

Set a custom database path with:

export ISTOK_DATABASE="/path/to/istok.db"

Commands that expose a matching flag can override it explicitly.

For example:

istok mcp --database /path/to/istok.db

The selected database determines which Istok project registry and durable state the command operates on.

A custom path can be useful for isolated environments, testing, or setups where Istok state should live in a specific location.

The managed MCP workflow uses a file-backed database.

Repository index

Repository retrieval data is stored separately from the main SQLite database.

By default, Istok keeps project indexes under its user data directory:

<data-home>/istok/indexes/

Each project has its own index directory:

<data-home>/istok/indexes/<project-id>/

You can override the index root with:

export ISTOK_INDEX_ROOT="/path/to/indexes"

Repository indexes are derived state.

Istok prepares and refreshes them as part of project initialization, search, graph reads, and automatic task retrieval workflows.

You normally do not need to manage the files inside the index directory directly.

See index, search and graph for repository discovery and freshness behavior.

Database and index storage

The main database and repository indexes serve different purposes:

Istok data
   │
   ├── istok.db
   │     └── durable project state
   │
   └── indexes/
         └── derived repository retrieval data

The SQLite database is the durable source of Istok project state.

Repository indexes can be rebuilt from the repository when necessary.

Managed artifacts

Artifacts produced through managed run workflows are stored separately from the database.

For the default data location, they live under:

<data-home>/istok/artifacts/

When a custom database file is selected, the managed artifact directory is stored alongside that database.

The database stores managed artifact references while the artifact contents remain in the artifact store.

If artifacts are important to your workflow, preserve them together with the database when backing up Istok state.

MCP actor identity

Every istok mcp process has one actor identity.

The actor identifies the logical coding agent performing operations through that process.

For a regular coding-agent setup, configure a stable actor ID:

istok mcp \
  --actor-id codex \
  --actor-name "Codex"

The ID and name serve different purposes:

A stable actor ID allows work performed across separate MCP process starts to remain associated with the same logical agent.

For example, you can give different coding agents different identities:

codex        → Codex
claude       → Claude Code
antigravity  → Antigravity CLI
cursor       → Cursor

These are conventions rather than reserved values. You can choose IDs that fit your environment.

See MCP for how actor identity relates to runs and ownership.

Configure actor identity with environment variables

Instead of passing actor flags directly, you can configure the identity through environment variables.

Set the stable actor ID:

export ISTOK_AGENT_ID="codex"

Set its human-readable name:

export ISTOK_AGENT_NAME="Codex"

Then start the MCP server normally:

istok mcp

This is equivalent to supplying the corresponding actor configuration for that process.

Environment variables can be useful when the MCP client or surrounding environment manages server configuration externally.

Command-line actor configuration

You can also configure actor identity explicitly for a particular MCP invocation:

istok mcp \
  --actor-id codex \
  --actor-name "Codex"

When an explicit actor flag and its corresponding environment variable are both present, the command-line value takes precedence for that invocation.

For normal coding-agent configuration, the Quick start uses explicit actor IDs so each configured agent has a recognizable stable identity.

Generated actor identity

If no actor ID is configured, Istok generates a unique identity for the current MCP process.

That process can still use Istok normally.

The generated identity belongs to that MCP process rather than representing a stable logical agent across restarts.

For a persistent coding-agent setup, configure --actor-id or ISTOK_AGENT_ID when you want durable attribution to remain recognizable over time.

Actor identity is fixed at startup

The MCP server fixes its actor identity when it starts.

Individual MCP tool calls cannot replace the actor with another identity.

The same process therefore uses one actor consistently for its project operations.

The MCP process also fixes its repository root at startup, so its effective scope is:

repository root
+
actor identity

See MCP for the complete process-scope model.

Backing up Istok data

The SQLite database contains the durable project state that should be preserved when backing up Istok.

Repository index data is stored separately and can be regenerated from the repository.

Managed artifacts are also stored outside SQLite and should be backed up separately when those files are important to your workflow.

The istok update workflow creates a database backup while applying an update.

That backup covers the database itself, not repository index data or managed artifacts.

Inspect command options

Use built-in help to inspect configuration flags available to a particular command:

istok init --help
istok project --help
istok mcp --help
istok update --help

Next

Continue with JSON output to use Istok from scripts and other programmatic integrations.