acthur

module

v0.0.0-...-5467d48 Latest Latest Go to latest Published: Jul 14, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/acthurhq/acthur

Links

Open Source Insights

README ¶

Acthur

Runtime Graph Operating System with Pluggable Infrastructure Nodes

Acthur orchestrates your entire application — backend, frontend, and infrastructure — as a live directed graph. It generates framework-native code, manages your dev environment, enforces API contracts between services, and deploys your system with one command.

What Acthur Is

You define the graph.  Acthur runs it.

acthur.yml             →  graph of nodes and relationships
acthur dev             →  starts everything, proxies traffic, hot reloads
acthur add auth        →  generates full auth system into your project  
acthur deploy          →  ships to production from the same graph

Acthur is not a framework. It is not a monorepo tool. It is not a scaffolder that generates code and steps back. It is a running system — alive during development and deployment — that manages your entire stack through its graph model.

Quick Start

# Install
curl -fsSL https://install.acthur.dev | sh

# Create a new project
acthur new my-saas

# Start development
cd my-saas
acthur dev
# → http://my-saas.test:4000

The Five Concepts

Graph — Every service, database, cache, and queue is a node. Every relationship is a typed edge. The kernel makes every decision — startup order, hot reload cascade, deploy topology — by traversing this graph.

Contracts — Every edge between services has a typed contract defining what can flow between them. Breaking changes are detected before they reach production. Code is generated from contracts.

Adapters — Adapters bridge abstract graph nodes to concrete technologies. go:fiber, rust:axum, ui:astro, db:postgres — each is an adapter. Adapters know how to start, build, and scaffold their framework. They know nothing about plugins.

Plugins — Plugins install capabilities into the kernel. auth, migrations, rbac, multitenancy — each is a plugin. Plugins register hooks, commands, and generators via the kernel API. They generate framework-native code into your project. Your deployed application has zero runtime dependency on Acthur.

Dev = Deploy — The same graph that runs acthur dev is the source of truth for acthur deploy. Docker Compose files, CI pipelines, and Dockerfiles are all derived from the graph. Never manually written.

Project Structure

my-saas/
├── acthur.yml            ← the graph definition (the source of truth)
├── contracts/            ← API contracts between services
│   ├── users.contract.yml
│   └── appointments.contract.yml
├── services/
│   ├── api/              ← go:fiber backend (generated)
│   └── worker/           ← background worker (generated)
├── web/                  ← ui:astro frontend (generated)
├── backoffice/           ← ui:next backoffice (generated)
├── db/migrations/        ← database migrations (generated)
└── .acthur/              ← kernel runtime state (gitignored)

`acthur.yml` — The Graph

project: my-saas
version: "1"

identifiers:
  strategy: ulid

graph:
  nodes:
    api:
      type: service
      adapter: go:fiber
      port: 8080

    web:
      type: service
      adapter: ui:astro
      port: 3000

    db:
      type: infra
      adapter: db:postgres

    cache:
      type: infra
      adapter: cache:redis

  edges:
    - from: api
      to: db
      type: depends_on

    - from: web
      to: api
      type: data_flow
      contracts: [contracts/users.contract.yml]

plugins:
  - name: migrations
  - name: auth
    config:
      strategy: jwt
      algorithm: RS256

Supported Runtimes

Runtime	Frameworks
Go	Fiber, Chi, Gin, Echo
Rust	Axum, Actix, Rocket
Node.js	Fastify, NestJS, Express
Bun	Elysia, Hono
Python	FastAPI, Django, Flask
PHP	Laravel

Frontend	Adapter
Astro	`ui:astro`
Next.js	`ui:next`
Nuxt	`ui:nuxt`
SvelteKit	`ui:svelte`
Vue (Vite)	`ui:vue`

The Three-Layer Boundary

Plugin  → installs capability into Acthur kernel
           (auth, migrations, rbac, multitenancy, ...)

Adapter → bridges a graph node to a real framework  
           (go:fiber, ui:astro, db:postgres, ...)

Generated code → lives in your project, zero Acthur imports
                  pure Go / Rust / TypeScript

These three never cross into each other. An adapter never knows a plugin exists. A plugin never calls an adapter directly. Your generated code never imports Acthur at runtime.

CLI Reference

# Project
acthur new <name>          interactive wizard → new project
acthur init                adopt existing project (non-destructive)
acthur dev                 start all services + proxy
acthur build               build all services for production
acthur deploy              deploy to configured target

# Graph
acthur graph validate      validate graph structure
acthur graph show          print all nodes and edges

# Contracts
acthur contract validate   validate all contracts
acthur contract diff <n>   show changes + flag breaking

# Database
acthur db migrate          run pending migrations
acthur db seed             run seeders
acthur db reset            drop + migrate + seed

# Code generation
acthur generate from-contract <file>
acthur generate model <Name> --fields "..."
acthur generate ai-context
acthur generate ci --target github-actions

# Plugins
acthur add auth
acthur add rbac
acthur add multitenancy

# Environment
acthur doctor              check environment health
acthur doctor --fix        auto-fix issues

# AI
acthur mcp serve           start MCP server for AI tools
acthur agent explain "<q>" explain part of the system
acthur agent diagnose "<p>" diagnose a runtime problem

Plugins

Plugin	Adds
`migrations`	DB migration management
`auth`	JWT, OAuth2, Session, Magic Link, MFA
`rbac`	Roles and permissions
`multitenancy`	Schema or row-level isolation
`feature-flags`	Feature flag system
`admin`	Auto-generated admin panel
`observability`	OpenTelemetry + Prometheus + Grafana
`security`	CORS, CSP, rate limiting, OWASP headers
`https`	mkcert for dev, ACME for production
`secrets`	Vault, Doppler, Infisical adapters
`i18n`	Internationalization + localization
`analytics`	PostHog, Plausible, Metabase
`ci-cd`	GitHub Actions, GitLab CI
`docs`	Living documentation from contracts
`ai`	Claude Code / Cursor context + MCP server

AI Integration

Acthur has something AI coding agents lack: a complete, live, typed model of your entire system. The ai plugin exposes this as:

Context files — Generated for your specific AI tool. Claude Code gets CLAUDE.md + skills. Cursor gets .cursorrules. Each file is derived from the actual graph — always accurate.

Skills — Project-specific procedural knowledge. create-endpoint, add-migration, auth-patterns — each skill knows your exact stack, adapter, and plugin configuration.

MCP server — acthur mcp serve exposes the live graph to any MCP-compatible tool. Claude Code can read your graph, trigger generators, run tests, and stream logs directly.

acthur generate ai-context    # select your tool, generate context + skills
acthur mcp serve              # start MCP server

For Existing Projects

cd my-existing-project
acthur init

Acthur scans your project, detects the stack, and writes acthur.yml. It never modifies existing files. The non-destructive guarantee: Acthur writes only acthur.yml and .acthur/.

Deploy

acthur deploy                    # production
acthur deploy --env staging      # staging
acthur deploy --dry-run          # preview without changes

Supported targets: Coolify, Fly.io, Railway, Render, Docker.

All deployment manifests are derived from the graph. Docker Compose files, Dockerfiles, and CI pipelines are generated — never manually written.

Architecture

For the complete architectural specification, see the Product Requirements Document.

Key architectural documents:

The Four-Layer Model — Ring 0 → Adapters → Contracts → Plugins and the communication law
Graph Engine Internals — scheduler, process table, topo sort, lifecycle
Contract Specification — typed edges, diff engine, wire enforcement
Plugin System — KernelAPI, event bus, generator hooks

Architecture Decision Records (the "why" behind key choices):

Roadmap

See docs/roadmap.md for the full phase breakdown and version milestones.

Version	Gate	Headline
v0.1	Phase A	`acthur generate` works; first example project
v0.2	Phase B	`acthur add auth/migrations/rbac`
v0.3	Phase C	Multi-adapter ecosystem; docs site live
v0.4	Phase D	Live hot-reload; contract enforcement on wire
v0.5	Phase E	`acthur deploy` to production in one command
v0.6	Phase F	MCP server; `acthur agent`
v1.0	All phases	Stable public API; Homebrew/Scoop

Contributing

Acthur is MIT-licensed and actively developed. See CONTRIBUTING.md for the full guide.

Adding a backend adapter: Implement the Adapter interface (8 methods) + scaffold templates for your framework. See internal/adapter/backend/gofiber/ as reference.

Adding a plugin: Implement the Plugin interface (3 methods) + Register(KernelAPI). See Plugin System.

git clone https://github.com/acthurhq/acthur
cd acthur
make build
make test
./bin/acthur doctor

License

MIT — see LICENSE

Acthur — Runtime Graph Operating System
https://acthur.dev · https://github.com/acthurhq/acthur

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
acthur command Package cmd wires all cobra commands for the Acthur CLI.	Package cmd wires all cobra commands for the Acthur CLI.
internal
adapter Package adapter defines the Adapter interface and the global adapter registry.	Package adapter defines the Adapter interface and the global adapter registry.
adapter/backend/chi Package chi implements the go:chi adapter.	Package chi implements the go:chi adapter.
adapter/backend/fastify Package fastify implements the node:fastify adapter.	Package fastify implements the node:fastify adapter.
adapter/backend/gin Package gin implements the go:gin adapter.	Package gin implements the go:gin adapter.
adapter/backend/gofiber Package gofiber implements the go:fiber adapter.	Package gofiber implements the go:fiber adapter.
adapter/backend/rustaxum Package rustaxum implements the rust:axum adapter.	Package rustaxum implements the rust:axum adapter.
adapter/frontend/astro Package astro implements the ui:astro adapter.	Package astro implements the ui:astro adapter.
adapter/frontend/next Package next implements the ui:next adapter.	Package next implements the ui:next adapter.
adapter/infra/postgres Package postgres implements the db:postgres adapter.	Package postgres implements the db:postgres adapter.
aiagent Package aiagent provides the LLM-provider plumbing behind `acthur agent`: resolving an acthur.yml `ai:` block plus environment variables into a usable API key, a small Provider interface real providers implement, and a Context builder that turns the live graph/contract/config into the prompt context an AI-powered command sends the model.	Package aiagent provides the LLM-provider plumbing behind `acthur agent`: resolving an acthur.yml `ai:` block plus environment variables into a usable API key, a small Provider interface real providers implement, and a Context builder that turns the live graph/contract/config into the prompt context an AI-powered command sends the model.
config Package config loads and validates acthur.yml into typed Go structs.	Package config loads and validates acthur.yml into typed Go structs.
container Package container projects declarative adapter container specs onto local container runtime commands.	Package container projects declarative adapter container specs onto local container runtime commands.
contract Package contract is the safety layer of the Acthur kernel.	Package contract is the safety layer of the Acthur kernel.
deploy Package deploy is the production half of the runtime: the pre-deploy gate, the deploy execution context, and the compose target.	Package deploy is the production half of the runtime: the pre-deploy gate, the deploy execution context, and the compose target.
deploy/artifacts Package artifacts projects a sealed graph.Graph onto the production deploy artifacts Slice 1 of Phase 8 owns: a Dockerfile per Dockerizable service node and one docker-compose.prod.yml wiring the whole graph together.	Package artifacts projects a sealed graph.Graph onto the production deploy artifacts Slice 1 of Phase 8 owns: a Dockerfile per Dockerizable service node and one docker-compose.prod.yml wiring the whole graph together.
deploy/coolify Package coolify is a minimal typed client for the Coolify v4 REST API, plus a deploy Target that pushes a project's docker-compose stack to a Coolify instance and waits for it to come up healthy (PRD phase-8 deploy-runtime, slice 3, tracker #52).	Package coolify is a minimal typed client for the Coolify v4 REST API, plus a deploy Target that pushes a project's docker-compose stack to a Coolify instance and waits for it to come up healthy (PRD phase-8 deploy-runtime, slice 3, tracker #52).
deploy/fly Package fly is a minimal typed client for the Fly.io Machines API, plus a deploy Target that builds+pushes a project's Dockerized services to Fly's own registry and runs them as Fly Machines (PRD phase-9, tracker #64).	Package fly is a minimal typed client for the Fly.io Machines API, plus a deploy Target that builds+pushes a project's Dockerized services to Fly's own registry and runs them as Fly Machines (PRD phase-9, tracker #64).
deploy/railway Package railway is a minimal typed client for Railway's public GraphQL API, plus a deploy Target that builds+pushes a project's Dockerized services to an external registry and runs them as Railway services (PRD phase-9, tracker #64).	Package railway is a minimal typed client for Railway's public GraphQL API, plus a deploy Target that builds+pushes a project's Dockerized services to an external registry and runs them as Railway services (PRD phase-9, tracker #64).
deploy/render Package render is a minimal typed client for the Render REST API (https://api.render.com/v1), plus a deploy Target that builds+pushes a project's Dockerized services to an external registry and runs them as Render web services (PRD phase-9, tracker #64).	Package render is a minimal typed client for the Render REST API (https://api.render.com/v1), plus a deploy Target that builds+pushes a project's Dockerized services to an external registry and runs them as Render web services (PRD phase-9, tracker #64).
dns Package dns checks whether the hostnames `acthur dev` routes traffic through (the project's dev domain and its per-node subdomains) resolve to 127.0.0.1, and produces copy-pastable /etc/hosts instructions when they don't.	Package dns checks whether the hostnames `acthur dev` routes traffic through (the project's dev domain and its per-node subdomains) resolve to 127.0.0.1, and produces copy-pastable /etc/hosts instructions when they don't.
doctor Package doctor checks whether the developer's machine meets all requirements for the given acthur.yml stack and can auto-fix many missing dependencies.	Package doctor checks whether the developer's machine meets all requirements for the given acthur.yml stack and can auto-fix many missing dependencies.
engine Package engine contains the dev and deploy orchestration engines.	Package engine contains the dev and deploy orchestration engines.
flags Package flags is the project's feature flag store backing `acthur flag create/list/enable/disable/toggle`.	Package flags is the project's feature flag store backing `acthur flag create/list/enable/disable/toggle`.
generate Package generate is the write engine behind acthur's generated code: it takes a set of plugin.GeneratedFile values (produced by acthur add's plugin generators, and — from Phase 7 slice 2 on — the contract→code pipeline) and persists them to disk idempotently, tracking what it wrote in a generated.lock file at the project root so repeat runs can tell "safe to regenerate" apart from "the user has since edited this by hand".	Package generate is the write engine behind acthur's generated code: it takes a set of plugin.GeneratedFile values (produced by acthur add's plugin generators, and — from Phase 7 slice 2 on — the contract→code pipeline) and persists them to disk idempotently, tracking what it wrote in a generated.lock file at the project root so repeat runs can tell "safe to regenerate" apart from "the user has since edited this by hand".
generate/aicontext Package aicontext generates AI coding-tool context files from the live Acthur graph, config, and contract registry — the "what is this project?" document described in acthur-prd.md §17.3, as opposed to the task-procedure skill files internal/generate/skillgen produces.	Package aicontext generates AI coding-tool context files from the live Acthur graph, config, and contract registry — the "what is this project?" document described in acthur-prd.md §17.3, as opposed to the task-procedure skill files internal/generate/skillgen produces.
generate/ci Package ci generates CI/CD pipeline configuration from the project graph.	Package ci generates CI/CD pipeline configuration from the project graph.
generate/docsgen Package docsgen generates living API documentation from the contract registry: one markdown page per contract (endpoints, methods, types) plus an index page linking all of them.	Package docsgen generates living API documentation from the contract registry: one markdown page per contract (endpoints, methods, types) plus an index page linking all of them.
generate/gofiber Package gofiber turns a parsed contract into framework-native go:fiber code: DTOs with constraint-derived validation, handlers, a service interface + skeleton, a pgx repository skeleton, route mounting, a contract-derived migration, and a test beside every source file.	Package gofiber turns a parsed contract into framework-native go:fiber code: DTOs with constraint-derived validation, handlers, a service interface + skeleton, a pgx repository skeleton, route mounting, a contract-derived migration, and a test beside every source file.
generate/skillgen Package skillgen generates a Claude Code skill scaffold (.claude/skills/<name>/SKILL.md) from the live project graph — the "how do I do X in this specific project?" procedure file described in acthur-prd.md §17.3/17.4, as opposed to internal/generate/aicontext's static "what is this project?" description.	Package skillgen generates a Claude Code skill scaffold (.claude/skills/<name>/SKILL.md) from the live project graph — the "how do I do X in this specific project?" procedure file described in acthur-prd.md §17.3/17.4, as opposed to internal/generate/aicontext's static "what is this project?" description.
generate/visualize Package visualize renders a graph.Graph as a Mermaid flowchart or a Graphviz DOT digraph for `acthur graph visualize`.	Package visualize renders a graph.Graph as a Mermaid flowchart or a Graphviz DOT digraph for `acthur graph visualize`.
graph Package graph is the kernel's brain.	Package graph is the kernel's brain.
health Package health provides health check strategies for every node type.	Package health provides health check strategies for every node type.
mcp Package mcp implements a Model Context Protocol server over stdio.	Package mcp implements a Model Context Protocol server over stdio.
output Package output provides consistent, styled terminal output for all Acthur commands.	Package output provides consistent, styled terminal output for all Acthur commands.
plugin Package plugin defines the Plugin interface, the KernelAPI that plugins are given access to, the kernel event bus, and the plugin loader.	Package plugin defines the Plugin interface, the KernelAPI that plugins are given access to, the kernel event bus, and the plugin loader.
plugin/builtin/admin Package admin is the built-in "admin" plugin (Phase 9, tracker #65).	Package admin is the built-in "admin" plugin (Phase 9, tracker #65).
plugin/builtin/auth Package auth is Acthur's built-in "auth" plugin (Phase 6 Slice 2).	Package auth is Acthur's built-in "auth" plugin (Phase 6 Slice 2).
plugin/builtin/featureflags Package featureflags is the built-in "feature-flags" plugin (Phase 9, tracker #65).	Package featureflags is the built-in "feature-flags" plugin (Phase 9, tracker #65).
plugin/builtin/https Package https is the built-in "https" plugin (Phase 9, tracker #65).	Package https is the built-in "https" plugin (Phase 9, tracker #65).
plugin/builtin/migrations Package migrations is the built-in "migrations" plugin: it registers a generator that scaffolds a project's migrations/ directory with an initial golang-migrate-compatible pair, and exposes the database-command logic consumed by `acthur db migrate\|rollback\|status\|create` (wired in cmd/acthur, since the plugin KernelAPI's CLICommand model registers only flat top-level commands — it has no notion of a command group, and `acthur db` already exists as a real cobra group in cmd/acthur/commands.go).	Package migrations is the built-in "migrations" plugin: it registers a generator that scaffolds a project's migrations/ directory with an initial golang-migrate-compatible pair, and exposes the database-command logic consumed by `acthur db migrate\|rollback\|status\|create` (wired in cmd/acthur, since the plugin KernelAPI's CLICommand model registers only flat top-level commands — it has no notion of a command group, and `acthur db` already exists as a real cobra group in cmd/acthur/commands.go).
plugin/builtin/multitenancy Package multitenancy is the built-in "multitenancy" plugin (Phase 6, Slice 4): schema-per-tenant multitenancy for go:fiber projects backed by Postgres.	Package multitenancy is the built-in "multitenancy" plugin (Phase 6, Slice 4): schema-per-tenant multitenancy for go:fiber projects backed by Postgres.
plugin/builtin/observability Package observability is the built-in "observability" plugin (Phase 9, tracker #65).	Package observability is the built-in "observability" plugin (Phase 9, tracker #65).
plugin/builtin/rbac Package rbac is the built-in "rbac" plugin: role-based access control for The go:fiber projects.	Package rbac is the built-in "rbac" plugin: role-based access control for The go:fiber projects.
plugin/builtin/security Package security is the built-in "security" plugin (Phase 9, tracker #65).	Package security is the built-in "security" plugin (Phase 9, tracker #65).
plugin/builtin/testplugin Package testplugin is the built-in "test" plugin: Phase 5's proof that a plugin's hook, command, and generator registrations all fire at the correct lifecycle points under the real kernel.	Package testplugin is the built-in "test" plugin: Phase 5's proof that a plugin's hook, command, and generator registrations all fire at the correct lifecycle points under the real kernel.
process Package process manages child processes for all service nodes in the graph.	Package process manages child processes for all service nodes in the graph.
proxy Package proxy implements the Acthur dev reverse proxy.	Package proxy implements the Acthur dev reverse proxy.
scaffold Package scaffold resolves adapter scaffold inputs from project config.	Package scaffold resolves adapter scaffold inputs from project config.
secrets Package secrets is the project-scoped secret store backing `acthur secrets set/get/list/rm/rotate`.	Package secrets is the project-scoped secret store backing `acthur secrets set/get/list/rm/rotate`.
watcher Package watcher implements a file system watcher that triggers graph-aware hot reload cascades when source files change.	Package watcher implements a file system watcher that triggers graph-aware hot reload cascades when source files change.