Chronos

A Go framework for building durable, scalable AI agents.
Define agents. Connect any LLM. Let them collaborate.

Install · Quickstart · Docs · Examples · Roadmap

Features

Install

CLI Binary (Linux / macOS / Windows)

curl -fsSL https://raw.githubusercontent.com/spawn08/chronos/main/install.sh | bash

Pre-built binaries for linux/amd64, linux/arm64, darwin/amd64 (Intel), darwin/arm64 (Apple Silicon), windows/amd64, and windows/arm64 are published to GitHub Releases.

Go Module

go get github.com/spawn08/chronos

Build from Source

git clone https://github.com/spawn08/chronos.git && cd chronos
make build    # outputs bin/chronos

Quickstart

YAML config — create .chronos/agents.yaml:

defaults:
  model:
    provider: openai
    api_key: ${OPENAI_API_KEY}
  storage:
    backend: sqlite
    dsn: chronos.db

agents:
  - id: dev
    name: Dev Agent
    model:
      model: gpt-4o
    system_prompt: You are a senior software engineer.
    stream: true
    permission_mode: prompt             # prompt | auto_approve | deny
    reasoning:
      native: true
      effort: medium
      summary: false

chronos repl                                      # interactive streaming chat
chronos run --stream "explain Go interfaces"      # headless token streaming
chronos --permission-mode auto_approve repl       # trusted local session
# At an approval prompt, enter "a" to approve all for this CLI session.

Go builder API:

a, _ := agent.New("chat", "Chat Agent").
    WithModel(model.NewOpenAI(os.Getenv("OPENAI_API_KEY"))).
    WithSystemPrompt("You are a helpful assistant.").
    Build()

resp, _ := a.Chat(ctx, "What is the capital of France?")
fmt.Println(resp.Content)

Graph-based agent:

g := graph.New("pipeline").
    AddNode("greet", func(_ context.Context, s graph.State) (graph.State, error) {
        s["message"] = fmt.Sprintf("Hello, %s!", s["user"])
        return s, nil
    }).
    SetEntryPoint("greet").
    SetFinishPoint("greet")

a, _ := agent.New("hello", "Hello Agent").WithGraph(g).Build()
result, _ := a.Run(ctx, map[string]any{"user": "World"})

Examples

All examples with No API keys run with mock providers or a scripted/offline path — no external calls.

Core

Graph & durability

Memory, knowledge & agent harness

Multi-agent & protocol interop

Sandboxing

Providers & production

Run any example: go run ./examples/<name>/

* k8s_sandbox needs a reachable Kubernetes cluster; with none configured it prints setup guidance and exits cleanly.

Every example that needs a real LLM (coding_agent, graph_with_llm, structured_output, mcp_agent, multi_agent, team_deploy, multi_provider) resolves its provider through examples/internal/providers.Pick(), so any of these env combos works interchangeably:

Supported Providers

OpenAI, Anthropic, Google Gemini, Azure OpenAI, AWS Bedrock, Mistral, Cohere, Ollama, Google Cloud Vertex AI (via an OpenAI-compatible endpoint), and any other OpenAI-compatible endpoint (Together, Groq, DeepSeek, OpenRouter, Fireworks, Perplexity, Anyscale, vLLM, LiteLLM).

Documentation

In-repo feature guides (with detailed run steps) live in docs/:

• Architecture — illustrated layer stack, request/graph/queue flows, HITL, MCP transports, and interfaces (on the docs site)
• Sandbox backends — Process, Container, WASM (WASI), and Kubernetes Job isolation
• MCP transports — connect to MCP servers over stdio and HTTP+SSE
• Eval suites — declare and run evaluation suites from YAML or Go

Full docs at spawn08.github.io/chronos:

• Installation — CLI binary, Go module, build from source
• CLI Install — curl install for all platforms
• Quickstart — First agent in 5 minutes
• Agents — Agent builder, YAML config, capabilities
• Teams — Multi-agent orchestration strategies
• StateGraph — Durable execution with checkpointing
• Tools — Function calling and permissions
• Hooks — Middleware: retry, cache, cost, rate limit
• Storage — All 14 storage and vector adapters

Server & API

chronos serve [addr] (default :8420) starts ChronosOS — the control-plane HTTP server. It exposes a REST API over sessions, checkpoints, traces, schedules, and human-in-the-loop approvals, plus a live SSE event stream, Prometheus metrics, health/readiness probes, and an interactive Swagger UI. It is hardened by default (timeouts, body limits, panic recovery, CORS, rate limiting, graceful shutdown) and stateless, so you can run many replicas behind a load balancer.

chronos serve :8420
open http://localhost:8420/swagger/     # interactive API explorer

Authentication is opt-in (CHRONOS_AUTH=none|jwt|apikey) with JWT (HS256/RS256/JWKS/OIDC) or API keys and per-tenant isolation. Role enforcement is opt-in too (CHRONOS_RBAC=true → admin > user > viewer), and the Swagger UI can be disabled on hardened deployments with CHRONOS_SWAGGER=false.

• ChronosOS Server — start, configure, and operate the control plane
• REST API Reference — every endpoint with curl examples
• Authentication & Authorization — JWT, API keys, RBAC, tenants
• Swagger UI at /swagger/ · OpenAPI JSON at /swagger/doc.json

Roadmap

The original seven-tier build-out (101 tracked items: correctness/safety, scale foundations, hardening/platform) is complete — see PLAN.md for the full history and acceptance criteria. Forward-looking capability work, aimed at parity with Google ADK, LangGraph, and DeepAgents while keeping Chronos self-hostable and Go-native, is tracked live in plan/STATUS.md.

See plan/README.md for the strategic thesis and workstream breakdown, and plan/STATUS.md for the live, item-by-item tracker.

CI/CD

Cut a release: git tag v0.2.0 && git push origin v0.2.0

Contributing

1. Fork and create a feature branch from main
2. Follow Go conventions — go vet, gofmt, wrap errors with %w
3. No init() functions, no global state, context.Context first on I/O methods
4. Table-driven tests in *_test.go files

License

MIT