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 YOUR_GPG_FINGERPRINT

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 — GPG key fingerprint. Establishes T0 trust tier when verified.

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

The trust constitution of your OS instance. Written once, it governs permissions, trust anchors, and structural operations for multi-agent or collaborative repos.

Human operator

Full governance — including modifying ENTITYFILE itself

Fingerprint hardcoded in src/kernel/identity.rs trust anchors

Verified agent or CI

Write source, run agents, delegate needles. Denied: write-kernel, modify-governance

GPG key cross-signed by a T0 holder

GPG key, not cross-signed

Read everything. Narrow write exceptions. Denied: write-kernel, modify-governance, write-src

GPG key present, check_gpg_cross_signature returns None

No GPG key

Boots; reads everything; all writes denied by pin caps (policy.rs:248)

host_identity::discover() returns no gpg_key

EXAMPLE_ENTITYFILE

ENTITYFILE: v1.0 (GPG chain signed — [email protected])
---
entity:
  name: @project.prime
  key: AAAA1111BBBB2222CCCC3333DDDD4444EEEE5555
  domain: project.prime
  version: 3.0.0
  boot_signature: FFFF0000AAAA1111BBBB2222CCCC3333DDDD4444
  laws:
    - invisible-write
    - ephemeral
    - filesystem
    - OCC
    - invisible-infra
  harness: terminal
  tool_pattern: native Bash
  dialect:
    - tack
    - hay
  fleet:
    alive: 1
    agents: 54
signing_key: 3689831ac67b433093ef15e23431b539e7222961f7f976a14feb268c8058ce6a
signing_algo: ed25519

WHEN_DO_I_NEED_AN_ENTITYFILE?

Solo developer, one machine NO

Solo developer, GPG identity needed NO

Team with shared repo YES

CI pipeline dispatching agents YES

Multiple humans with different trust YES

The Negotiate Protocol

Changes require ceremony. You cannot unilaterally modify `ENTITYFILE` — even as T0.

File an offer describing the change (.ostk/offers/)

Counter-party reviews and responds

Both parties sign with their keys

Merge with --no-ff to preserve ceremony in git history

Authority Chain Flow

T0 (human)

→

kernel

→

agents

Trust flows downward. No agent can elevate its own trust tier. No agent can modify `ENTITYFILE`. The human remains the final authority.

3. .primefile

Location: .ostk/.primefile

The kernel's identity document. Written automatically by the OS, it anchors the identity chain.

The .primefile is dual-signed: once by the kernel's GPG key (T1), and once by the operator's GPG key (T0).

Modifying it manually invalidates the signature and will cause the kernel to refuse to boot.

EXAMPLE_PRIMEFILE

---BEGIN HAYSTACK.PRIME KERNEL DECLARATION---

KERNEL: @project.prime
VERSION: 3.0.0
CREATED: 2026-03-10T00:00:00Z

AUTHORITY:
  Primary: @operator (Human operator, HUMANFILE authority)
  Kernel: @project.prime (Persistent kernel, GOVERNANCE.md authority)
  Co-signers: Both keys required for mutation

KEYS:
  T0 Human Root:
    Name: Your Name <[email protected]>
    Key: AAAA...1111
    Algorithm: ed25519

  T1 Kernel:
    Name: @project.prime (v3.0) <[email protected]>
    Key: BBBB...2222
    Algorithm: ed25519

LINEAGE:
  Root: @operator GPG signature
  Co-sign: @project.prime GPG signature
  Chain: Unbroken from 2026-03-10

---SIGNATURES BELOW---

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 GPG key registry: T0 human root, T1 kernel, T1 CI. Algorithm and cross-signature info.

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

SIGNATURE_VERIFICATION

TERMINAL

$ gpg --verify .ostk/.primefile.asc .ostk/.primefile
$ gpg --verify .ostk/.primefile.t0.asc .ostk/.primefile

Both verifications must pass. A single-signature primefile (T1 only) is not trusted.

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"

[authorization]
github_gpg_required = true
trust_tiers = ["T0:dual-signed", "T1:cross-signed", "T2:gpg-not-cross-signed", "T3:anonymous"]

[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 = ["invisible-write", "ephemeral", "filesystem", "OCC", "invisible-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 Override trust tier resolution. Bypasses GPG detection. Used by CI/tests. Auto-detected

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.0.0+)

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