CONFIGURATION // CONFIG_AND_ENV

Configuration & Environment

The configuration hierarchy governs identity, trust limits, project-specific settings, and ambient environment variable overrides.

CONFIGURATION_FILES

1. HUMANFILE — Operator identity, defaults, and API keys
2. ENTITYFILE — Governance constitution and authority chains
3. .primefile — Auto-generated kernel root-of-trust anchor
4. ostk.toml — Project-level config overrides
5. Environment Variables — Runtime flags and options

1. HUMANFILE

Location: .ostk/HUMANFILE or ~/.HUMANFILE

Your compiled operator identity. The OS reads this at boot and calibrates to you. This is a governance document representing the human at the terminal.

EXAMPLE_HUMANFILE

IDENTITY yourname
SIGN <verified-identity-evidence>

MODEL claude-opus-4-6
FALLBACK mistral-large-latest

AVAILABLE <<MODELS
claude-sonnet-4-5
claude-opus-4-6
gemini-2.5-pro
mistral-large-latest
MODELS

SECRET <<KEYS
ANTHROPIC_API_KEY
GEMINI_API_KEY
KEYS

DRIVER rust fcp-rust
EMBED codebase
PREPROCESS apple/default

HUMANFILE_DIRECTIVES

IDENTITY REQ Your username. Used in audit attribution and agent identity.

SIGN — Ed25519 multikey or legacy GPG fingerprint used as operator identity evidence. Tier depends on verification and anchor admission.

MODEL REQ Default model for agent sessions. Kernel auto-detects provider from model name.

FALLBACK — Model when primary is unavailable or rate-limited.

AVAILABLE <<MODELS — Heredoc listing all authorized models. Consumed by FROM auto in Agentfiles.

SECRET <<KEYS — Heredoc listing authorized API key names. Keys stored in platform keychain.

DRIVER <type> <name> — FCP driver to load at boot. Internal drivers don't need declaration.

EMBED — Embedding index mode: codebase (full), incremental (git-diff), off.

PREPROCESS — Local model for preprocessing user input via olleh runtime. e.g. apple/default. Fixes grammar, expands tack shorthand before the remote LLM sees it.

TRUST — Trust policy for Agentfile signing. unsigned skips signature requirement.

EXTENDS — Path to parent HUMANFILE for inheritance. Child directives override.

BOOT — Custom boot steps appended after kernel initialization.

VERB — Custom verb registration merged into .language at boot.

SECRET_RESOLUTION_ORDER

BYO_SECRET_MANAGER

secret_cmd inside .ostk/config (e.g. bw, op, pass). User-controlled local file only. Ambient environment variables like OSTK_SECRET_CMD are explicitly ignored to prevent injection/exfiltration.

PLATFORM_KEYCHAIN

macOS: security Keychain access. Linux: secret-tool storage.

ENVIRONMENT_VARIABLE

Fallback to $KEY in shell environment (least secure).

2. ENTITYFILE

Location: .ostk/ENTITYFILE

A project governance document for identity declarations, trust anchors, and structural policy. Effective permissions still come from the identity verifier, tier defaults, active pins, and the execution surface.

Verified project or operator root

No tier-default restrictions; full governance

Verified primefile or trusted Ed25519/DSSE evidence; legacy GPG anchor

T0-endorsed identity

Source writes with kernel-state and governance restrictions

Verified delegated evidence or legacy T0 cross-signature

Identity without T0 endorsement

Governed src/, kernel state, and governance writes denied by default

Recognized identity evidence without trusted endorsement

Anonymous

Kernel-mediated writes denied by default

No verified primefile or other recognized identity evidence

CURRENT_IDENTITY_PATH

Current verification prefers supported Ed25519 and DSSE/OAE identity evidence. Detached .asc and Sigstore-era artifacts remain compatibility paths for projects that already use them; they are not the only way to establish a local root.

Keep the document descriptive. Use ostk boot to see which evidence actually resolved and which default posture is active.

Changing Governance

Governance writes routed through ostk are evaluated against the active identity posture and capability policy. Lower tiers are denied by default; a T0 operator can make an authorized change, while repository review and signature requirements remain explicit project policy.

Identity evidence does not let an agent self-promote. Re-run ostk boot after a governance change to verify the evidence and resulting posture.

3. .primefile

Location: .ostk/.primefile

A project identity document created by ostk init. It records the local root and lineage evidence that boot can verify.

Treat .primefile as verified project identity evidence, not as a universal dual-GPG ceremony. Current projects can use Ed25519/DSSE-compatible evidence; legacy detached GPG material remains a fallback where present.

Manual changes can invalidate the evidence. Use the supported initialization and governance paths, then confirm the resolved tier with ostk boot.

PRIMEFILE_FIELDS

KERNEL Kernel identity name. Default: @project.prime.

VERSION Kernel declaration version.

AUTHORITY Who controls the kernel — primary (human), kernel, and co-signer requirements.

KEYS Trust-key registry, including Ed25519 multikeys and any legacy GPG anchors or cross-signature metadata.

LINEAGE Root of trust chain, co-signers, and chain continuity date.

VERIFY_THE_RESOLVED_EVIDENCE

TERMINAL

$ ostk boot
# Inspect the reported identity evidence, trust tier, and any degraded fallback.

Boot reports the evidence path it can verify. Missing legacy GPG material alone does not imply T3 when verified primefile or other supported identity evidence is present.

4. ostk.toml

Location: ./ostk.toml

The project-level configuration file. Written and maintained by you at the repository root, it controls version bounds, pins, and custom tool rules.

TERMINAL

[project]
name = "ostk-site"
bail = "os-tack/ostk.ai"
kernel = ">=3.0.0, <4.0.0"

# Identity resolution comes from HUMANFILE SIGN evidence
# plus verified primefile evidence; see the trust reference.

[distribution]
mirrors = [
  "https://github.com/os-tack/ostk.ai/releases",
  "https://ostk.ai/releases"
]
verify_signature = true
tarball_pattern = "ostk-{version}-{target}.tar.gz"

[kernel]
boot_mode = "embedded-first"
daemon_lifecycle = "tui-owned"
laws = ["familiar-project", "durable-state", "filesystem", "OCC", "inspectable-infra"]

[onboarding]
steps = ["binary-install", "environment-detect", "humanfile-create", "os-init", "import-offer"]

[pins.default]
read = [".ostk/", ".language"]
write = [".ostk/store/default/"]
execute = "shell(readonly)"
deny = ["write-kernel", "modify-governance"]

[features]
tui = true
agents = true
audit = true
digest = true
embeddings = false

TOML_SECTIONS

[project]

Project name and optional bail lineage (the upstream signed package this project was seeded from). Top-level kernel = ">=X.Y.Z" pin sits alongside.

[authorization]

Declarative trust policy: github_gpg_required, trust_tiers list. Documentary — source of truth is src/kernel/identity.rs trust anchors.

[distribution]

Release mirrors, signature verification, tarball pattern. Used by install scripts and bail fetchers, not the runtime kernel.

[kernel]

boot_mode (embedded-first | daemon-first), daemon_lifecycle, laws. The laws array is documentary — the actual five laws are enforced in code.

[onboarding]

install.sh ceremony steps. Documentary — consumed by the install script, not the kernel.

[pins.*]

Named pin configurations. read/write/execute paths and deny tokens. Parsed by the pin loader at boot.

[features]

Boolean toggles: tui, agents, audit, digest, embeddings. Read at boot to gate subsystem initialization.

[mcp.*]

Historical. MCP servers are declared in HUMANFILE, not ostk.toml — see /docs/mcp for the real path.

5. Environment Variables

Prefix: OSTK_*

Ambient configuration options that live in the shell environment. Most are optional; the kernel boots cleanly with zero environment variables set.

AGENT_IDENTITY

OSTK_AGENT Agent alias. Set by kernel on spawn. Used for audit attribution, heartbeat, gen_table writer. "unknown"

OSTK_PIN Active capability pin name. Loads .ostk/pins/<name>/pin.caps. Tier default

OSTK_TRUST_TIER Trusted test-harness override. It is intentionally ignored in normal untrusted agent processes and cannot grant production tier. Ignored unless the process explicitly enables the trusted test path

OSTK_AGENTFILE Path to Agentfile to load at boot. None

DAEMON_SCHEDULER

OSTK_SCHEDULER_TICK_SECONDS Scheduler tick loop interval. Set to 0 to disable. Disabled

OSTK_SCHEDULER_STUCK_AFTER_SECS Seconds before tick escalates from skipped to stuck in audit. 90

OSTK_SCHEDULER_FORCE_CLEAR_AFTER_SECS Seconds before force-clearing busy flag. 300

DRAIN_RECOVERY

OSTK_DRAIN_SNAPSHOT Controls drain snapshot writes. Set to 0 to disable. Enabled (v7.7.7+)

MODEL_SECRETS

OSTK_MODEL Override default model for ostk run, ostk tack --run, FROM auto. Overrides HUMANFILE. HUMANFILE

OSTK_SECRET_CMD BYO vault command (ambient env variable is ignored for execution bounds in favor of local secret_cmd in .ostk/config). None

DIAGNOSTICS

OSTK_DUMP_REQUEST Directory for full API request JSON dumps. For debugging cache/preload. Disabled

OSTK_DUMP_HANDSHAKE File path for handshake bytes at boot. For debugging byte-stability. Disabled

OSTK_NO_CACHE Set to 1 to disable cache_control breakpoints. Disabled

OSTK_T2_OBSERVER Set to 1 for Hot PR Tier 2 arbitration audit rows. Disabled

SYSTEM

OSTK_STATE_DIR Override state directory name (instead of .ostk). .ostk

OSTK_DIR Absolute path to .ostk directory. Set by kernel for FCP driver subprocesses. Auto

OSTK_REGISTRY_DIR Override global registry directory. Used by CI for isolation. ~/.ostk/

OSTK_PREPROCESS Local model for input preprocessing via olleh runtime. Overrides HUMANFILE PREPROCESS. HUMANFILE

OSTK_TOOL_THRESHOLD Momentum threshold for verb loading from .language. Float 0-1. 0.45