pantheon

Pantheon

An always-on Discord agent harness in Rust, packaged as a NixOS service. Native memory follows UniiChat 0500bf6: immutable paged originals, durable binary summaries, independent main/compactor views, staged coarsening and fresh provider conversations. See the parity contract for verified behavior and explicit implementation differences.

Pantheon includes OpenAI Responses and Anthropic Messages adapters, background-only subagents, prompt steering, durable wakeups and change monitors, and bundled Camoufox windows with a shared profile and separate authenticated noVNC viewers. It runs its own agent loop; Prime Agent is not required.

NixOS

Add this repository as a pinned flake input and import pantheon.nixosModules.default:

services.pantheon = {
  enable = true;
  applicationId = 123456789012345678;
  allowedUsers = [ 123456789012345678 ];
  environmentFile = "/run/secrets/pantheon.env";
  settings.agent = {
    model = "openai/gpt-5.6";
    compactor_model = "openai/gpt-5-mini";
    reasoning = "medium";
  };
};
networking.firewall.interfaces.tailscale0.allowedTCPPortRanges = [
  { from = 6080; to = 6180; }
];

The environment file contains DISCORD_TOKEN and any selected API provider keys (OPENAI_API_KEY / ANTHROPIC_API_KEY; opt-in Z.ai uses ZAI_API_KEY). codex/model instead uses a ChatGPT subscription login from the service account's Codex credential cache; the Nix package includes the official CLI for login/refresh. Keep secrets outside the Nix store. The service account owns /var/lib/pantheon; its configured workspace is the tool working directory. Browsers, Python driver, Xvfb, x11vnc and noVNC are all part of the pinned Nix closure, with no runtime browser download. See provider authentication for existing-login reuse and service setup.

See persistent service installation and migration for moving an existing instance with its memory, chats, skills and workspace intact, including running the Nix package as a boot-enabled systemd user service.

Create a Discord bot, enable the Message Content Intent, and invite it with bot and applications.commands scopes and View Channel, Send Messages, Read Message History and Embed Links permissions. Only configured allowedUsers can invoke it. DMs are admitted directly; guild messages must mention the bot. Mention the bot again to steer a running guild turn. Replies from other bots are ignored.

Development

nix develop
cp pantheon.toml.example pantheon.toml
# Edit application_id, allowed_users, and workspace; load protected credentials into your environment.
cargo run -- --config pantheon.toml doctor
cargo run -- --config pantheon.toml run

nix run . -- --config /absolute/path/pantheon.toml run uses the complete packaged runtime. Without Nix, the Rust daemon builds with Cargo, but browser actions require the runtime paths described in browser.md. doctor performs local checks without calling paid APIs.

Discord interaction

Slash replies are private. Ordinary prompts and agent output use the originating channel. Progress prose and activity are plain messages; only the completion after all current work has finished replies to the loop's original prompt and notifies its author. Further input steers that loop without replacing its reply target. Fenced activity accumulates consecutive tool events; prose closes the fence, and subsequent events open a new one at the bottom of the conversation. Full fences roll over without dropping events. Named spawns show IDs, model/effort and incoming reports arrive individually as workers finish. Worker tool calls and owned shell/scheduler notifications remain private; the main timeline shows coordinator actions and delivered worker reports. Input reactions show 📥 received, 🧠 submitted to the model, and ✅ settled; steers share the loop's final settlement. Typing covers inference, context settling and background work. Slash commands use branded embeds with structured fields. Activity exposes names and status rather than arguments/output. Long replies split on Discord's UTF-16 budget with code fences preserved. Provider reasoning can be shown with agent.show_reasoning=true, without persisting it locally (GLM native reasoning is never displayed).

Root and worker runs have no model-cycle limit by default (agent.max_steps = 0, including when omitted). Set a positive value, such as max_steps = 128, to cap model-response cycles per run; one cycle may contain multiple tool calls. Existing positive values keep their cap after upgrading: remove that setting or set it to 0 to opt into unlimited cycles. Runs still stop on normal completion, /stop, service shutdown or errors; request/tool timeouts and other resource limits remain active. The curator also defaults to unlimited model cycles, with independent optional draft/reviewer caps and a fifteen-minute whole-pass deadline (configuration). Unlimited cycles can consume ongoing provider quota until completion or cancellation.

Optional Claude Code background tasks are disabled by default and require a manually installed, directly authenticated CLI on the daemon PATH; Pantheon does not bundle it through Nix.

Every subagent runs in the background and reports to the master. There are no foreground children or wait/poll tools. By default the root has the full execution toolkit: it handles short or tightly connected work directly and delegates substantial independent work, parallel investigations and noisy exploration. Workers inherit the settled global coordinator memory at spawn and can zoom into earlier findings. Set agent.coordinator_root = true for a strict coordinator that delegates all execution; existing configurations that explicitly set it retain that behavior. Root and workers have web search and fetch: hosted search with cited source URLs, and credential-free HTTP fetching with a durable, revalidating cache. Browser windows share one durable pantheon-shared profile and X display; each window group gets its own loopback VNC and noVNC listener on 0.0.0.0. Browser handoff pauses automation until explicit resume. Returned LAN/Tailscale URLs are candidates; routing and remote firewall access cannot be established by enumerating local interfaces.

Idle workers and coordinators leave default agent listings after one hour (agent.agent_idle_seconds = 3600). Their identities, histories and schedules remain durable. All agents can discover and message same-channel workers; coordinators can also find and message known neighboring coordinators using list_agents(kind="coordinators") and tell(id="channel:<id>", message="..."). include_archived=true finds hidden identities; tell automatically restores and wakes them, as do user input and scheduled notifications. Memory stays channel-owned; coordinator messages explicitly carry information across channels.

Root and workers have skill discovery/loading and MCP integrations. Bundled guides cover product research, browser activities, learning and engineering. Bundled and configured SKILL.md guides seed a durable evolving library. Each channel has an independent curator queue: after substantial work settles and the channel stays idle, a read-only memory fork stages improvements for parallel reviewers. Approved changes emit activity receipts and accumulate context notes without waking an idle orchestrator. The system prompt contains every active skill with frozen usage/refinement counts; catalogue refreshes happen only on fresh turns after the configured idle period. /skills provides content, resources, history and rollback; /curator shows queue and review status. MCP supports stdio and Streamable HTTP tools, resources and prompts, with role/channel controls and durable retrieval of large results. Schemas stay fixed while external catalogs enter tool results. The shared behavior guide treats explicit requests about the user's own environment and authorized credential entry as ordinary work, carries tasks through to evidence, and scales process to everyday interactions.

State and checks

Cache diagnostics distinguish provider-reported reuse from local prefix stability. Transport diagnostics and retries correlate provider failures with timing, stream progress and underlying transport causes; configurable linear backoff recovers transient failures without replaying completed tools. Tool activity shows compact previews, line counts, exit codes and original-message updates for detached shells. Steering queues behind requested tool execution; /stop explicitly cancels work.

Back up the state directory. memory/main/ and tree/ contain immutable daily JSONL records; operational SQLite journals contain inbox/outbox, tasks and schedules; subagents/ holds private child traces; browsers/pantheon-shared/profile/ holds shared browser state, and the other browser directories hold viewer metadata and screenshots. State is never committed to this repository.

cargo fmt --all -- --check
cargo clippy --all-targets -- -D warnings
cargo test --locked --all-targets
nix flake check

Stop the service before offline memory operations:

pantheon --config pantheon.toml export --output memory.html
pantheon --config pantheon.toml import --file note.txt

Crash recovery resumes queued prompts, wakeups and unsent output. Interrupted turns are reported rather than replaying uncertain tool side effects. Discord delivery is at least once; nonce deduplication has a finite remote window. Complete provider responses are rendered per step; token-by-token prose streaming is not implemented yet. Live bot/model validation requires your credentials.

See architecture, memory, Discord, browsers, web tools and authentication for invariants, tradeoffs and recovery details.

Development and releases

Use Conventional Commits, for example feat(browser): share login state or fix(runtime): deliver a completion once. PR titles and development commits are checked in CI. Cargo.toml is the version source; Cargo.lock must agree and the Nix package reads that version directly.

Like Thoth, PRs to main require a stable SemVer increase unless labeled no-release for changes that do not warrant a release. Protected main requires an up-to-date PR with passing version, rust and nix checks, squash/rebase merges, and no force push or administrator bypass. On main, Rust formatting, Clippy, tests, Nix builds and the live packaged-browser test must pass before CI tags the exact validated commit and publishes a GitHub release. Existing tags never move; an interrupted release can be repaired by rerunning at its original commit. Install a release with nix run github:GustavoWidman/pantheon/v0.5.0 or pin that tag in your NixOS flake. Service deployment remains controlled by the consuming NixOS configuration.

Rust and Nix checks run when a PR is opened, updated or reopened, not on development-branch pushes. The release workflow reuses those checks on main before publishing.

Both root and workers can own wakeups and monitors. Shell commands return a background job ID after five seconds by default; their results reach the owning agent’s durable inbox. An idle worker resumes under its existing ID. Successful worker turns with running shells or queued inbox work keep their report private until that work finishes; future scheduled wakeups and monitor intervals do not hold reports. See architecture for delivery, cancellation and recovery behavior, and browser ownership for shared storage and handoff details.

Model discovery and chat-local overrides cover /model and /reasoning autocomplete and the agent’s models catalog tool. pantheon models performs live discovery without inference. Agents can compare dated official API prices and Codex credit rates, including cache/context bands; included subscription quota and API references remain separate.

Nix CI compilation

After installing Nix, CI uses DeterminateSystems/magic-nix-cache-action to cache build outputs in GitHub Actions across runs. GitHub Actions caching is explicitly enabled and FlakeHub caching is disabled; no additional credentials or OIDC permissions are required. The reusable release checks use the same cache setup. Cache misses still build normally, and the first run may be cold.

The Nix package keeps its optimized Rust executable (pantheon.unwrapped) separate from the browser-worker/runtime wrapper. Cargo's source set includes Cargo.toml, Cargo.lock, src/, embedded skills/, and Rust integration tests; changes to documentation, Python tests or the browser worker do not recompile Rust. Browser-worker changes still produce a new final package and run the packaged-browser smoke test. tests/test_nix_packaging.py checks these cache boundaries by evaluating real derivations after source mutations (Nix required).

The installed executable retains the release profile, including thin LTO. Nix runs all Rust test targets and doctests using Cargo's normal test profile rather than release LTO: Rust tests require unwinding, so they cannot reuse the release binary's abort-on-panic build. This avoids expensive redundant test optimization without dropping tests. The Rust CI job still runs formatting, Clippy, Rust and Python tests, and the Nix job still builds the package/runtime and exercises the packaged browser. Opt-in credential-dependent tests remain opt-in.

Superseded PR check runs are cancelled; reusable release checks use a unique run group and are never cancelled by a newer PR or release run.

Discord supports receiving and sending attachments, native image/document input where supported, durable send_file deliveries, and managed cleanup. Incoming attachments have no harness size ceiling.

Z.ai / GLM supports explicit worker/main model selection through the exact Coding Chat Completions endpoint, with model-specific image capabilities and separate existing hosted web search. It is disabled by default.