# Kastor

> A declarative language and toolchain for AI agents that lets you define agents, tools, and prompts in typed HCL, then generate framework projects or deploy to hosted platforms with plan/apply semantics.

Kastor describes itself as "Terraform for AI agents" — a declarative language and Go-based toolchain that brings infrastructure-as-code discipline to AI agent development. It is an open-source project under the Apache 2.0 license, currently in early development at v0.0.1-alpha, created in July 2026 by the GitHub user weirdGuy.

## What It Is

Kastor addresses a gap the project README identifies: agents today are defined imperatively inside frameworks like LangGraph or CrewAI, or assembled in platform UIs like OpenAI Assistants or Bedrock Agents, with no vendor-neutral, versionable, reviewable source of truth. Kastor provides that source of truth through `.agent`, `.tool`, and `.prompt` files written in typed HCL (HashiCorp Configuration Language), plus a Go toolchain with two distinct paths:

- **`kastor build`** — compiles the declarative spec into a runnable project for a target framework (LangGraph is the first supported target)
- **`kastor plan` / `kastor apply`** — reconciles agents as long-lived resources on hosted platforms, with local state files, three-way diffs, and drift detection

The design is explicitly not another agent runtime or framework; it sits above them as a spec and compilation layer.

## How the Two Paths Work

The **build path** takes a directory of `.agent`, `.tool`, and `.prompt` files and generates a complete runnable project. For LangGraph, `kastor build --target langgraph .` writes a Python project (with `main.py`, `requirements.txt`, and a generated `README.md`) to a declared output directory. Generated output is reproducible from the spec and is not committed to source control.

The **plan/apply path** mirrors Terraform's workflow. `kastor plan` performs a pure read — comparing the spec, the local state file, and the remote platform — and surfaces attribute-level diffs and out-of-band drift warnings without touching any remote resources. `kastor apply` then reconciles the spec onto the target platform. A built-in in-memory platform is available for local experimentation with no credentials required.

## Architecture and Spec Design

Agents in Kastor are small declarative blocks that declare a model reference, a system prompt, a list of tools, and typed input/output contracts. Tools reference MCP server URIs (e.g., `mcp://search-server/tavily_search`), keeping the spec vendor-neutral while deferring server connection details to deployment-time configuration via `mcp_servers.json`. Model references use symbolic names (`model.fast`) resolved in a `kastor.hcl` workspace file, so swapping providers requires only a config change, not a spec rewrite.

The full design is documented in `SPEC.md` in the repository. `CLAUDE.md` documents day-to-day development conventions.

## Current Status: v0.0.1-alpha

The project published its first alpha release on July 8, 2026. Working capabilities as of that release include:

- Parsing `.agent`, `.tool`, `.prompt`, and `kastor.hcl` files
- Reference validation and prompt variable checking
- LangGraph code generation (`kastor build`)
- `kastor plan`, `kastor apply`, and `kastor destroy` against the built-in in-memory platform
- Two working examples: a weather agent and a content scheduler agent

Planned for v0 but not yet implemented: hosted platform providers, with OpenAI Assistants listed first, followed by AWS and Azure targets. The platform-reconciliation path for real hosted platforms is described as "in design."

## Installation and Setup

Kastor can be installed via Homebrew (`brew tap weirdGuy/tap && brew install kastor`), a curl install script that verifies release checksums, `go install` with Go 1.26+, or by downloading a release archive directly. The quickstart for the weather example requires Go 1.26+, Python 3.11+, an OpenAI API key, and a Tavily API key for the MCP-backed web search tool.

## Features
- Declarative HCL-based agent, tool, and prompt definitions
- kastor build: compile specs to runnable LangGraph projects
- kastor plan: three-way diff of spec, state, and remote platform
- kastor apply / kastor destroy: reconcile agents on hosted platforms
- Drift detection for out-of-band remote changes
- Typed input/output contracts for agents
- MCP server URI-based tool references
- Symbolic model references for vendor-neutral specs
- Built-in in-memory platform for local testing without credentials
- Reference validation and prompt variable checking at compile time
- Deterministic code generation enforced by tests
- Homebrew, install script, and go install support

## Integrations
LangGraph, OpenAI Assistants (planned), AWS Bedrock Agents (planned), Azure (planned), Tavily MCP server, MCP (Model Context Protocol)

## Platforms
MACOS, API, CLI

## Pricing
Open Source

## Version
v0.0.1-alpha

## Links
- Website: https://www.getkastor.dev
- Documentation: https://github.com/weirdGuy/kastor/blob/main/SPEC.md
- Repository: https://github.com/weirdGuy/kastor
- EveryDev.ai: https://www.everydev.ai/tools/kastor