Configuration
Every config option created by bootstrap
After phantasm bootstrap, the current shipped runtime creates exactly two
user-edited config files: .phantasm/phantasm.toml and
.phantasm/clients.toml. This page documents every supported key in both
files and calls out what is not configurable yet.
Generated layout
.phantasm/
├── phantasm.toml
├── clients.toml
└── state/
├── store.sqlite
├── backups/
├── indexes/
├── logs/
├── raw/
└── tmp/
Only phantasm.toml and clients.toml are public config files
today. The rest of the runtime layout is state, storage, or derived output.
phantasm.toml
version = "v1"
default_client = "generic_mcp"version
Type: quoted string. Default: "v1". This is the config schema version.
The runtime currently accepts only v1.
default_client
Type: quoted string. Default: "generic_mcp". This selects the client
profile Phantasm should treat as the default when a runtime consumer relies on config
rather than hard-coding a profile selection.
Valid values for default_client are the names present in
clients.toml. The shipped built-ins are generic_mcp,
codex, claude_code, and hermes.
clients.toml
version = "v1"
# User-defined profiles must inherit from exactly one built-in profile.
# Built-ins: generic_mcp, codex, claude_code, hermes
#
# Example:
# [profiles.codex_readonly]
# inherits = "codex"
# display_name = "Codex Read Only"
# allow_authoritative_writes = false
The top-level file key is version. Custom profiles live under
[profiles.<name>] sections.
version
Type: quoted string. Default: "v1". This is the client-profile schema
version, and only v1 is accepted today.
inherits
Type: quoted string. Required inside every custom profile section. The value must be
one built-in profile: generic_mcp, codex,
claude_code, or hermes.
display_name
Type: quoted string. Optional. If omitted, Phantasm derives a display name from the profile section name by replacing underscores with spaces.
allow_suggestions
Type: boolean. Optional. Overrides whether the profile can create suggestion-shaped mutations. If omitted, the value is inherited from the built-in parent profile.
allow_authoritative_writes
Type: boolean. Optional. Controls whether the profile can perform authoritative runtime writes. Omitted values inherit from the built-in parent.
allow_sensitive_read
Type: boolean. Optional. Controls whether the profile can perform sensitive reads. Omitted values inherit from the built-in parent.
allow_sensitive_export
Type: boolean. Optional. Controls whether the profile can export sensitive data. Omitted values inherit from the built-in parent.
Built-in profiles
generic_mcpcodexclaude_codehermesHermes provider settings
These settings are local to a Hermes profile and are not part of a project .phantasm/ runtime. The provider configuration hook, invoked by hermes memory setup, creates $HERMES_HOME/phantasm.json and runs phantasm bootstrap "$HERMES_HOME". Direct YAML selection does not invoke that hook; if $HERMES_HOME/.phantasm/state/store.sqlite is missing, bootstrap that profile home explicitly before starting Hermes.
{
"binary": "phantasm",
"request_timeout_seconds": 15,
"queue_flush_timeout_seconds": 5,
"prefetch_char_limit": 8000
}prefetch_char_limit caps read-only recalled context at 8,000 characters. This setting does not configure Hermes context compression; the independently selected context.engine owns that behavior.
Current limitations
- There is no supported post-bootstrap config key for context length or token budget yet.
- There is no model-selection key in the generated runtime config files yet.
- Unknown keys in custom client profile sections are rejected as config errors.
- Comments are supported, but values must still use the expected quoted-string or boolean format.
Related docs
For the Markdown version of this reference, see configuration-reference.md.