Agent and Provider Roster Reference

This page is auto-generated from the Pydantic schema in roster.schema. Terok validates every listed field when it loads a file. Terok rejects unknown keys. This behavior identifies typing errors before Terok uses default values.

JSON Schema files for editor completion and validation:

:material-download: agent.schema.json{: .md-button } :material-download: provider.schema.json{: .md-button } :material-download: routes.schema.json{: .md-button }

---

Agent YAML

Terok parses each bundled file in resources/agents/*.yaml. It also parses each user override in ~/.config/terok/agent/agents/*.yaml. Each file becomes a RawAgentYaml object. Terok then converts the object to a type in roster.types.

All sections use extra="forbid". Thus, an unknown field such as headles: or prommpt_flag: causes an error. Terok does not use a default value for an unknown field.

Top-level keys

Key	Type	Default	Description
kind	Literal	"native"
label	string or null	—	Human-readable display name
binary	string or null	—	CLI binary name (defaults to roster name)
protocol	string or null	—	Wire protocol the agent speaks (anthropic-messages / openai-chat / …)
mounts	list of RawMountSpec	[]
web_ingress	boolean	false	Whether this entry publishes a host HTTP port

git_identity:

Key	Type	Default	Description
name	string or null	—	Git author/committer name
email	string or null	—	Git author/committer email

headless:

Key	Type	Default	Description
subcommand	string or null	—	Subcommand for headless mode (e.g. exec for codex)
prompt_flag	string	"-p"	Flag for the prompt; "" for positional
model_flag	string or null	—	Flag for model override
max_turns_flag	string or null	—	Flag for maximum turns
verbose_flag	string or null	—	Flag for verbose output
output_format_flags	list of string	[]	Flags for structured output

auto_approve:

Key	Type	Default	Description
env	mapping	{}
flags	list of string	[]

session:

Key	Type	Default	Description
supports_resume	boolean	false
resume_flag	string or null	—
resume_subcommand	string or null	—
continue_flag	string or null	—
session_file	string or null	—
supports_hook	boolean	false

capabilities:

Key	Type	Default	Description
add_dir	boolean	false
log_format	Literal	"plain"

wrapper:

Key	Type	Default	Description
refuse_subcommands	list of string	[]

wrapper.launcher:

Key	Type	Default	Description
script	string	required
mode	Literal	required

auth:

Key	Type	Default	Description
host_dir	string	required	Single-segment dir under mounts_dir() (e.g. _codex-config)
container_mount	string	required	Mount point inside the container
command	list or null	—	Container command for OAuth mode; derived from auth_key when absent
banner_hint	string	empty
extra_run_args	list of string	[]
modes	list of Literal	[]
device_auth	boolean	false	OAuth flow has a headless device-code variant, offered in the auth prompt
api_key_hint	string	empty
post_capture_state	mapping	{}	JSON state files to merge into the auth mount post-capture

auth.auth_key:

Key	Type	Default	Description
label	string or null	—
key_url	string	required
env_var	string	required
config_path	string	required
printf_template	string	required
tool_name	string or null	—

provider:

Key	Type	Default	Description
default	string or null	—	Provider name this agent routes to (None for harnesses)
token_env	mapping	{}
token_env_aliases	list of string	[]
base_url_env	string	empty
socket_env	string	empty
ca_cert_env	string	empty
credential_file	string	empty
credential_file_writable	boolean	false	Mount the credential file writable instead of under a read-only shadow. Set when the tool stores credentials and settings in the same file it must rewrite on startup (e.g. glab's config.yml) — the shadow would block the write, and the file persists in the shared mount instead of being contained.
credential_type	Literal	"api_key"
config_patch	dict or null	—

sidecar:

Key	Type	Default	Description
tool_name	string or null	—
env_map	mapping	{}

install:

Key	Type	Default	Description
depends_on	list of string	[]
run_as_root	string	empty
run_as_dev	string	empty

help:

Key	Type	Default	Description
label	string	empty
section	Literal	"agent"

Full example

claude.yaml

kind: native
# Human-readable display name
label:
# CLI binary name (defaults to roster name)
binary:
git_identity:
  # Git author/committer name
  name:
  # Git author/committer email
  email:

headless:
  # Subcommand for headless mode (e.g. exec for codex)
  subcommand:
  # Flag for the prompt; "" for positional
  prompt_flag: -p
  # Flag for model override
  model_flag:
  # Flag for maximum turns
  max_turns_flag:
  # Flag for verbose output
  verbose_flag:
  # Flags for structured output
  output_format_flags: []

auto_approve:
  env: {}
  flags: []

session:
  supports_resume: false
  resume_flag:
  resume_subcommand:
  continue_flag:
  session_file:
  supports_hook: false

capabilities:
  add_dir: false
  log_format: plain

wrapper:
  refuse_subcommands: []
  launcher:
    script: PydanticUndefined
    mode: PydanticUndefined


auth:
  # Single-segment dir under mounts_dir() (e.g. _codex-config)
  host_dir: PydanticUndefined
  # Mount point inside the container
  container_mount: PydanticUndefined
  # Container command for OAuth mode; derived from auth_key when absent
  command:
  auth_key:
    label:
    key_url: PydanticUndefined
    env_var: PydanticUndefined
    config_path: PydanticUndefined
    printf_template: PydanticUndefined
    tool_name:

  banner_hint: ""
  extra_run_args: []
  modes: []
  # OAuth flow has a headless device-code variant, offered in the auth prompt
  device_auth: false
  api_key_hint: ""
  # JSON state files to merge into the auth mount post-capture
  post_capture_state: {}

# Wire protocol the agent speaks (anthropic-messages / openai-chat / …)
protocol:
provider:
  # Provider name this agent routes to (None for harnesses)
  default:
  token_env: {}
  token_env_aliases: []
  base_url_env: ""
  socket_env: ""
  ca_cert_env: ""
  credential_file: ""
  # Mount the credential file writable instead of under a read-only shadow. Set when the tool stores credentials and settings in the same file it must rewrite on startup (e.g. glab's config.yml) — the shadow would block the write, and the file persists in the shared mount instead of being contained.
  credential_file_writable: false
  credential_type: api_key
  config_patch:

sidecar:
  tool_name:
  env_map: {}

install:
  depends_on: []
  run_as_root: ""
  run_as_dev: ""

help:
  label: ""
  section: agent

mounts: []
# Whether this entry publishes a host HTTP port
web_ingress: false

---

Provider YAML

Terok parses each bundled file in resources/providers/*.yaml. Terok also parses each user file in ~/.config/terok/providers/*.yaml. Each file becomes a RawProvider object.

Terok loads the legacy ~/.config/terok/agent/providers/*.yaml directory first. A file in the current provider directory overrides a legacy file that has the same name.

The file name, without .yaml, is the provider name. The name must match [a-z0-9]+. Thus, use only lowercase ASCII letters and digits. A new provider name must not match an existing agent or tool name.

See Custom providers for a minimal example. The example declares model data, so OpenCode and Pi do not request the /models endpoint.

Top-level keys

Key	Type	Default	Description
label	string or null	—	Provider name that users see
upstream	string	required	Upstream API base URL
path_upstreams	mapping	{}
oauth_credential_headers	mapping	{}
shared_domain	boolean	false
serves	mapping	{}	Wire protocol → container-facing base path (LLM providers only)
default_model	string or null	—	Default model ID for OpenCode and Pi
models	mapping	{}	Model data. Each key is a model ID.

auth:

auth.api_key:

Key	Type	Default	Description
header	string	empty	HTTP header that contains the credential. For an empty block, the default is Authorization. For a block that is not empty, this field is required.
prefix	string	empty	Text before the credential. For an empty block, the default is Bearer. If a block contains only header, the prefix stays empty. This behavior supports legacy files.
extra_headers	mapping	{}	Additional headers for this authentication mode.

auth.oauth:

Key	Type	Default	Description
header	string	empty	HTTP header that contains the credential. For an empty block, the default is Authorization. For a block that is not empty, this field is required.
prefix	string	empty	Text before the credential. For an empty block, the default is Bearer. If a block contains only header, the prefix stays empty. This behavior supports legacy files.
extra_headers	mapping	{}	Additional headers for this authentication mode.

oauth_refresh:

Key	Type	Default	Description
token_url	string	required
client_id	string	required
scope	string or null	—

egress:

Key	Type	Default	Description
allow	list of string	[]	Hosts allowed directly at egress (t30)

opencode:

Key	Type	Default	Description
display_name	string	required
base_url	string	required
preferred_model	string	required
fallback_model	string	required
env_var_prefix	string	required
config_dir	string	required
auth_key_url	string	required
api_key_hint	string or null	—	Override for the auto-derived auth provider's API-key hint

install:

Key	Type	Default	Description
depends_on	list of string	[]
run_as_root	string	empty
run_as_dev	string	empty

help:

Key	Type	Default	Description
label	string	empty
section	Literal	"agent"

---

Generated routes.json

AgentRoster.generate_routes_json() creates the routes.json file. The sandbox vault server reads this file. Each entry complies with VaultRouteEntry. The top-level object maps each provider name to its entry. Serialization omits empty optional fields.

Top-level keys

Key	Type	Default	Description
upstream	string	required	Upstream API base URL
auth_header	string	required	HTTP header name for the real credential
auth_prefix	string	required	Prefix prepended to the token (e.g. "Bearer ")
path_upstreams	dict or null	—	Path-prefix → upstream-base overrides
oauth_extra_headers	dict or null	—	Headers added when forwarding OAuth credentials
oauth_credential_headers	dict or null	—	Upstream headers sourced from OAuth credential fields
oauth_refresh	dict or null	—	Token-refresh endpoint config (token_url, client_id, optional scope)