Agent Roster Reference

This page is auto-generated from the Pydantic schema in roster.schema. Every field listed here is validated at load time — unknown keys are rejected, catching typos before they silently fall back to defaults.

JSON Schema files (for editor autocompletion and validation):

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

---

Agent YAML

Each file under resources/agents/*.yaml (and any user override in ~/.config/terok/agent/agents/*.yaml) is parsed into RawAgentYaml before being projected onto the runtime types in roster.types.

All sections use extra="forbid" — typos like headles: or prommpt_flag: raise a precise error rather than silently using defaults.

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)
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	—
continue_flag	string or null	—
session_file	string or null	—
supports_hook	boolean	false

capabilities:

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

wrapper:

Key	Type	Default	Description
refuse_subcommands	list of string	[]

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

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	[]
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	—

vault:

Key	Type	Default	Description
route_prefix	string	required	Path prefix in the proxy (e.g. claude)
upstream	string	required	Upstream API base URL
path_upstreams	mapping	{}
oauth_extra_headers	mapping	{}
auth_header	string	"Authorization"
auth_prefix	string	"Bearer "
credential_type	Literal	"api_key"
credential_file	string	empty
token_env	mapping	{}
base_url_env	string	empty
socket_env	string	empty
shared_config_patch	dict or null	—
shared_domain	boolean	false	True when upstream host also serves non-API traffic (docs, dashboards, git push…); terok's auth-protect layer skips host-level denies for these providers.

vault.oauth_refresh:

Key	Type	Default	Description
token_url	string	required
client_id	string	required
scope	string 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:
  continue_flag:
  session_file:
  supports_hook: false

capabilities:
  agents_json: false
  add_dir: false
  log_format: plain

wrapper:
  refuse_subcommands: []

opencode:
  display_name: PydanticUndefined
  base_url: PydanticUndefined
  preferred_model: PydanticUndefined
  fallback_model: PydanticUndefined
  env_var_prefix: PydanticUndefined
  config_dir: PydanticUndefined
  auth_key_url: PydanticUndefined
  # Override for the auto-derived auth provider's API-key hint
  api_key_hint:

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: []
  api_key_hint: ""
  # JSON state files to merge into the auth mount post-capture
  post_capture_state: {}

vault:
  # Path prefix in the proxy (e.g. claude)
  route_prefix: PydanticUndefined
  # Upstream API base URL
  upstream: PydanticUndefined
  path_upstreams: {}
  oauth_extra_headers: {}
  auth_header: Authorization
  auth_prefix: "Bearer "
  credential_type: api_key
  credential_file: ""
  token_env: {}
  base_url_env: ""
  socket_env: ""
  shared_config_patch:
  oauth_refresh:
    token_url: PydanticUndefined
    client_id: PydanticUndefined
    scope:

  # True when upstream host also serves non-API traffic (docs, dashboards, git push…); terok's auth-protect layer skips host-level denies for these providers.
  shared_domain: false

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

---

Generated routes.json

AgentRoster.generate_routes_json() produces the routes.json file consumed by the sandbox vault server. Each entry conforms to VaultRouteEntry. The full file is a top-level {provider_name: VaultRouteEntry} object; empty optional fields are dropped from the serialized output.

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_refresh	dict or null	—	Token-refresh endpoint config (token_url, client_id, optional scope)