README
¶
Kastor
Kastor is "Terraform for AI agents." Agents today are defined imperatively inside frameworks (LangGraph, CrewAI) or clicked together in platform UIs (OpenAI Assistants, Bedrock Agents) — there is no vendor-neutral, versionable, reviewable source of truth. Kastor provides one: a typed, declarative spec (.agent, .tool, .prompt files in HCL) and a Go toolchain with two paths — kastor build generates runnable projects for target frameworks, and kastor plan / kastor apply reconcile agents as long-lived resources on hosted platforms, with state, diffs, and drift detection.
The full design lives in SPEC.md.
Install
Homebrew:
brew tap weirdGuy/tap && brew install kastor
Install script (verifies the release checksum, installs to /usr/local/bin or ~/.local/bin, never sudo):
curl -fsSL https://raw.githubusercontent.com/weirdGuy/kastor/main/scripts/install.sh | sh
With Go 1.26+:
go install github.com/weirdGuy/kastor/cmd/kastor@latest
Or download an archive for your platform from the releases page, verify it against checksums.txt, and put the kastor binary on your PATH.
Quickstart: build the weather example
Prerequisites: Go 1.26+, Python 3.11+, an OpenAI API key, and a Tavily API key (the example's search tool runs against Tavily's hosted MCP server).
Compile the spec to a LangGraph project:
go build ./cmd/kastor
./kastor validate examples/weather/
./kastor build examples/weather/
kastor build writes the generated project to examples/weather/gen/langgraph (the target's declared output). Generated output is not committed: it is reproducible from the spec, and codegen determinism is enforced by tests.
Set up the generated project:
cd examples/weather/gen/langgraph
python3 -m venv .venv
. .venv/bin/activate
pip install -r requirements.txt
The example's web_search tool is pinned to an MCP server and tool by its spec URI, mcp://search-server/tavily_search. How to reach that server is deployment configuration, not spec: create mcp_servers.json in the working directory (or point the KASTOR_MCP_CONFIG env var at a file elsewhere). For Tavily's hosted server:
{
"search-server": {
"transport": "streamable_http",
"url": "https://mcp.tavily.com/mcp/?tavilyApiKey=tvly-YOUR-KEY"
}
}
The URL embeds your API key, which is why mcp_servers.json is gitignored — treat it as a secret, never commit it. Also note the spec URI's last path segment (tavily_search) must name a tool the server actually advertises, or calls fail with "does not expose tool".
Export the model credential (the example's model "fast" block uses provider openai):
export OPENAI_API_KEY=sk-...
Run the agent:
python3 main.py weather --inputs '{"location": "Lisbon", "date": "tomorrow"}'
It prints the agent's declared output contract as JSON:
{
"weather": "..."
}
The generated README.md inside gen/langgraph owns the run-the-project side in full: every agent's inputs and outputs, tool bindings, and MCP configuration.
One v0 caveat (SPEC.md §3.2/§4): agent.weather's optional forecast_context input references agent.forecast's output. That reference is validated at compile time and orders the dependency graph, but generated code does not run the upstream agent for you — if you want the context, run forecast yourself and pass its summary via --inputs.
Development
go build ./... # build everything
go test ./... # run all tests
SPEC.md is the source of truth for design decisions; CLAUDE.md documents the day-to-day conventions.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
kastor
command
|
|
|
internal
|
|
|
build
Package build is the codegen engine (SPEC.md §6): it runs a codegen target's Generator over a loaded module and syncs the generated files into the target's output directory.
|
Package build is the codegen engine (SPEC.md §6): it runs a codegen target's Generator over a loaded module and syncs the generated files into the target's output directory. |
|
build/buildtest
Package buildtest provides test helpers that hold generators to the engine's determinism guarantee (see package build).
|
Package buildtest provides test helpers that hold generators to the engine's determinism guarantee (see package build). |
|
build/langgraph
Package langgraph generates a runnable LangGraph (Python) project from a loaded Kastor module — the codegen path of SPEC.md §1 (issue #12).
|
Package langgraph generates a runnable LangGraph (Python) project from a loaded Kastor module — the codegen path of SPEC.md §1 (issue #12). |
|
diff
Package diff produces unified diffs for kastor fmt's -diff output.
|
Package diff produces unified diffs for kastor fmt's -diff output. |
|
graph
Package graph builds the dependency DAG over a loaded module's blocks (SPEC.md §4, §6): references and depends_on entries become edges, cycles are compile errors, and a deterministic topological order is exposed for build/apply consumption.
|
Package graph builds the dependency DAG over a loaded module's blocks (SPEC.md §4, §6): references and depends_on entries become edges, cycles are compile errors, and a deterministic topological order is exposed for build/apply consumption. |
|
module
Package module loads every Kastor file in a directory tree into one module (SPEC.md §2), builds the module-wide symbol table, and resolves all captured references against it.
|
Package module loads every Kastor file in a directory tree into one module (SPEC.md §2), builds the module-wide symbol table, and resolves all captured references against it. |
|
parser
Package parser decodes Kastor source files into the typed structs in internal/schema using hashicorp/hcl/v2.
|
Package parser decodes Kastor source files into the typed structs in internal/schema using hashicorp/hcl/v2. |
|
provider
Package provider is the target-agnostic plan/apply engine (SPEC.md §6): it renders a loaded module into desired resource configurations, compares them three ways (spec vs.
|
Package provider is the target-agnostic plan/apply engine (SPEC.md §6): it renders a loaded module into desired resource configurations, compares them three ways (spec vs. |
|
provider/providertest
Package providertest provides an in-memory Provider for testing the plan/apply engine and CLI without a real platform (mirroring buildtest for the codegen engine).
|
Package providertest provides an in-memory Provider for testing the plan/apply engine and CLI without a real platform (mirroring buildtest for the codegen engine). |
|
schema
Package schema defines the typed configuration structs that parsed Kastor files decode into.
|
Package schema defines the typed configuration structs that parsed Kastor files decode into. |
|
state
Package state owns the kastor.state.json file (SPEC.md §5): the record of which remote resource each block address maps to and the configuration last applied to it, used by kastor plan/apply for three-way comparison and drift detection.
|
Package state owns the kastor.state.json file (SPEC.md §5): the record of which remote resource each block address maps to and the configuration last applied to it, used by kastor plan/apply for three-way comparison and drift detection. |