Configuration Reference¶

This page is auto-generated from the Pydantic schema models in yaml_schema.py. Every field listed here is validated at load time — unknown keys are rejected, catching typos before they silently do nothing.

JSON Schema files (for editor autocompletion and validation): :material-download: project.schema.json{: .md-button } :material-download: config.schema.json{: .md-button }

project.yml¶

Per-project configuration. Located at <projects-root>/<id>/project.yml, where the projects root is discovered via user_projects_root() (default ~/.config/terok/projects, overridable via paths.user_projects_root in config.yml) or the system config root.

Top-level keys¶

Key	Type	Default	Description
`default_agent`	string or null	—	Default agent provider (e.g. `claude`, `codex`)
`default_login`	string or null	—
`agent`	mapping	`{}`	Agent configuration dict (model, subagents, MCP servers, etc.)

`project:`¶

Key	Type	Default	Description
`id`	string or null	—	Unique project identifier (lowercase, `[a-z0-9_-]`)
`name`	string or null	—	Human-readable project name (display only)
`security_class`	string	`"online"`	Security mode: `online` (direct push) or `gatekeeping` (gated mirror)

`git:`¶

Key	Type	Default	Description
`upstream_url`	string or null	—	Repository URL to clone into task containers
`default_branch`	string or null	—	Default branch name (e.g. `main`)
`human_name`	string or null	—	Human name for git committer identity
`human_email`	string or null	—	Human email for git committer identity
`authorship`	string or null	—	How agent/human map to git author/committer. Values: `agent-human`, `human-agent`, `agent`, `human`

`ssh:`¶

Key	Type	Default	Description
`key_name`	string or null	—	SSH key filename (default: `id_ed25519_<project_id>`)
`host_dir`	string or null	—	Host directory for SSH key storage (keys served via SSH agent proxy, not mounted)
`config_template`	string or null	—	Path to an SSH config template file (supports `{{IDENTITY_FILE}}`, `{{KEY_NAME}}`, `{{PROJECT_ID}}`)

`tasks:`¶

Key	Type	Default	Description
`root`	string or null	—	Override task workspace root directory
`name_categories`	list or null	—	Word categories for auto-generated task names (string or list of strings)

`gate:`¶

Key	Type	Default	Description
`path`	string or null	—	Override git gate (mirror) path

`gatekeeping:`¶

Key	Type	Default	Description
`staging_root`	string or null	—	Staging directory for gatekeeping builds
`expose_external_remote`	boolean	`false`	Add upstream URL as `external` remote in gatekeeping containers

`gatekeeping.upstream_polling:`¶

Key	Type	Default	Description
`enabled`	boolean	`true`	Poll upstream for new commits
`interval_minutes`	integer	`5`	Polling interval in minutes

`gatekeeping.auto_sync:`¶

Key	Type	Default	Description
`enabled`	boolean	`false`	Auto-sync branches from upstream to gate
`branches`	list of string	`[]`	Branch names to auto-sync

`run:`¶

Key	Type	Default	Description
`shutdown_timeout`	integer	`10`	Seconds to wait before SIGKILL on container stop
`gpus`	string or boolean or null	—	GPU passthrough: `true`, `"all"`, or omit to disable

`run.hooks:`¶

Key	Type	Default
`pre_start`	string or null	—
`post_start`	string or null	—
`post_ready`	string or null	—
`post_stop`	string or null	—

`shield:`¶

Key	Type	Default	Description
`drop_on_task_run`	boolean or null	—	Drop shield (bypass firewall) when task container is created
`on_task_restart`	Literal or null	—	Shield policy on container restart: `retain` or `up`

`docker:`¶

Key	Type	Default	Description
`base_image`	string	`"ubuntu:24.04"`	Base Docker image for container builds
`user_snippet_inline`	string or null	—	Inline Dockerfile snippet injected into the project image
`user_snippet_file`	string or null	—	Path to a file containing a Dockerfile snippet

Full example¶

project.yml

project:
  # Unique project identifier (lowercase, [a-z0-9_-])
  id:
  # Human-readable project name (display only)
  name:
  # Security mode: online (direct push) or gatekeeping (gated mirror)
  security_class: online

git:
  # Repository URL to clone into task containers
  upstream_url:
  # Default branch name (e.g. main)
  default_branch:
  # Human name for git committer identity
  human_name:
  # Human email for git committer identity
  human_email:
  # How agent/human map to git author/committer. Values: agent-human, human-agent, agent, human
  authorship:

ssh:
  # SSH key filename (default: id_ed25519_<project_id>)
  key_name:
  # Host directory for SSH key storage (keys served via SSH agent proxy, not mounted)
  host_dir:
  # Path to an SSH config template file (supports {{IDENTITY_FILE}}, {{KEY_NAME}}, {{PROJECT_ID}})
  config_template:

tasks:
  # Override task workspace root directory
  root:
  # Word categories for auto-generated task names (string or list of strings)
  name_categories:

gate:
  # Override git gate (mirror) path
  path:

gatekeeping:
  # Staging directory for gatekeeping builds
  staging_root:
  # Add upstream URL as external remote in gatekeeping containers
  expose_external_remote: false
  upstream_polling:
    # Poll upstream for new commits
    enabled: true
    # Polling interval in minutes
    interval_minutes: 5

  auto_sync:
    # Auto-sync branches from upstream to gate
    enabled: false
    # Branch names to auto-sync
    branches: []


run:
  # Seconds to wait before SIGKILL on container stop
  shutdown_timeout: 10
  # GPU passthrough: true, "all", or omit to disable
  gpus:
  hooks:
    pre_start:
    post_start:
    post_ready:
    post_stop:


shield:
  # Drop shield (bypass firewall) when task container is created
  drop_on_task_run:
  # Shield policy on container restart: retain or up
  on_task_restart:

docker:
  # Base Docker image for container builds
  base_image: "ubuntu:24.04"
  # Inline Dockerfile snippet injected into the project image
  user_snippet_inline:
  # Path to a file containing a Dockerfile snippet
  user_snippet_file:

# Default agent provider (e.g. claude, codex)
default_agent:
default_login:
# Agent configuration dict (model, subagents, MCP servers, etc.)
agent: {}

config.yml¶

Global configuration. Search order:

$TEROK_CONFIG_FILE (explicit override)
${XDG_CONFIG_HOME:-~/.config}/terok/config.yml
sys.prefix/etc/terok/config.yml
/etc/terok/config.yml

Top-level keys¶

Key	Type	Default	Description
`default_agent`	string or null	—	Default agent provider (e.g. `claude`, `codex`)
`default_login`	string or null	—
`agent`	mapping	`{}`	Agent configuration dict (model, subagents, MCP servers, etc.)

`ui:`¶

Key	Type	Default	Description
`base_port`	integer	`7860`	Base port for web UI task containers

`credentials:`¶

Key	Type	Default	Description
`dir`	string or null	—	Shared credentials directory (proxy DB, agent config mounts)

`paths:`¶

Key	Type	Default	Description
`state_dir`	string or null	—	Writable state directory (tasks, caches, builds)
`build_dir`	string or null	—	Build artifacts directory (generated Dockerfiles)
`user_projects_dir`	string or null	—	User projects directory (per-user project configs)
`user_presets_dir`	string or null	—	User presets directory (per-user preset configs)

`tui:`¶

Key	Type	Default	Description
`default_tmux`	boolean	`false`	Default to tmux mode when launching the TUI

`logs:`¶

Key	Type	Default	Description
`partial_streaming`	boolean	`true`	Enable typewriter-effect streaming for log viewing

`shield:`¶

Key	Type	Default	Description
`bypass_firewall_no_protection`	boolean	`false`	Dangerous: disable egress firewall entirely
`profiles`	dict or null	—	Named shield profiles for per-project firewall rules
`audit`	boolean	`true`	Enable shield audit logging
`drop_on_task_run`	boolean	`true`	Drop shield (bypass firewall) when task container is created
`on_task_restart`	Literal	`"retain"`	Shield policy on container restart: `retain` or `up`

`credential_proxy:`¶

Key	Type	Default	Description
`bypass_no_secret_protection`	boolean	`false`
`transport`	Literal	`"socket"`

`gate_server:`¶

Key	Type	Default	Description
`port`	integer	`9418`	Gate server listen port
`repos_dir`	string or null	—
`suppress_systemd_warning`	boolean	`false`	Suppress the systemd unit installation suggestion

`tasks:`¶

Key	Type	Default	Description
`name_categories`	list or null	—	Word categories for auto-generated task names (string or list of strings)

`git:`¶

Key	Type	Default	Description
`human_name`	string or null	—	Human name for git committer identity
`human_email`	string or null	—	Human email for git committer identity
`authorship`	string or null	—	How agent/human map to git author/committer. Values: `agent-human`, `human-agent`, `agent`, `human`

`hooks:`¶

Key	Type	Default
`pre_start`	string or null	—
`post_start`	string or null	—
`post_ready`	string or null	—
`post_stop`	string or null	—

Full example¶

config.yml

ui:
  # Base port for web UI task containers
  base_port: 7860

credentials:
  # Shared credentials directory (proxy DB, agent config mounts)
  dir:

paths:
  # Writable state directory (tasks, caches, builds)
  state_dir:
  # Build artifacts directory (generated Dockerfiles)
  build_dir:
  # User projects directory (per-user project configs)
  user_projects_dir:
  # User presets directory (per-user preset configs)
  user_presets_dir:

tui:
  # Default to tmux mode when launching the TUI
  default_tmux: false

logs:
  # Enable typewriter-effect streaming for log viewing
  partial_streaming: true

shield:
  # Dangerous: disable egress firewall entirely
  bypass_firewall_no_protection: false
  # Named shield profiles for per-project firewall rules
  profiles:
  # Enable shield audit logging
  audit: true
  # Drop shield (bypass firewall) when task container is created
  drop_on_task_run: true
  # Shield policy on container restart: retain or up
  on_task_restart: retain

credential_proxy:
  bypass_no_secret_protection: false
  transport: socket

gate_server:
  # Gate server listen port
  port: 9418
  repos_dir:
  # Suppress the systemd unit installation suggestion
  suppress_systemd_warning: false

tasks:
  # Word categories for auto-generated task names (string or list of strings)
  name_categories:

git:
  # Human name for git committer identity
  human_name:
  # Human email for git committer identity
  human_email:
  # How agent/human map to git author/committer. Values: agent-human, human-agent, agent, human
  authorship:

hooks:
  pre_start:
  post_start:
  post_ready:
  post_stop:

# Default agent provider (e.g. claude, codex)
default_agent:
default_login:
# Agent configuration dict (model, subagents, MCP servers, etc.)
agent: {}

Validation behavior¶

All config models use Pydantic v2 with extra="forbid". This means:

Typos are caught at load time — e.g. projecct: instead of project: produces a clear error with the field path.
Type mismatches are reported — e.g. shutdown_timeout: "ten" fails with a descriptive message.
Enum values are validated — security_class must be online or gatekeeping.
Null sections get defaults — writing git: with no sub-keys is equivalent to omitting the section entirely.

Note

project.yml validation is strict: errors produce a clear message and abort the operation. config.yml validation is lenient: errors are logged as warnings and the file falls back to defaults, so a typo in global config never prevents the TUI or CLI from starting.

Configuration Reference¶

project.yml¶

Top-level keys¶

project:¶

git:¶

ssh:¶

tasks:¶

gate:¶

gatekeeping:¶

gatekeeping.upstream_polling:¶

gatekeeping.auto_sync:¶

run:¶

run.hooks:¶

shield:¶

docker:¶

Full example¶

config.yml¶

Top-level keys¶

ui:¶

credentials:¶

paths:¶

tui:¶

logs:¶

shield:¶

credential_proxy:¶

gate_server:¶

tasks:¶

git:¶

hooks:¶

Full example¶

Validation behavior¶

`project:`¶

`git:`¶

`ssh:`¶

`tasks:`¶

`gate:`¶

`gatekeeping:`¶

`gatekeeping.upstream_polling:`¶

`gatekeeping.auto_sync:`¶

`run:`¶

`run.hooks:`¶

`shield:`¶

`docker:`¶

`ui:`¶

`credentials:`¶

`paths:`¶

`tui:`¶

`logs:`¶

`shield:`¶

`credential_proxy:`¶

`gate_server:`¶

`tasks:`¶

`git:`¶

`hooks:`¶