local-first agent runtime. one binary. memory, sandboxing, observation, security, package management. agents run on top.
forge is the operating system for AI agents. you write a config file. forge handles everything else.
forge init my-agent
forge run my-agent.toml
forge list
forge status
forge validate my-agent.toml
forge remember my-agent alice uses linux
forge recall my-agent
forge forget my-agent alice uses
forge logs my-agent-1234567890
forge kill my-agent-1234567890
one binary. no cloud. no daemon. no build step. boring tech (Go, SQLite, TOML).
today you wire 15 MCP servers into a config file by hand. you hope they work. you can't see what your agent does. you can't sandbox it. you can't give it memory that survives restarts. you can't manage multiple agents.
forge fixes all of that. it's the layer between you and the agent.
| manual config | forge | |
|---|---|---|
| start an agent | edit json, hope | forge run agent.toml |
| memory | none | cairn (sqlite, temporal) |
| sandboxing | none | vault (fs overlay, env sanitize, net policy) |
| observation | console.log | observer (trace tools, sqlite log) |
| MCP management | manual json | smith (install, compose, secure) |
| security | hope | mcprobe (prompt injection, tool shadowing) |
| multiple agents | impossible | forge list, forge kill |
| notifications | drowned | pulse (filtered, prioritized) |
forge ties the Valtors ecosystem together. each tool is a kernel module. forge is the kernel.
[agent]
name = "my-agent"
model = "claude-sonnet"
command = "claude"
[memory]
backend = "cairn"
path = "~/.local/share/forge/my-agent/memory.db"
[sandbox]
enabled = true
allow = ["./src"]
net = ["github.com"]
[mcp]
servers = ["filesystem", "git", "valtors/cairn"]
[observe]
log = true
trace = trueforge/
internal/
config/ TOML config, load, save, defaults
agent/ process manager, start/stop/list agents
sandbox/ fs overlay, env sanitizer, network policy
observe/ tool call logger, trace history, search
mcp/ MCP server resolver (npm, git, local)
memory/ temporal sqlite store (remember, recall, forget)
main.go CLI entry point
commands.go command handlers (run, list, logs, kill, init)
forge also manages agent memory directly from the CLI:
forge remember my-agent alice uses linux
forge recall my-agent
forge recall my-agent alice
forge forget my-agent alice uses
memory persists across restarts. stored in sqlite. one file per agent.
- loads your agent.toml
- sets up sandbox (fs overlay, strips secrets from env, blocks paths)
- initializes memory (sqlite, temporal store)
- resolves and starts MCP servers (npm, git, local)
- starts the agent process
- wires observation (logs every tool call, stores in sqlite)
- agent runs with all services wired up
- you get logs, traces, memory, sandboxing -- all automatic
go install github.com/valtors/forge@latestor build from source:
git clone https://github.com/valtors/forge
cd forge
go build -o forge .# create a new agent config
forge init my-agent
# edit the config
vim my-agent.toml
# run the agent with all services wired
forge run my-agent.toml
# see running agents
forge list
# view logs
forge logs my-agent-1234567890
# stop an agent
forge kill my-agent-1234567890when sandbox is enabled:
- filesystem: agent gets an overlay dir. writes go there. reads only from allowlisted paths.
.ssh,.aws,.env,.gnupgare invisible. - environment: every env var matching token, secret, password, credential, api_key, auth, aws_, azure_, openai, anthropic, stripe, resend, database_url, private_key, github_token, gh_pat -- stripped. agent sees a clean shell.
- network: only allowlisted hosts. everything else refused. wildcard support (
*.npmjs.org).
forge is the runtime. these are the modules:
- cairn -- agent memory. temporal knowledge store in sqlite.
cargo install cairn-memory - vault -- agent sandbox. fs overlay, env sanitizer, net policy.
go install github.com/valtors/vault - observer -- tool call logging. trace tools injected back to agent.
go install github.com/valtors/observer - smith -- MCP package manager. install, compose, secure.
cargo install smith-mcp - mcprobe -- MCP security scanner. prompt injection, tool shadowing, baseline drift.
go install github.com/tamish560/mcprobe - pulse -- notification agent. filtered, prioritized, remembered.
- relay -- one MCP server for files, web, PDFs, images.
npx userelay - reflow -- SSR-safe responsive toolkit for TypeScript.
npm install usereflow
100 tests. 73.3% coverage. all pass.
go test ./... -count=1go. single binary. sqlite (pure-go, no cgo for memory store). toml config. stdlib everything else. boring tech on purpose.
see CONTRIBUTING.md. we welcome contributions of all kinds - bug fixes, new patterns, transport support, docs.
good first issues are labeled good first issue.
MIT. strictly open source. no cloud tier, no enterprise plan, no proprietary fork.