config: replace dotenv with varlock for env validation

- Add .env.schema with types, @required, @sensitive decorators for all env vars
- Remove dotenv from slack-bridge, env vars now injected via varlock run
- start.sh validates with `varlock load` before launching
- startup-cleanup.sh uses `varlock run` for bridge tmux session
- deploy.sh deploys .env.schema to ~/.config/.env.schema
- setup.sh installs varlock binary
- Update CONFIGURATION.md with schema validation docs

Replaces blind dotenv loading with schema-validated startup. Catches
wrong token prefixes, missing required vars, and invalid emails before
any connections are attempted.

Author: benvinegar

.env.schema

@@ -0,0 +1,112 @@
+# Hornet agent configuration schema
+# See CONFIGURATION.md for details on each variable.
+#
+# Secrets live at ~/.config/.env (600 perms, never committed).
+# This schema is deployed to ~/.config/.env.schema alongside the .env file.
+#
+# @defaultSensitive=true
+# @defaultRequired=false
+# ---
+
+# ── LLM Access ───────────────────────────────────────────────────────────────
+
+# API key for the LLM provider (Anthropic, OpenAI, or a proxy)
+# @required @type=string
+# @docs(https://docs.anthropic.com/en/api/getting-started)
+OPENCODE_ZEN_API_KEY=
+
+# ── GitHub ───────────────────────────────────────────────────────────────────
+
+# GitHub Personal Access Token (fine-grained, scoped to agent repos)
+# @required @type=string(startsWith=ghp_)
+# @docs(https://github.com/settings/tokens)
+GITHUB_TOKEN=
+
+# ── Slack ────────────────────────────────────────────────────────────────────
+
+# Slack bot OAuth token
+# @required @type=string(startsWith=xoxb-)
+# @docs("Create a Slack app", https://api.slack.com/apps)
+SLACK_BOT_TOKEN=
+
+# Slack app-level token (Socket Mode)
+# @required @type=string(startsWith=xapp-)
+SLACK_APP_TOKEN=
+
+# Comma-separated Slack user IDs allowed to interact with the agent
+# Bridge refuses to start without at least one user ID.
+# @required @sensitive=false @type=string
+# @example="U01ABCDEF,U02GHIJKL"
+SLACK_ALLOWED_USERS=
+
+# ── Email Monitor ────────────────────────────────────────────────────────────
+
+# AgentMail API key
+# @type=string
+# @docs(https://app.agentmail.to)
+AGENTMAIL_API_KEY=
+
+# Agent's monitored email address
+# @sensitive=false @type=email
+HORNET_EMAIL=
+
+# Shared secret for email sender authentication
+# @type=string
+HORNET_SECRET=
+
+# Comma-separated sender email allowlist
+# @sensitive=false @type=string
+# @example="you@example.com,teammate@example.com"
+HORNET_ALLOWED_EMAILS=
+
+# ── Sentry (optional) ───────────────────────────────────────────────────────
+
+# Sentry API bearer token
+# @type=string
+# @docs(https://sentry.io/settings/account/api/auth-tokens/)
+SENTRY_AUTH_TOKEN=
+
+# Sentry organization slug
+# @sensitive=false @type=string
+SENTRY_ORG=
+
+# Slack channel ID for Sentry alerts
+# @sensitive=false @type=string(startsWith=C)
+SENTRY_CHANNEL_ID=
+
+# ── Slack Channels (optional) ───────────────────────────────────────────────
+
+# Additional monitored channel (responds to all messages, not just @mentions)
+# @sensitive=false @type=string(startsWith=C)
+SLACK_CHANNEL_ID=
+
+# ── Kernel (optional) ───────────────────────────────────────────────────────
+
+# Kernel cloud browser API key
+# @type=string
+# @docs(https://kernel.computer)
+KERNEL_API_KEY=
+
+# ── Tool Guard ───────────────────────────────────────────────────────────────
+
+# Unix username of the agent
+# @sensitive=false @type=string
+HORNET_AGENT_USER=hornet_agent
+
+# Agent's home directory
+# @sensitive=false @type=string
+HORNET_AGENT_HOME=/home/hornet_agent
+
+# Path to admin-owned source repo (enables source repo write protection)
+# @sensitive=false @type=string
+HORNET_SOURCE_DIR=
+
+# ── Bridge ───────────────────────────────────────────────────────────────────
+
+# Local HTTP API port for outbound Slack messages
+# @sensitive=false @type=port
+BRIDGE_API_PORT=7890
+
+# Target pi session ID (auto-detects control-agent if unset)
+# @sensitive=false @type=string
+PI_SESSION_ID=

CONFIGURATION.md

@@ -2,6 +2,12 @@
 
 All secrets and configuration live in `~/.config/.env` on the agent's home directory (`/home/hornet_agent/.config/.env`). This file is `600` permissions and never committed to the repo.
 
+## Schema Validation
+
+Hornet uses [Varlock](https://varlock.dev) to validate environment variables at startup. The schema (`.env.schema`) is committed to the repo and deployed to `~/.config/.env.schema` alongside the secrets file. It defines types, required/optional status, and sensitivity for each variable.
+
+`start.sh` runs `varlock load` to validate before launching — the agent won't start with missing or malformed variables. The bridge uses `varlock run` to inject validated env vars. Varlock must be installed on the agent system (`brew install dmno-dev/tap/varlock` or `curl -sSfL https://varlock.dev/install.sh | sh -s`).
+
 ## Required Variables
 
 ### LLM Access
@@ -123,4 +129,4 @@ sudo -u hornet_agent pkill -u hornet_agent
 sudo -u hornet_agent ~/runtime/start.sh
 ```
 
-The bridge and all sub-agents source `~/.config/.env` on startup via `set -a && source ~/.config/.env && set +a`.
+The bridge and all sub-agents load `~/.config/.env` on startup. If varlock is installed, variables are validated against `.env.schema` before injection.

bin/deploy.sh

@@ -52,6 +52,7 @@ if [ "$DRY_RUN" -eq 0 ]; then
     [ -f "$HORNET_SRC/bin/$script" ] && cp --no-preserve=ownership "$HORNET_SRC/bin/$script" "$STAGE_DIR/bin/$script"
   done
   [ -f "$HORNET_SRC/pi/settings.json" ] && cp --no-preserve=ownership "$HORNET_SRC/pi/settings.json" "$STAGE_DIR/settings.json"
+  [ -f "$HORNET_SRC/.env.schema" ] && cp --no-preserve=ownership "$HORNET_SRC/.env.schema" "$STAGE_DIR/.env.schema"
   chmod -R a+rX "$STAGE_DIR"
 fi
 
@@ -210,6 +211,20 @@ if [ -f "$STAGE_DIR/settings.json" ]; then
   fi
 fi
 
+# ── Env schema ───────────────────────────────────────────────────────────────
+
+echo "Deploying env schema..."
+
+if [ -f "$STAGE_DIR/.env.schema" ]; then
+  if [ "$DRY_RUN" -eq 0 ]; then
+    as_agent cp "$STAGE_DIR/.env.schema" "$HORNET_HOME/.config/.env.schema"
+    as_agent chmod 644 "$HORNET_HOME/.config/.env.schema"
+    log "✓ .env.schema → ~/.config/.env.schema"
+  else
+    log "would copy: .env.schema → ~/.config/.env.schema"
+  fi
+fi
+
 # ── Version stamp + integrity manifest ────────────────────────────────────────
 
 echo "Stamping version..."

pi/skills/control-agent/startup-cleanup.sh

@@ -76,7 +76,7 @@ fi
 # Start fresh slack-bridge
 echo "Starting slack-bridge with PI_SESSION_ID=$MY_UUID..."
 tmux new-session -d -s slack-bridge \
-  "set -a && source ~/.config/.env && set +a && export PATH=\$HOME/opt/node-v22.14.0-linux-x64/bin:\$PATH && export PI_SESSION_ID=$MY_UUID && cd ~/hornet/slack-bridge && exec node bridge.mjs"
+  "export PATH=\$HOME/.varlock/bin:\$HOME/opt/node-v22.14.0-linux-x64/bin:\$PATH && export PI_SESSION_ID=$MY_UUID && cd ~/runtime/slack-bridge && exec varlock run --path ~/.config/ -- node bridge.mjs"
 
 # Wait for bridge to come up
 sleep 3

setup.sh

@@ -176,6 +176,13 @@ done
 echo "=== Installing Slack bridge dependencies ==="
 (cd "$REPO_DIR/slack-bridge" && npm install)
 
+echo "=== Installing varlock ==="
+if command -v varlock &>/dev/null; then
+  echo "varlock already installed, skipping"
+else
+  curl -sSfL https://varlock.dev/install.sh | sh -s
+fi
+
 echo "=== Deploying from source to runtime ==="
 # deploy.sh runs as admin (needs read access to source, write+chown to agent home).
 # It copies extensions, skills, bridge, and utility scripts to runtime dirs.

slack-bridge/bridge.mjs

@@ -17,7 +17,8 @@
  *   BRIDGE_API_PORT        - outbound API port (default: 7890)
  */
 
-import "dotenv/config";
+// Env vars loaded and validated by varlock (via `varlock run` or `start.sh`).
+// No dotenv/varlock import needed — env is already in process.env.
 import { App } from "@slack/bolt";
 import * as net from "node:net";
 import * as fs from "node:fs";

slack-bridge/package-lock.json

@@ -9,7 +9,6 @@
     "test": "node --test security.test.mjs"
   },
   "dependencies": {
-    "@slack/bolt": "^4.6.0",
-    "dotenv": "^17.3.1"
+    "@slack/bolt": "^4.6.0"
   }
 }

slack-bridge/package.json

@@ -14,9 +14,13 @@ set -euo pipefail
 cd ~
 
 # Set PATH
-export PATH="$HOME/opt/node-v22.14.0-linux-x64/bin:$PATH"
+export PATH="$HOME/.varlock/bin:$HOME/opt/node-v22.14.0-linux-x64/bin:$PATH"
 
-# Load secrets
+# Validate and load secrets via varlock
+varlock load --path ~/.config/ || {
+  echo "❌ Environment validation failed — check ~/.config/.env against .env.schema"
+  exit 1
+}
 set -a
 source ~/.config/.env
 set +a