Foundry

Agent orchestration framework. Context layers, capability gating, multi-thread pipelines, real-time operator dashboard.

bun install
bun run setup
bun run start

Open http://localhost:4500.

For source-bound Claude Code and Codex credentials, see native runtime authentication.

How Foundry fits with Kingdom, Oracle, Archive and agent-session, and how far the end-to-end journey works today: system map.

What this is

Foundry is a framework for building agent systems where you control the context, permissions, and routing — not just the prompt.

• Context layers — stackable context slices with staleness and caching. Agents see what you decide they should see.
• Classify → Route → Execute pipeline — incoming messages are classified, routed to the right executor with the right context slice, and traced end-to-end.
• Capability gate — agents request permission before dangerous operations. Policies map each capability to allow, prompt or deny. Prompts surface in the viewer for human approval.
• Multi-thread hierarchy — spawn child threads with inherited or isolated context. Herald observes across threads and detects duplication, contradiction, convergence.
• Viewer dashboard — three-panel operator UI. Thread tree with prompt badges, live event stream, trace inspector, layer bands, intervention corrections. Not a log viewer — a control surface.

Structure

packages/
  core/     @inixiative/foundry-core   — engine primitives, zero external deps
  foundry/  @inixiative/foundry        — framework, providers, viewer, adapters

Core is usable standalone. It includes context layers, agents, middleware, signals, thread, harness, tracing, hooks, and lightweight adapters (file, sqlite, http, markdown).

Foundry adds opinions: session management, LLM providers (Anthropic, OpenAI, Gemini, Claude Code), the viewer, heavy-infra adapters (Postgres, Redis), and higher-order agents (Planner, Herald, Corpus Compiler).

Setup

Requires Bun (v1.0+).

git clone https://github.com/inixiative/foundry.git
cd foundry
bun install
bun run setup

Setup is interactive — picks your LLM provider and model, creates .foundry/settings.json, writes .env.local with your API key, and scaffolds a starter config (3 context layers, classifier → router → executor pipeline, file-based memory).

Provider choices come from the shared registry: Anthropic, OpenAI, Google Gemini, Claude Code CLI and Codex. See team readiness and the current roadmap before enabling a shared team instance.

Foundry is subscription-only by default: the Claude Code worker and GPT-6 Luna decisions (through the Codex CLI) use the logins already on the machine, so no API key is needed. Log in with claude and codex login first. API-key providers require "apiTokens": true in .foundry/settings.json; see subscription decisions.

Environment variables

# Only with "apiTokens": true — pick one provider
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
GEMINI_API_KEY=AI...

# Optional
DATABASE_URL=postgresql://...   # Postgres persistence
REDIS_URL=redis://...           # Redis adapter
VIEWER_PORT=4500                # Dashboard port (default: 4500)

Local ports come from the @inixiative/config port registry (Foundry is block 5: viewer 4500, Postgres 5932, Redis 6879, MuninnDB 8975/8976; bunx @inixiative/config ports foundry).

Running

bun run doctor       # Inspect existing setup without starting agents or making provider calls
bun run start        # Production — loads config, starts viewer + harness
bun run setup        # Reconfigure (additive — edit agents, layers, sources, projects)
bun run demo         # Demo mode with sample data

Send messages through the viewer chat or the API:

curl -X POST http://localhost:4500/api/messages \
  -H 'Content-Type: application/json' \
  -d '{"message": "What is the project structure?"}'

Daemon

bun run daemon:install runs Foundry as a LaunchAgent. Before boot it starts the docker-compose services your DATABASE_URL, REDIS_URL and MUNINN_URL point at on this machine.

The daemon runs a release, not your working checkout: an exported commit with its own install under .foundry/releases/<sha>. With "daemon": { "autoUpdate": "apply" } in settings, it builds origin/main as a candidate (at startup and every updateCheckSeconds, default 300) and restarts onto it once no job is running. A candidate that boots becomes stable; one that fails to boot is marked failed, never retried, and the daemon relaunches on stable. "check" only logs that origin/main moved. Release state is in .foundry/releases/state.json.

A boot of stable that fails on changed settings sets them aside as .foundry/settings.rejected-<ts>.json and restores the last settings that booted.

Testing

bun run test           # Core + Foundry tests
bun run test:core      # Core engine tests
bun run test:foundry   # Framework tests
bun run test:db        # Postgres tests (requires DATABASE_URL)

Key concepts

Context layers

import { ContextLayer, ContextStack } from "@inixiative/foundry-core";

const system = new ContextLayer({ id: "system" });
await system.load(mySource);

const stack = new ContextStack();
stack.add(system);

const context = stack.assemble({ maxTokens: 8000 });

Capability gate

import { ActionQueue, CapabilityGate } from "@inixiative/foundry-core";

const queue = new ActionQueue();
const gate = new CapabilityGate({ defaults: "prompt", capabilities: { "file:read": "allow" } }, queue);

// This blocks until a human approves in the viewer
await gate.require("file:write", {
  agentId: "code-writer",
  threadId: "main",
  detail: "Writing to /src/index.ts",
});

Pipeline

import { Harness, Thread } from "@inixiative/foundry-core";

const thread = new Thread({ id: "main" });
thread.agents.set("classifier", myClassifier);
thread.agents.set("router", myRouter);
thread.agents.set("executor", myExecutor);

const harness = new Harness(thread);
harness.setClassifier("classifier");
harness.setRouter("router");
harness.setDefaultExecutor("executor");

const result = await harness.dispatch("Fix the login bug");
// result.trace — full execution trace with timing
// result.output — agent response

Viewer

The viewer is a Preact-based dashboard served by Hono. No build step — vanilla JS with htm tagged templates.

• Left panel: thread tree (with prompt badges), layers, agents, live event stream
• Center panel: conversation chat, pending prompt cards with approve/reject buttons
• Right panel: trace inspector, span details, layer detail, intervention corrections

Keyboard shortcuts: 1-3 switch panels, ? help, s settings, a analytics.

License

• packages/core/ — MIT
• packages/foundry/ — BSL 1.1 (converts to MIT on 2030-04-06)

See LICENSE for details.

Session archives

Foundry captures its durable sessions into this machine's local Archive (bun run archive setup starts it), which publishes onward to hosted Archives reached through Kingdom. See setup and retrieval.

Usage telemetry and context budgets

Claude cache reads/writes and original usage tags flow through sessions, providers, traces, token tracking, and persisted analytics. Foundry defaults Claude Code to a 200k native compaction window with an 80% trigger (roughly 160k). See usage telemetry and native context budgets for configuration, counter semantics, and the limits of native compaction.