Ingot

Evidence-gated change control for agent instructions.

An agent's skills are instructions it will follow. Ingot
is a local-first library that treats them as what they are: versioned state that needs a review
process. Every skill folder is content-addressed, every proposed change is quarantined until a human
reads the evidence and approves it, and promotion is atomic, snapshots what it replaced, and is
recorded. An MCP server then serves the approved revision of the right skill for each task,
which is what lets a cheap or local model reuse methods that would otherwise need a frontier model.

What the system guarantees:

• A revision names an exact skill. Every file in a skill folder is hashed, so the revision on a
  trace, in a piece of evidence, and on disk are comparable.
• Changes are quarantined. Generated rewrites land in runs/pending/ and cannot route
  traffic until a human approves them.
• Approval needs evidence. A rewrite carries held-out champion-vs-challenger scores, per-case
  deltas, token cost, and a gate verdict; promotion re-checks the evidence still matches disk.
• Promotion is atomic and reversible. The displaced revision is snapshotted and the directory
  swapped by rename; restore any snapshot from the UI or CLI.
• Decisions are audited. Approvals and rollbacks append metadata-only records (action, skill,
  revision, actor, timestamp), never skill text or credentials.

Built for individual users first, ready to share:

• Batteries included. docker compose up starts the router, the change-control UI, and a
  self-hosted Langfuse for traces and experiments. An included Compose override connects Cloud or
  another self-hosted Langfuse without starting the bundled stack.
• Local. Point it at Ollama or vLLM and it runs with no API key; nothing leaves your machine.
• Secure. Hosted calls default to OpenRouter with zero-data-retention routing enforced on every
  request, everything binds localhost, and the shared UI has an optional password gate.
• Easy. A skill is a folder with a SKILL.md. Drop one in and it is live on the next request.

Changes come mostly from you. Ingot also ships an optional candidate generator
that mines real traces for failing skills, drafts rewrites, and measures them on held-out tasks; it
produces proposals, never activations.

Quickstart · Tutorial · How it works ·
Configuration · Architecture ·
Contributing · Security · MIT license

Quickstart

git clone https://github.com/SlanchaAI/ingot.git && cd ingot
cp .env.example .env               # add an OpenRouter key, or point BASE_URL at Ollama (no key)
scripts/fetch_skills.sh all        # fetch ~70 real skills into ./skills (see docs/skill-sources.md)
docker compose up                  # router (:8000), UI (:8080), Langfuse (:3100), and one agent run
docker compose run --rm agent "How do I merge several PDFs into one and add page numbers?"

The change-control UI at localhost:8080 asks for a login; the compose default is admin /
ingot. Change AUTH_PASSWORD in .env before sharing it on your LAN (or set it empty to run
open), see Privacy & security.

docker compose up brings up a self-hosted Langfuse (traces + experiment UI) alongside the router
and UI; trace mining reads from it and has no local fallback, so it fails loudly if no
Langfuse-compatible backend is reachable. To send traces to your own Langfuse without starting the
bundled containers, set LANGFUSE_* and use docker-compose.external-langfuse.yml as documented in
Configuration. Backend, model, and gate
settings live in Configuration.

Then walk through the full loop, from mining a stale Tailwind skill through promotion, in the
Tutorial.

For a hardened open-source Langfuse deployment with agents on other LAN machines, follow
Production setup.

Connect Claude Code or Codex

You can use Ingot with your existing coding agent instead of the bundled demo agent. Start the
stack, then run the setup script for your agent. The Codex connector requires Codex 0.128 or newer,
Node.js 22 or newer, and Python 3. The Claude Code connector requires uv (recommended), or
Python 3.10 or newer with pip and the Langfuse 4.x SDK:

# macOS, install only the dependencies your selected agent needs
brew install node@22       # Codex
brew install uv            # Claude Code
brew install [email protected]   # Codex when python3 is missing, or Claude's fallback runtime

docker compose up -d
./scripts/claude_setup.sh
# or
./scripts/codex_setup.sh

Both scripts are safe to run again. Use --doctor to inspect versions, installed connectors,
configuration, and Langfuse reachability without changing anything. Use --repair to replace a
mismatched MCP registration and reinstall managed dependencies or plugins:

./scripts/claude_setup.sh --doctor
./scripts/claude_setup.sh --repair
./scripts/codex_setup.sh --doctor
./scripts/codex_setup.sh --repair

Each script adds http://localhost:8000/mcp as the user-level ingot MCP server and installs the
official Langfuse observability connector. Claude Code prompts for the Langfuse URL and project keys
after restart only when configuration is incomplete. The setup script supplies LANGFUSE_* values
or the bundled local defaults during installation. The Codex script writes a private
~/.codex/langfuse.json; it defaults to the bundled Langfuse at http://localhost:3100 with the
local demo project keys.

For Langfuse Cloud or another self-hosted project, provide its values when running the Codex setup:

LANGFUSE_BASE_URL=https://cloud.langfuse.com \
LANGFUSE_PUBLIC_KEY=pk-lf-... \
LANGFUSE_SECRET_KEY=sk-lf-... \
./scripts/codex_setup.sh

Set INGOT_MCP_URL if the MCP server is not on localhost. The connectors record prompts, responses,
reasoning summaries, and tool inputs and outputs, including Ingot MCP calls, so do not enable them
for sessions whose contents must not be stored in Langfuse. Their trace-root shapes are accepted by
optimize-mine; untagged turns are attributed to skills by task similarity. See
Bring your own agent for the trace contract and routing behavior.
Tell the agent to call ingot.route_and_load once at the start of each request and follow the
returned skill_body; connecting the MCP server makes the tool available but does not force its use.
Add this as a persistent CLAUDE.md or AGENTS.md rule, not just a one-time chat prompt. See
Make skill loading part of the agent instructions.
For an agent on another machine, see Agent on another LAN machine.
Verify that the services are reachable before starting the agent:

curl http://localhost:8000/mcp                 # an HTTP error response still proves MCP is listening
curl http://localhost:3100/api/public/health  # should return a healthy Langfuse response

How it works

Ingot does three things around your skill library:

• Serve. An MCP server routes each task to the approved revision of the right skill (embedding
  routing on CPU, no GPU) so a weak or local model can reuse a strong method.
• Govern. Every change is quarantined, carries held-out evidence, and needs a human approval;
  promotion is atomic, snapshotted, reversible, and audited.
• Improve. An optional loop mines real traces for failing skills, rewrites them with the SkillOpt
  reflective optimizer, and A/Bs the result on held-out tasks, leaving a reviewable proposal.

The component map is in docs/how-it-works.md; deeper design in
ARCHITECTURE.md.

Documentation

License

MIT, see LICENSE.