Configuration

Istok works with local defaults, and most people never change them. This page lists the environment variables it reads, where it keeps data, and what to back up.

Environment variables

A command-line flag takes precedence over the matching environment variable.

Data locations

<data-home>/istok/
├── istok.db      durable project state (SQLite)
├── indexes/      derived code index data, one directory per project
└── artifacts/    files recorded by managed runs

Istok writes nothing into your repositories.

Database

istok.db holds registered projects, tasks, context, knowledge, runs, validation records, context snapshots, and related metadata. It is the source of truth for all Istok state.

Code index

Each project has its index under <data-home>/istok/indexes/<project-id>/. Override the root with ISTOK_INDEX_ROOT. Indexes are derived data: Istok builds and refreshes them itself and can rebuild them from the repository. See index, search and graph.

Managed artifacts

Artifact contents are stored outside the database, which keeps only references to them. With the default database they live in <data-home>/istok/artifacts/; with a custom database file, the artifact directory sits next to that file.

Permissions

On Linux and macOS, Istok keeps the database private to your user:

• the default data directory is kept at mode 0700;
• the database file is created as a regular file with mode 0600, and an existing file is set to 0600 when Istok opens it;
• the database path must not be a symbolic link.

These rules cover the POSIX permission bits; existing extended ACL entries are not rewritten.

Custom database

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

or, for commands that support it:

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

The database decides which projects and state a command sees, so the CLI, the MCP server, and the web UI must use the same one to agree. A custom path is useful for isolated environments and testing. The MCP workflow requires a file-backed database.

For a custom path, Istok creates missing directories with mode 0700 but does not change the permissions of an existing directory. If that directory is writable by its group or by other users, Istok refuses to use it, because another user could replace the database file.

Web UI port

istok ui listens on 127.0.0.1:7700 by default. Change the port with --port or:

export ISTOK_UI_PORT=7800

istok ui service install writes the port into the service file (a systemd unit on Linux, a launchd agent on macOS), so a later change to the variable does not affect an installed service until you run install again. See istok ui.

Variables set for managed commands

Commands started with istok run exec and istok run validate, or the matching MCP tools, receive an allowlisted environment from the parent process plus:

MCP actor identity

Each istok mcp process has one actor identity, fixed at startup. Set it with flags or with environment variables, which is handy when the MCP client manages the server’s environment:

export ISTOK_AGENT_ID="codex"
export ISTOK_AGENT_NAME="Codex"
istok mcp

IDs are conventions, not reserved values; choose ones that fit your setup, for example claude for Claude Code, codex for Codex, and cursor for Cursor. Without an ID, Istok generates one for that process only, so attribution does not carry across restarts. See MCP tools.

Backups

Back up istok.db: it holds all durable state, including knowledge. Back up artifacts/ too if recorded files matter to you. indexes/ can be regenerated and does not need a backup.

istok update backs up the database while applying an update. That backup covers only the database, not indexes or artifacts.