Types
types
¶
Runtime dataclasses produced by the agent roster loader.
These are the immutable result types that consumers (env builder,
auth flow, image build) receive after a YAML file passes the
schema validation gate. Kept in
their own module so both schema
(which projects onto them) and loader
(which orchestrates the projection) can import without a cycle.
HelpSection = Literal['agent', 'dev_tool']
module-attribute
¶
Section in the in-container help banner that an entry belongs to.
HELP_SECTIONS = get_args(HelpSection)
module-attribute
¶
All valid HelpSection values, as a tuple (single source of truth).
MountDef(host_dir, container_path, label, credential_file='', provider='')
dataclass
¶
A shared directory mount derived from the agent roster.
host_dir
instance-attribute
¶
Directory name under mounts_dir() (e.g. "_codex-config").
container_path
instance-attribute
¶
Mount point inside the container (e.g. "/home/dev/.codex").
label
instance-attribute
¶
Human-readable label (e.g. "Codex config").
credential_file = ''
class-attribute
instance-attribute
¶
Credential file path relative to the mount root (e.g. ".credentials.json").
Empty when the mount carries no auth artefact (e.g. opencode state dirs).
Populated from the matching vault.credential_file so callers can
layer a read-only shadow over the file without touching the rest of
the shared mount. See terok-ai/terok#873.
provider = ''
class-attribute
instance-attribute
¶
Roster entry name that contributed this mount (e.g. "claude").
Empty for explicit mounts: blocks that aren't tied to a single
provider. Used by the credential-shadow path to match against
ContainerEnvSpec.expose_credential_providers.
VaultRoute(provider, route_prefix, upstream, path_upstreams=dict(), oauth_extra_headers=dict(), auth_header='Authorization', auth_prefix='Bearer ', credential_type='api_key', credential_file='', token_env=dict(), base_url_env='', socket_env='', shared_config_patch=None, oauth_refresh=None, shared_domain=False)
dataclass
¶
Vault route config parsed from a vault: YAML section.
Used to generate the routes.json that the vault server reads.
provider
instance-attribute
¶
Agent/tool name (e.g. "claude").
route_prefix
instance-attribute
¶
Path prefix in the proxy (e.g. "claude" → /claude/v1/...).
upstream
instance-attribute
¶
Upstream API base URL (e.g. "https://api.anthropic.com").
path_upstreams = field(default_factory=dict)
class-attribute
instance-attribute
¶
Optional request-path prefix → upstream-base overrides.
oauth_extra_headers = field(default_factory=dict)
class-attribute
instance-attribute
¶
Provider-specific headers added only when forwarding OAuth credentials.
auth_header = 'Authorization'
class-attribute
instance-attribute
¶
HTTP header name for the real credential.
auth_prefix = 'Bearer '
class-attribute
instance-attribute
¶
Prefix before the token value in the auth header.
credential_type = 'api_key'
class-attribute
instance-attribute
¶
Type of credential: "oauth", "api_key", "oauth_token", "pat".
credential_file = ''
class-attribute
instance-attribute
¶
Credential file path relative to the auth mount.
token_env = field(default_factory=dict)
class-attribute
instance-attribute
¶
Phantom-token env var name, keyed by stored credential type.
The named env var carries the phantom token the agent reads in place of
the real credential. Keys are credential types ("oauth", "pat",
…); "_default" is the fallback for any type without an explicit
entry. Most agents read one env var regardless of type
({"_default": "MISTRAL_API_KEY"}); Claude swaps the name when an
OAuth token is stored
({"oauth": "CLAUDE_CODE_OAUTH_TOKEN", "_default": "ANTHROPIC_API_KEY"}).
base_url_env = ''
class-attribute
instance-attribute
¶
Env var to override with the vault's HTTP URL (e.g. "ANTHROPIC_BASE_URL").
socket_env = ''
class-attribute
instance-attribute
¶
Env var that receives the container-side vault socket path.
Set when the agent speaks HTTP-over-UNIX natively (e.g. Claude reads
ANTHROPIC_UNIX_SOCKET). The resolved value is mode-dependent and
injected centrally by the env builder.
shared_config_patch = None
class-attribute
instance-attribute
¶
Optional shared config patch applied after auth (e.g. Vibe's config.toml).
oauth_refresh = None
class-attribute
instance-attribute
¶
OAuth refresh config: {token_url, client_id, scope}.
shared_domain = False
class-attribute
instance-attribute
¶
Whether the upstream host also serves non-API traffic.
Set on entries whose upstream host is an apex (or otherwise mixed)
domain that legitimately serves docs, dashboards, git push, etc.
Host-level egress denies can't separate paths, so terok's auth-protect
layer skips these providers when re-applying denies after shield
down — credential containment alone keeps the API safe.
Examples: gitlab.com (API + git push), sonarcloud.io
(API + project pages + docs + badges).
InstallSpec(depends_on=(), run_as_root='', run_as_dev='')
dataclass
¶
Roster-driven install snippets emitted into the L1 Dockerfile.
The build template loops over the resolved selection and concatenates
run_as_root snippets in the root section, run_as_dev snippets
in the dev-user section. Both fields are raw Dockerfile fragments
(RUN, COPY — anything valid at top level after USER ...).
depends_on lists other roster names that must be installed
alongside this one (transitively resolved at selection time).
depends_on = ()
class-attribute
instance-attribute
¶
Other roster entries this install requires (e.g. blablador → opencode).
run_as_root = ''
class-attribute
instance-attribute
¶
Dockerfile fragment emitted in the root section of the L1 image.
run_as_dev = ''
class-attribute
instance-attribute
¶
Dockerfile fragment emitted in the dev-user section of the L1 image.
HelpSpec(label='', section='agent')
dataclass
¶
SidecarSpec(tool_name, env_map=dict())
dataclass
¶
Sidecar container configuration parsed from a sidecar: YAML section.
Tools with sidecar specs run in a separate lightweight L1 image (no agent CLIs) and receive the real API key instead of phantom tokens.
tool_name
instance-attribute
¶
Tool identifier used to select the Jinja2 install block in the template.
env_map = field(default_factory=dict)
class-attribute
instance-attribute
¶
Maps container env var names to credential dict keys.
Example: {"CODERABBIT_API_KEY": "key"} reads cred["key"] and
injects it as CODERABBIT_API_KEY.