.env.example

# shellcheck shell=sh
# shellcheck disable=SC2034
# Neotoma Environment Variables (local-only mode)
# Copy this file to .env and fill in values as needed.

# =============================================================================
# Server Configuration
# =============================================================================
# Repo path is stored in ~/.config/neotoma by neotoma init (or set NEOTOMA_REPO_ROOT at runtime to override).

# MCP server port (stdio mode)
# NEOTOMA_PORT=3000
PORT=3000

# HTTP Actions server port (or set NEOTOMA_HTTP_PORT at runtime)
HTTP_PORT=3080

# =============================================================================
# Inspector (visual control plane served at /inspector by default)
# =============================================================================
# The Inspector SPA is bundled into the npm package at dist/inspector/ and
# mounted at /inspector automatically. Override with these env vars:

# Disable the Inspector mount and landing-page link entirely.
# NEOTOMA_INSPECTOR_DISABLE=1

# Point the landing page at an externally hosted Inspector (no local mount).
# NEOTOMA_PUBLIC_INSPECTOR_URL=https://inspector.example.com

# Serve a custom Inspector build from this directory instead of the bundled one.
# NEOTOMA_INSPECTOR_STATIC_DIR=/path/to/inspector/dist

# Change the URL path where the Inspector is mounted (default: /inspector).
# NEOTOMA_INSPECTOR_BASE_PATH=/inspector

# Full Inspector SPA root for CLI browser links (`neotoma inspector admin unlock`). When unset, defaults to
# {API origin}{NEOTOMA_INSPECTOR_BASE_PATH} (e.g. http://localhost:3080/inspector). Set for Vite-only dev, e.g.:
# NEOTOMA_INSPECTOR_BASE_URL=http://localhost:5175/inspector

# Disable only the bundled fallback (keeps STATIC_DIR and PUBLIC_URL working).
# NEOTOMA_INSPECTOR_BUNDLED_DISABLE=1

# Re-read Inspector index.html on each request, no-store for /inspector assets, and inject a 2s poll that reloads when build output mtimes change (index.html + assets/*; dev / dev:full:prod set this).
# NEOTOMA_INSPECTOR_LIVE_BUILD=1

# Inspector standalone Vite dev server port (`inspector/` package; default 5175 to avoid clashing with root marketing Vite on 5173/5174).
# VITE_INSPECTOR_DEV_PORT=5175
# INSPECTOR_DEV_PORT=5175

# Frontend URL for CORS
# NEOTOMA_FRONTEND_URL=http://localhost:5195
# FRONTEND_URL=http://localhost:5195

# WebSocket MCP bridge port
# NEOTOMA_WS_PORT=8280
WS_PORT=8280

# API authentication (code reads NEOTOMA_BEARER_TOKEN; ACTIONS_BEARER_TOKEN is a legacy alias kept for backwards compat)
NEOTOMA_BEARER_TOKEN=your-actions-bearer-token-here

# MCP auth settings
NEOTOMA_CONNECTION_ID=your-connection-id-here
MCP_TOKEN_ENCRYPTION_KEY=your-encryption-key-here

# Cursor signed stdio shim (scripts/run_neotoma_mcp_signed_stdio_dev_shim.sh). Prefer
# setting these in ~/.cursor/mcp.json "env" for Cursor; .env is sourced by the shim
# when present. See docs/developer/mcp/proxy.md and docs/developer/mcp_cursor_setup.md.
# NEOTOMA_MCP_USE_LOCAL_PORT_FILE=1
# NEOTOMA_MCP_LOCAL_HTTP_PORT_PROFILE=dev
# NEOTOMA_MCP_PORT_PROBE_MS=1200
# MCP_PROXY_DOWNSTREAM_URL=http://127.0.0.1:3080/mcp

# Host URL settings (optional)
# NEOTOMA_HOST_URL=https://your-tunnel.example.com
# Production MCP/API (Fly): set to the public origin, e.g. https://mcp.neotoma.io
# HOST_URL=https://your-tunnel.example.com
# API_BASE_URL=http://localhost:3080

# MCP root landing page (`GET /`) behavior. Overrides the default mode
# detection, which resolves to: explicit env > sandbox (NEOTOMA_SANDBOX_MODE=1)
# > loopback request > "personal". Valid values: sandbox, personal, prod, local.
# NEOTOMA_ROOT_LANDING_MODE=personal
#
# Base URL used by the root landing page to link back to the marketing docs
# site. All nav items (e.g. /install, /connect) are prefixed with this URL.
# NEOTOMA_PUBLIC_DOCS_URL=https://neotoma.io

# HTTP server keep-alive tuning (milliseconds). Increase if MCP/Inspector sessions
# drop unexpectedly behind a reverse proxy (Cloudflare Tunnel, ngrok, etc.).
# Node 18+ defaults keepAliveTimeout to 5 s; proxies often idle for 60-300 s.
# headersTimeout must exceed keepAliveTimeout to avoid a Node.js race condition.
# NEOTOMA_KEEPALIVE_TIMEOUT_MS=120000
# NEOTOMA_HEADERS_TIMEOUT_MS=125000

# Smithery / MCP registry: override static server card JSON (optional). Default card is built from tool_definitions.
# NEOTOMA_MCP_SERVER_CARD_JSON={"serverInfo":{"name":"neotoma","version":"0.0.0"},"authentication":{"required":true,"schemes":["oauth2"]},"tools":[],"resources":[],"prompts":[]}

# =============================================================================
# Local Storage Configuration
# =============================================================================
# NEOTOMA_DATA_DIR=./data
# NEOTOMA_RAW_STORAGE_DIR=./data/sources
# NEOTOMA_EVENT_LOG_PATH=./data/logs/events.log
# NEOTOMA_LOGS_DIR=./data/logs
# NEOTOMA_EVENT_LOG_MIRROR=false

# =============================================================================
# OpenAI Configuration (Optional)
# =============================================================================
OPENAI_API_KEY=sk-your-api-key-here

# =============================================================================
# Frontend Configuration (Vite)
# =============================================================================
# Vite loads .env* from the repository root (see vite.config.ts envDir), not frontend/.
# Mode-specific overrides:
#   .env.development.local — local dev server (vite); set VITE_UMAMI_WEBSITE_ID_DEV (and optional VITE_UMAMI_URL_DEV).
#   .env.production.local   — optional local production builds; CI uses GitHub Actions env/secrets.
VITE_API_BASE_URL=http://localhost:3080
# VITE_WS_PORT=8280
# VITE_LOCAL_MCP_URL=ws://127.0.0.1:8280/mcp
# VITE_MCP_URL=ws://your-mcp-server.com/mcp
# VITE_AUTO_SEED_RECORDS=true
# Umami — values must come from your environment; nothing is defaulted in the app.
# Production / vite build: origin (no trailing slash) + website UUID from your Umami project.
# VITE_UMAMI_URL=
# VITE_UMAMI_WEBSITE_ID=
# Vite dev server only (separate Umami "website" for localhost / dev host):
# VITE_UMAMI_WEBSITE_ID_DEV=
# Optional dev-only script origin (otherwise VITE_UMAMI_URL is used in dev):
# VITE_UMAMI_URL_DEV=
# Google API credentials (server-side; set via neotoma site configure or here)
# GOOGLE_APPLICATION_CREDENTIALS=
# GOOGLE_OAUTH_CREDENTIALS=.creds

# Set at runtime when needed: NEOTOMA_ENV=development|production

# =============================================================================
# MCP Bridge (Optional)
# =============================================================================
# NEOTOMA_MCP_CMD=node
# MCP_CMD=node
# NEOTOMA_MCP_ARGS=["dist/index.js"]
# MCP_ARGS=["dist/index.js"]
#
# When "1" or "true", MCP initialize sends the compact instruction block
# (same body as the runtime fallback when instructions.md is unreadable)
# instead of the full fenced block from docs/developer/mcp/instructions.md.
# Use for dual-host setups where the client already loads workspace
# .cursor/rules/neotoma_*.mdc (e.g. Cursor + ateles). Do not use for MCP-only
# clients that depend on the full shipped block.
# NEOTOMA_MCP_COMPACT_INSTRUCTIONS=1

# =============================================================================
# Cursor Cloud API (Optional)
# =============================================================================
CURSOR_CLOUD_API_KEY=your-cursor-cloud-api-key-here
# CURSOR_CLOUD_API_URL=https://api.cursor.com

# =============================================================================
# GitHub Issues integration
# =============================================================================
# Issues are filed via the GitHub API using credentials from the GitHub CLI (gh).
# These env vars provide overrides for CI/scripts or non-default configurations.
#
# Explicit GitHub token override (CI, scripts); bypasses gh CLI resolution.
# NEOTOMA_ISSUES_GITHUB_TOKEN=
#
# Target GitHub repository for issues (default: markmhendrickson/neotoma).
# Override to markmhendrickson/neotoma-docs-private for dev builds.
# NEOTOMA_ISSUES_REPO=markmhendrickson/neotoma
#
# Reporting mode: proactive | consent | off (session-scope override).
# NEOTOMA_ISSUES_REPORTING_MODE=proactive
#
# Staleness threshold for implicit sync on reads (milliseconds, default 300000 = 5min).
# NEOTOMA_ISSUES_SYNC_STALENESS_MS=300000
#
# Target Neotoma instance URL for issue submission (canonical store).
# All issues (public and private) are submitted here. GitHub is optional mirror.
# Default when unset: https://neotoma.markmhendrickson.com (override for local/dev).
# NEOTOMA_ISSUES_TARGET_URL=https://neotoma.markmhendrickson.com
#
# GitHub Webhook secret for verifiable actor provenance (POST /github/webhook).
# When set, the server verifies X-Hub-Signature-256 on incoming webhook payloads.
# When unset, the /github/webhook route returns 503 Service Unavailable.
# GITHUB_WEBHOOK_SECRET=

# -----------------------------------------------------------------------------
# ACCESS POLICIES (per entity-type guest access control)
# -----------------------------------------------------------------------------
# Override entity-type access policies via environment variables.
# Pattern: NEOTOMA_ACCESS_POLICY_<ENTITY_TYPE_UPPERCASED>=<mode>
# Modes: closed (default), read_only, submit_only, submitter_scoped, open
#
# NEOTOMA_ACCESS_POLICY_ISSUE=submitter_scoped
# NEOTOMA_ACCESS_POLICY_CONVERSATION=submitter_scoped
# NEOTOMA_ACCESS_POLICY_CONVERSATION_MESSAGE=submitter_scoped

# -----------------------------------------------------------------------------
# [DEPRECATED] Netlify -> Neotoma forwarder (agent.neotoma.io only)
# -----------------------------------------------------------------------------
# This section is deprecated. The feedback pipeline has been replaced by
# the GitHub Issues integration (see NEOTOMA_ISSUES_* variables above).
# These variables are retained temporarily for backward compatibility with
# the sandbox report system which shares some infrastructure.
#
# ---------- AAuth signing (agent.neotoma.io -> local Neotoma) ----------
# Private JWK used by the Netlify forwarder to sign outbound requests per
# RFC 9421 (HTTP Message Signatures). Must be ES256 (EC P-256) or EdDSA
# (OKP Ed25519). Generate with:
#   node -e 'require("jose").generateKeyPair("ES256",{extractable:true}).then(async ({publicKey,privateKey})=>{const pk=await require("jose").exportJWK(privateKey);const pb=await require("jose").exportJWK(publicKey);pk.alg="ES256";pk.use="sig";pk.kid="agent-site-"+Date.now();pb.alg="ES256";pb.use="sig";pb.kid=pk.kid;console.log("AGENT_SITE_AAUTH_PRIVATE_JWK="+JSON.stringify(pk));console.log("AGENT_SITE_JWKS_JSON="+JSON.stringify({keys:[pb]}));})'
# AGENT_SITE_AAUTH_PRIVATE_JWK={"kty":"EC","crv":"P-256","x":"...","y":"...","d":"...","kid":"agent-site-20260422","alg":"ES256","use":"sig"}
#
# Optional overrides. Default sub is agent-site@neotoma.io and default
# iss is https://agent.neotoma.io. The kid falls back to the value
# embedded in the private JWK when unset.
# AGENT_SITE_AAUTH_SUB=agent-site@neotoma.io
# AGENT_SITE_AAUTH_ISS=https://agent.neotoma.io
# AGENT_SITE_AAUTH_KID=agent-site-20260422
# AGENT_SITE_AAUTH_TOKEN_TTL_SEC=300
#
# Public JWKS served at agent.neotoma.io/.well-known/jwks.json. Must
# contain the PUBLIC counterpart of AGENT_SITE_AAUTH_PRIVATE_JWK (no `d`
# / `p` / `q` / etc). The jwks function sanity-strips private members
# before serving, but keep this variable public-only to avoid surprises.
# AGENT_SITE_JWKS_JSON={"keys":[{"kty":"EC","crv":"P-256","x":"...","y":"...","kid":"agent-site-20260422","alg":"ES256","use":"sig"}]}

# =============================================================================
# Security (Optional)
# =============================================================================
# Attribution policy — controls how the server treats writes without a
# verified agent identity. Default is "allow" for compatibility. For hosted or
# multi-tenant deployments, prefer "warn" (log + accept) or "reject" (block).
# See docs/reports/security_audit_2026_04_22.md S-7.
# NEOTOMA_ATTRIBUTION_POLICY=warn
# NEOTOMA_ATTRIBUTION_POLICY_JSON={"observations":"warn","sources":"reject"}
#
# Strict AAuth verification — when "1", signed requests that fail signature
# verification return 401 instead of continuing as unauthenticated. Unsigned
# requests still pass through to OAuth / Bearer flows. See S-6.
# NEOTOMA_AAUTH_STRICT=1
#
# Strict-require AAuth for specific agent subjects. Comma-separated list of
# subjects that MUST present a valid AAuth signature when a request claims
# that identity via `X-Agent-Label`. A missing signature or a signature with
# a different `sub` returns 401. See docs/subsystems/agent_capabilities.md.
# NEOTOMA_STRICT_AAUTH_SUBS=agent-site@neotoma.io
#
# Agent-capability scoping is now driven by `agent_grant` entities managed
# in the Inspector under "Agents → Agent grants" (or via standard MCP /
# REST entity-store calls when an agent holds the bootstrap capability).
# The previous environment variables NEOTOMA_AGENT_CAPABILITIES_JSON,
# NEOTOMA_AGENT_CAPABILITIES_FILE, NEOTOMA_AGENT_CAPABILITIES_ENFORCE, and
# the committed `config/agent_capabilities.default.json` registry have
# been removed in favour of grants. Setting any of those NEOTOMA_AGENT_*
# variables now causes startup to fail with a structured error pointing
# at the upgrade command:
#
#   neotoma agents grants import --owner-user-id <usr_…>
#       [--file path/to/agent_capabilities.json]
#
# Re-runs are idempotent on `(match_sub, match_iss, match_thumbprint)`.
# See docs/subsystems/agent_attribution_integration.md (§ Per-agent
# capability scoping) for the lifecycle and admission semantics.
#
# Rate limit for write endpoints (/store, /correct, /entities/merge,
# /observations/create). Per-user or per-IP, per minute. See S-8.
# NEOTOMA_WRITE_RATE_LIMIT_PER_MIN=120
#
# Optional extra Content-Security-Policy connect-src entries (comma-
# separated). Only set this when you host the API on a different origin from
# the UI and the browser needs to reach it. See S-9.
# NEOTOMA_CSP_CONNECT_SRC=https://api.my-neotoma.example,https://telemetry.example
#
# Official cross-origin Inspector-embed allowlist (comma-separated host
# origins, scheme + host + optional port, NO path). When set, each listed
# origin may iframe `/embed/graph` directly (Neotoma emits
# `Content-Security-Policy: frame-ancestors 'self' <origins>` and drops
# `X-Frame-Options` on `/embed/*`) AND its browser may `fetch()` the two graph
# read endpoints (`/entities/query`, `/retrieve_graph_neighborhood`)
# cross-origin (scoped CORS: exact-origin echo, no credentials, POST+OPTIONS
# only). No other endpoints are CORS-enabled — `/store`,`/correct`,… stay
# unreachable cross-origin. Data access still requires the normal auth (a
# read-only bearer or a `read_only` guest access policy). SECURE BY DEFAULT:
# leave unset for byte-identical `'self'`/`SAMEORIGIN` locked-down behavior.
# See docs/subsystems/inspector_embed_cross_origin.md.
# NEOTOMA_EMBED_ALLOWED_ORIGINS=https://hub.opschudding.app
#
# Production error verbosity — when "1", include Error.message detail and
# stack traces in responses / logs. Default off in production. See S-5.
# NEOTOMA_VERBOSE_ERRORS=0
# NEOTOMA_LOG_STACKS=0

# =============================================================================
# AAuth hardware attestation — Linux TPM 2.0 (FU-4 / packages/aauth-tpm2)
# =============================================================================
# These variables only take effect when the optional `@neotoma/aauth-tpm2`
# native package is installed (Linux x64/arm64 with libtss2 + /dev/tpmrm0).
# On any other host they are ignored and the CLI falls back to the
# software-tier signer.
#
# Override the persistent TPM 2.0 handle used to anchor the AIK. Set this
# when integrating with a pre-provisioned fleet whose handles are managed
# externally; otherwise the CLI defaults to 0x81010000.
# NEOTOMA_AAUTH_TPM2_HANDLE=0x81010000
#
# Override the TPM hierarchy for key generation. Defaults to `owner` so
# end-user installs can rotate without touching the endorsement hierarchy.
# Permitted values: owner | endorsement.
# NEOTOMA_AAUTH_TPM2_HIERARCHY=owner
#
# Gate hardware-bound smoke tests in `packages/aauth-tpm2/`. Tests skip
# when this is not "1"; CI on hosts without /dev/tpmrm0 must NOT set this.
# NEOTOMA_AAUTH_TPM2_TEST_ENABLED=0

# =============================================================================
# AAuth hardware attestation — Windows TBS / NCrypt (FU-5 / packages/aauth-win-tbs)
# =============================================================================
# These variables only take effect when the optional `@neotoma/aauth-win-tbs`
# native package is installed (Windows x64/arm64 with the Microsoft Platform
# Crypto Provider exposing a usable TPM 2.0 chip). On any other host they
# are ignored and the CLI falls back to the software-tier signer.
#
# Override the NCrypt key storage provider. Defaults to the Microsoft
# Platform Crypto Provider. Only override when integrating with a vendor
# CSP that exposes the same NCrypt surface (rare).
# NEOTOMA_AAUTH_WIN_TBS_PROVIDER=Microsoft Platform Crypto Provider
#
# Override the NCrypt key name used to anchor the AIK. Defaults to a stable
# per-install name so re-running `neotoma auth keygen --hardware` reuses
# the same TPM-resident key. Set this to integrate with a fleet whose key
# names are managed externally.
# NEOTOMA_AAUTH_WIN_TBS_KEY_NAME=neotoma-aauth-aik
#
# Override the NCrypt key scope. Defaults to `user` so non-administrative
# installs work out of the box; set to `machine` for service / fleet
# installs that need the key under HKLM. Permitted values: user | machine.
# NEOTOMA_AAUTH_WIN_TBS_SCOPE=user
#
# Gate hardware-bound smoke tests in `packages/aauth-win-tbs/`. Tests skip
# when this is not "1"; CI on hosts without TBS / a usable TPM must NOT
# set this.
# NEOTOMA_AAUTH_WIN_TBS_TEST_ENABLED=0

# =============================================================================
# AAuth hardware attestation — YubiKey PKCS#11 (FU-6 / packages/aauth-yubikey)
# =============================================================================
# These variables only take effect when the optional `@neotoma/aauth-yubikey`
# native package is installed AND `libykcs11` (the Yubico PKCS#11 provider,
# part of YubiKey Manager / yubico-piv-tool) is reachable on the host AND a
# YubiKey 5 series device is connected. On any other host they are ignored
# and the CLI falls back to the next backend in the ladder (or the software
# signer). YubiKey is a portable fallback across darwin / linux / win32 —
# prefer the platform-native backends (Secure Enclave on darwin, TBS on
# win32, libtss2 on linux) when available; YubiKey is selected when those
# backends decline (no SE / no TPM / virtualised host) or when operators
# pin via NEOTOMA_AAUTH_HARDWARE_BACKEND=yubikey.
#
# Override the path to libykcs11. The binding searches a platform-specific
# list of well-known locations (e.g. /Library/Yubico/lib/libykcs11.dylib on
# macOS, /usr/lib/x86_64-linux-gnu/libykcs11.so.2 on Debian/Ubuntu,
# C:\Program Files\Yubico\Yubico PIV Tool\bin\libykcs11.dll on Windows);
# only override when YubiKey Manager is installed in a non-standard prefix.
# NEOTOMA_AAUTH_YUBIKEY_PKCS11_PATH=/usr/local/lib/libykcs11.so
#
# Pin to a specific YubiKey serial number when multiple YubiKeys are
# connected. The decimal serial number is printed by `ykman info` /
# `ykman list`. Without this override the binding picks the first YubiKey
# returned by `C_GetSlotList(true, ...)`.
# NEOTOMA_AAUTH_YUBIKEY_SERIAL=12345678
#
# Inject the PIV PIN non-interactively. NEVER log this value, NEVER persist
# it to signer.json, and NEVER commit it to dotfiles or shell history. Three
# failed PIN attempts lock the YubiKey; recover via
# `ykman piv access change-pin --puk`. Without this variable the binding
# prompts on stdin (TTY only) — non-interactive callers (CI, daemons) MUST
# either set this variable or arrange for a session-scoped login that
# unlocks slot 9c via PIV's `PIN ONCE` policy.
# NEOTOMA_AAUTH_YUBIKEY_PIN=
#
# Gate hardware-bound smoke tests in `packages/aauth-yubikey/`. Tests skip
# when this is not "1"; CI on hosts without a YubiKey + libykcs11 must NOT
# set this. The smoke suite refuses to prompt interactively, so callers
# must pair this with NEOTOMA_AAUTH_YUBIKEY_PIN.
# NEOTOMA_AAUTH_YUBIKEY_TEST_ENABLED=0

# =============================================================================
# AAuth attestation revocation (FU-7 / src/services/aauth_attestation_revocation.ts)
# =============================================================================
# Per-format revocation hooks consult these variables AFTER chain validation
# succeeds. Apple Secure Enclave attestations call Apple's anonymous-
# attestation revocation endpoint; WebAuthn-packed and TPM2 attestations use
# the standard X.509 OCSP path, with CRL fallback when the leaf advertises a
# CRL Distribution Point but no OCSP responder. Revocation failures are
# surfaced under decision.attestation.revocation_status. The default mode is
# `disabled` until the v0.11.0 release flips it to `log_only`; v0.12.0 will
# default to `enforce`.
#
# Operational mode:
#   - disabled  — skip all revocation lookups (preserves v0.10.x behaviour;
#                 default for v0.10.x).
#   - log_only  — run lookups, surface the result in diagnostics, but never
#                 demote the resolved tier (default for v0.11.0).
#   - enforce   — demote `hardware` to `software` with reason=`revoked` when
#                 a lookup returns a revoked status (or, when fail-open is
#                 disabled below, when the responder returns `unknown`).
#                 Default in v0.12.0.
# NEOTOMA_AAUTH_REVOCATION_MODE=disabled
#
# Cache TTL (seconds) for in-memory revocation outcomes. Outcomes are keyed
# by the SHA-256 fingerprint of the attestation leaf so re-issued tokens
# from the same agent share a cache entry. Default: 3600 (1 hour). Setting
# this to 0 or a non-numeric value reverts to the default.
# NEOTOMA_AAUTH_REVOCATION_CACHE_TTL_SECONDS=3600
#
# Per-lookup network timeout (milliseconds). Floors at 100ms. Default: 1500.
# NEOTOMA_AAUTH_REVOCATION_TIMEOUT_MS=1500
#
# Fail-open vs fail-closed when the responder returns `unknown` (network
# error, parse error, missing AIA / CDP). When `1` (default) `unknown` is
# treated as `good` for tier-resolution purposes; when `0`/`false` (and the
# mode is `enforce`) `unknown` is treated as `revoked` and the tier is
# demoted. Operators running in `enforce` mode on hosts with reliable
# upstream connectivity may set this to `0` to harden the policy.
# NEOTOMA_AAUTH_REVOCATION_FAIL_OPEN=1
#
# Optional override for Apple's anonymous-attestation revocation endpoint.
# The default points at Apple's documented production endpoint. Override
# only when running in a sandboxed test environment that mirrors the
# endpoint shape (POST { "serial_numbers": [...] } -> { "revoked": [...] }).
# NEOTOMA_AAUTH_APPLE_REVOCATION_URL=https://data.appattest.apple.com/v1/revoked-list

# =============================================================================
# Testing (Optional)
# =============================================================================
# NEOTOMA_ACTIONS_DISABLE_AUTOSTART=0
# BRANCH_PORTS_FILE=.branch-ports