.env.example

# ──────────────────────────────────────────────────────────────────────────────
# koad:io .env.example — complete harness environment variable reference
# ──────────────────────────────────────────────────────────────────────────────
# This file documents every KOAD_IO_*, ENTITY_*, and HARNESS_* env var the
# harness reads. Grouped by subsystem. Each var shows its purpose and default.
#
# Legend:
#   [framework]  = set once in ~/.koad-io/.env, applies to all entities
#   [per-entity] = set in ~/.<entity>/.env, specific to one entity
#   [security]   = critical — can escape the sandbox if misconfigured
#   [runtime]    = set by the launcher / dispatcher at session start, not user
# ──────────────────────────────────────────────────────────────────────────────

# ═══════════════════════════════════════════════════════════════════════════════
# 1. Session / Startup Assembly
# ═══════════════════════════════════════════════════════════════════════════════

# Entity identity — set by the launcher before startup.sh runs. [runtime]
ENTITY=juno

# Working directory passed by caller; startup.sh derives HARNESS_WORK_DIR. [runtime]
# CWD=

# Entity home directory; startup.sh derives from $HOME/.$ENTITY if unset. [runtime]
# ENTITY_DIR=

# Framework root directory. Default: $HOME/.koad-io. [framework]
# KOAD_IO_DIR=$HOME/.koad-io

# If true, entity works from ~/.$ENTITY (rooted / has an office).
# If unset/false, entity works from $CWD (roaming). [per-entity]
# KOAD_IO_ROOTED=true

# Light mode — strips briefs, daemon status, flights, inbox, working-dir listing.
# Use for conversation dispatch where a topic PRIMER replaces heavy context. [per-entity]
# KOAD_IO_STARTUP_LIGHT=0

# Entity role — selects primers/<role>/PRIMER.md at startup. [per-entity]
# KOAD_IO_ENTITY_ROLE=orchestrator

# Extra command directories to scan (colon-separated). Default: forge + framework.
# KOAD_IO_COMMANDS_DIRS=$HOME/.forge/commands:$HOME/.koad-io/commands

# ═══════════════════════════════════════════════════════════════════════════════
# 2. Harness Defaults (free-tier fallback)
# ═══════════════════════════════════════════════════════════════════════════════

# Framework harness defaults — last-resort fallback when the entity's own .env
# does not pin ENTITY_DEFAULT_HARNESS/PROVIDER/MODEL. Free-first: no API key or
# signup needed to reach these defaults. Entity .env can override independently.
# [framework]
KOAD_IO_DEFAULT_HARNESS=opencode
KOAD_IO_DEFAULT_PROVIDER=opencode
KOAD_IO_DEFAULT_MODEL=minimax-m2.5-free

OPENCODE_MODEL="${OPENCODE_MODEL:-opencode/minimax-m2.5-free}"

# ═══════════════════════════════════════════════════════════════════════════════
# 3. Package & Build Paths
# ═══════════════════════════════════════════════════════════════════════════════

# Meteor package directories — colon-separated. [framework]
KOAD_IO_PACKAGE_DIRS=$HOME/.ecoincore/packages:$HOME/.koad-io/packages
METEOR_PACKAGE_DIRS=$KOAD_IO_PACKAGE_DIRS  # DEPRECATED: Meteor compat shim

# ═══════════════════════════════════════════════════════════════════════════════
# 4. ADAS Budget
# ═══════════════════════════════════════════════════════════════════════════════

# Kingdom ceiling — max token_budget.total for any assembled ADAS flight plan.
# Flights exceeding this require override: true + override_requires auth. [framework]
KOAD_IO_ADAS_BUDGET_CEILING=100000

# ═══════════════════════════════════════════════════════════════════════════════
# 5. Messages & Inbox
# ═══════════════════════════════════════════════════════════════════════════════

# Root directory for entity inboxes — each entity gets a subdirectory.
# Default: $HOME/.forge/messages. [framework]
KOAD_IO_MESSAGES_DIR=$HOME/.forge/messages

# ═══════════════════════════════════════════════════════════════════════════════
# 6. Network / DDP (Kingdom Infrastructure)
# ═══════════════════════════════════════════════════════════════════════════════

# Bind IP for kingdom services. Default: 10.10.10.10 (ZeroTier mesh). [framework]
# KOAD_IO_BIND_IP=10.10.10.10

# Daemon port. Default: 28282. [framework]
# KOAD_IO_PORT=28282

# Control-tower port. Default: 28283. [framework]
# KOAD_IO_CONTROL_PORT=28283

# Daemon URL (DDP / REST). Default: http://{BIND_IP}:{PORT}. [framework]
# KOAD_IO_DAEMON_URL=http://10.10.10.10:28282

# Control-tower URL. Default: http://{BIND_IP}:{CONTROL_PORT}. [framework]
# KOAD_IO_CONTROL_URL=http://10.10.10.10:28283

# ═══════════════════════════════════════════════════════════════════════════════
# 7. Runtime Paths
# ═══════════════════════════════════════════════════════════════════════════════

# Where dispatch state lives (flight plans, dispatch.json, followups).
# Default: $HOME/.local/share/koad-io/runtime. [framework]
# KOAD_IO_RUNTIME_PATH=

# Where pi harness session JSONL files are stored. [runtime]
# KOAD_IO_HARNESS_SESSIONS_DIR=

# ═══════════════════════════════════════════════════════════════════════════════
# 8. Lifecycle / Telemetry (HARNESS_* vars — set by launcher, not user)
# ═══════════════════════════════════════════════════════════════════════════════

# Emission ID for the current flight — set by dispatcher. [runtime]
# HARNESS_EMISSION_ID=

# Parent emission ID (for sub-flights). [runtime]
# HARNESS_PARENT_EMISSION_ID=

# Control flight ID (for dispatches). [runtime]
# HARNESS_CONTROL_FLIGHT_ID=

# Flight plan name. [runtime]
# HARNESS_FLIGHT_PLAN=

# Session ID (unique per harness session). [runtime]
# HARNESS_SESSION_ID=

# Conversation ID (groups related sessions). [runtime]
# HARNESS_CONVERSATION_ID=

# Working directory for this session. [runtime]
# HARNESS_WORK_DIR=

# MCP session token for daemon authentication. [runtime]
# KOAD_IO_MCP_SESSION_TOKEN=

# Global telemetry toggle — "1" enables emission inserts to daemon/control-tower.
# Turn off for dry-run/debug sessions. [per-entity]
# KOAD_IO_EMIT=1

# ═══════════════════════════════════════════════════════════════════════════════
# 9. Identity / Footer (UI-only, not security)
# ═══════════════════════════════════════════════════════════════════════════════

# Spirit name override for footer (operator identity). Default: $USER. [per-entity]
# KOAD_IO_SPIRIT=

# Pi provider override (for footer display). Default: $PROVIDER. [runtime]
# ENTITY_PI_PROVIDER=
# KOAD_IO_HARNESS_PI_PROVIDER=

# Pi model override (for footer display). Default: $MODEL. [runtime]
# ENTITY_PI_MODEL=

# ═══════════════════════════════════════════════════════════════════════════════
# 10. Fallback / Circuit Breaker
# ═══════════════════════════════════════════════════════════════════════════════

# Fallback model when context budget exceeds 95%. Default: gpt-4o. [framework]
# KOAD_IO_FALLBACK_MODEL=gpt-4o

# Fallback provider. Default: openai. [framework]
# KOAD_IO_FALLBACK_PROVIDER=

# ═══════════════════════════════════════════════════════════════════════════════
# 11. Bond-Gate — Bypass & Tool Grants
# ═══════════════════════════════════════════════════════════════════════════════
# Each var has a KOAD_IO_ prefix and an optional KOAD_IO_PI_ legacy alias.
# The gate reads both; the KOAD_IO_ form is canonical.
#
# All vars in this section are [security]-critical. Misconfiguration can
# grant unrestricted access that bypasses trust bonds entirely.
#
# Resolution order:
#   1. KOAD_IO_BOND_GATE_BYPASS=1 → full bypass (dev escape hatch)
#   2. Trust bonds on disk → derive scope from signed capabilities
#   3. HARNESS_WORK_DIR → dispatched workspace gets r+w+e lane
#   4. Env lanes (below) → widen active scope without full bypass
#   5. No bonds + no env → deny by default

# FULL BYPASS — grants read/write/exec of /, all tools, all targets.
# NEVER set in production. Dev escape hatch only. [security][per-entity]
# KOAD_IO_BOND_GATE_BYPASS=0

# ── Tool grants (flag: 0/1) ────────────────────────────────────────────
# Set to 1 to open a lane the bond doesn't grant. Set to 0 to defer to bond.
# [security][per-entity]
# KOAD_IO_BOND_GATE_ALLOW_BASH=0
# KOAD_IO_BOND_GATE_ALLOW_DISPATCH=0
# KOAD_IO_BOND_GATE_ALLOW_DISPATCH_FOLLOWUP=0
# KOAD_IO_BOND_GATE_ALLOW_DISPATCH_COMPLETE=0

# ── Interactive overrides (operator consent per-session) ───────────────
# Bond declares interactive capabilities; operator activates by uncommenting.
# These give the entity write/bash/exec access in interactive (UI) sessions.
# [security][per-entity]
# KOAD_IO_BOND_GATE_ALLOW_INTERACTIVE_BASH=1
# KOAD_IO_BOND_GATE_ALLOW_INTERACTIVE_EXEC=1
# KOAD_IO_BOND_GATE_ALLOW_INTERACTIVE_WRITE=1

# ── Tool list grants (name-list: comma or space separated) ─────────────
# Narrow lanes — open individual tools/commands/targets without full bypass.
# [security][per-entity]
# KOAD_IO_BOND_GATE_ALLOW_KOADIO_TOOLS=search,status,koad-io
# KOAD_IO_BOND_GATE_ALLOW_KOADIO_COMMANDS=git,session
# KOAD_IO_BOND_GATE_ALLOW_CHANNEL_MODERATE=*
# KOAD_IO_BOND_GATE_ALLOW_CHANNEL_PARTICIPATE=*
# KOAD_IO_BOND_GATE_ALLOW_DISPATCH_TARGETS=vulcan,muse
# KOAD_IO_BOND_GATE_ALLOW_READ_TOOLS=read,ls,sin
# KOAD_IO_BOND_GATE_ALLOW_WRITE_TOOLS=write,edit

# ═══════════════════════════════════════════════════════════════════════════════
# 12. Bond-Gate — Path & Extension Lanes
# ═══════════════════════════════════════════════════════════════════════════════
# Add read/write/exec paths beyond what the bond grants.
# Colon-separated for paths, comma/space for patterns/extensions.
# [security][per-entity]

# KOAD_IO_HARNESS_READ_PATHS=$HOME/.forge/websites/kingofalldata.com
# KOAD_IO_HARNESS_WRITE_PATHS=$HOME/.forge/websites/kingofalldata.com
# KOAD_IO_HARNESS_EXEC_PATHS=$HOME/.forge/websites/kingofalldata.com

# Blocked path patterns — paths containing these strings cannot be read/written.
# Always appended to the hardcoded defaults (/.env, /.credentials, /.git/, /id/,
# /.ssh/, /auth.json, /secrets/, /secret/, /private/).
KOAD_IO_HARNESS_BLOCKED_PATTERNS=/.env,/.credentials

# Extension filters — restrict which file types can be read/written.
# Empty = all extensions allowed. If non-empty, only listed extensions pass.
# KOAD_IO_HARNESS_READ_EXTENSIONS=
# KOAD_IO_HARNESS_WRITE_EXTENSIONS=

# Blocked extensions — always blocked regardless of path grants. [security]
KOAD_IO_HARNESS_BLOCKED_EXTENSIONS=.asc,.pem,.key,.env,.credentials

# ═══════════════════════════════════════════════════════════════════════════════
# 13. Bash Policy
# ═══════════════════════════════════════════════════════════════════════════════
# Even when bash is allowed, the shell lane is not a blank check. These vars
# configure additional restrictions. [security][per-entity]

# Allow raw curl/wget to daemon/control-tower. Default: 0 (blocked).
# Set to 1 only if you have a specific reason to bypass the typed API tools.
KOAD_IO_BOND_GATE_ALLOW_CURL=0

# Commands denied via bash — comma/space separated. [security]
KOAD_IO_BASH_DENY_COMMANDS=curl,wget,ssh,scp,nc,telnet,ncat,socat

# Regex patterns denied in bash commands — comma/space separated. [security]
KOAD_IO_BASH_DENY_PATTERNS=meteor\\s+publish,docker\\s+rm

# File with one deny pattern per line (for larger lists). [security][per-entity]
# KOAD_IO_BASH_DENY_PATTERNS_FILE=$HOME/.juno/harness/bash-deny-patterns.txt

# Per-entity bash routing JSON — redirects commands to typed tools. [per-entity]
# KOAD_IO_BASH_ROUTING_FILE=$HOME/.juno/harness/bash-routing.json

# ═══════════════════════════════════════════════════════════════════════════════
# 14. Secret Scrubbing
# ═══════════════════════════════════════════════════════════════════════════════

# Skip secret scrubbing of tool results. "1" disables redaction of private keys,
# tokens, passwords, and protected paths from LLM-visible tool output.
# NEVER set to 1 in production — sessions are published to kingofalldata.com.
# [security][per-entity]
KOAD_IO_SKIP_SCRUB=0

# ═══════════════════════════════════════════════════════════════════════════════
# 15. Channel Backend
# ═══════════════════════════════════════════════════════════════════════════════

# Activate SPEC-154/156 channel tools in the pi extension. [per-entity]
# KOAD_IO_CHANNEL_BACKEND=true

# ═══════════════════════════════════════════════════════════════════════════════
# 16. Billing Mode
# ═══════════════════════════════════════════════════════════════════════════════

# "max" = flat-rate subscription, shadow-track. "metered" = per-token, real cost.
# "unknown" = conservative fallback, treated as metered. [per-entity]
# KOAD_IO_BILLING_MODE=metered

# ═══════════════════════════════════════════════════════════════════════════════
# 17. Misc
# ═══════════════════════════════════════════════════════════════════════════════

# Hook debug log — set to 1 to capture payloads at /tmp/<entity>-hook-debug.log.
# KOAD_IO_HOOK_DEBUG=1

# Port prefix for entity services. [per-entity]
# KOAD_IO_PORT_PREFIX=413

# Pi + Codex harness config-dir pins (set per entity or globally when ready).
# KOAD_IO_PI_AGENT_DIR=
# KOAD_IO_CODEX_HOME=