Andurel, Space-grade Go framework for humans and agents

Docs: andurel.com · Discord: join here

This README tracks master (head / nightly). It may describe features not yet in the latest semver release. Stable documentation matches go install …@latest at andurel.com/docs.

Platform Support

Andurel supports Linux and macOS on amd64 and arm64. Official releases contain and smoke-test all four combinations.

See release verification for archive installation, checksums, SBOMs, keyless signatures, and provenance.

Why Andurel?

Andurel is built for humans and agents on the same pad:

• Airframe: Generated models, factories, controllers, routes, and pages that belong to the application
• GNC: Fx for dependency injection and lifecycle. Explicit wiring, not a hidden runtime
• Propellant: PostgreSQL with narsilc-generated queries into application-owned model structs
• Payload: Inertia v3 with React, Vue, or Svelte. Same Go backend, official Inertia adapters, optional SSR. Templ + Datastar remains available for hypermedia pages
• Range ops: River jobs, email, and queues on the same stack that serves the request path
• Ground support: Agent-ready CLI, JSON discovery, and AGENTS.md so machines can operate the project without a second stack
• Live reload: andurel run with Shadowfax for Go, templates, CSS, and Vite (--tools mailpit for sidecars)
• Production build: andurel build compiles Templ, Tailwind CSS, Vite assets, and the Go binary

Agents. An agent-ready CLI with JSON discovery, plus AGENTS.md in the project. Machines get the same pad as humans, without inventing a second stack.

Core Technologies

• Echo: HTTP framework
• PostgreSQL + pgx: Database
• narsilc: Typed SQL with caller-owned result structs
• Templ + Datastar: Default hypermedia UI
• Inertia v3: Default React / Vue / Svelte + Vite
• River: Background jobs
• OpenTelemetry: Observability
• Tailwind CSS: CSS
• Shadowfax: Dev runner
• Fx: Dependency injection

Install

Match the install channel to the docs you follow.

Latest stable (v2)

go install github.com/mbvlabs/andurel/v2@latest
andurel --version

Specific version

go install github.com/mbvlabs/andurel/[email protected]
andurel --version

v1 releases stay on the unversioned module path (go install github.com/mbvlabs/[email protected]). That path's @latest never jumps to v2.

Nightly (matches master / this README)

Nightly ships as prebuilt binaries on the nightly GitHub release. Do not use go install for nightly; it builds from source without the embedded nightly version metadata.

# Linux amd64 (also available: andurel-darwin-arm64, andurel-darwin-amd64)
curl -L https://github.com/mbvlabs/andurel/releases/download/nightly/andurel-linux-amd64 -o andurel
chmod +x andurel
mv andurel "$(go env GOBIN)/"
andurel --version

Verified release archives (checksums, attestations) are documented in release verification.

Full install guide: andurel.com/docs.

Quick Start

# Default: PostgreSQL + Inertia React + pnpm
andurel new myapp
Other UI combinations
andurel new myapp --ui vue/bun
andurel new myapp --ui svelte/npm
andurel new myapp --ui templ/datastar
cd myapp
andurel tool sync
andurel skill install
cp .env.example .env
Edit .env with your database credentials

If using Inertia, install JS deps with the package manager from --ui
andurel db create          # optional: if the local database does not exist yet
andurel db migrate up
andurel run

App: http://localhost:8080

Generate a first resource after writing a migration:

andurel generate migration create_products_table
Edit the SQL, then:
andurel generate scaffold Product

See what generators can do:

andurel generate --help
andurel db --help

Project Layout & Options

A new app is ordinary Go you own. Top-level shape:

| Path | Role | |------|------| | cmd/app, cmd/queue | Process entry: load env, signal context, fx.New | | cmd/migrate | One-shot process: apply pending SQL via storage.RunMigrations | | cmd/seeds | One-shot process: run named seed sets | | internal/runtime | Fx graphs and process wiring (telemetry, email, database, server) | | config/ | App, DB, auth, email, telemetry config | | controllers/ | HTTP handlers | | models/ | Domain types + narsilc queries | | router/ | Routes and middleware | | views/ | Templ pages for Datastar UI; Inertia root document when using Inertia | | resources/js/ | Inertia pages (default UI) | | database/ | Migrations and seeds | | queue/ | River jobs and workers | | css/ / assets/ | Tailwind source and compiled assets |

Default: Inertia React + pnpm (--ui react/pnpm).

--ui react/pnpm|vue/bun|svelte/npm|templ/datastar: Same Go backend; choose Inertia + JS package manager (pnpm, bun, or npm), or Templ + Datastar. Generate follows the project UI; pass --api for JSON responses instead.

Details: directory structure · frontend options.

Core Commands

| Command | Purpose | |---------|---------| | andurel new (n) | Scaffold a project | | andurel generate | Create model, migration, controller, scaffold, job, email, query | | andurel sync | Refresh derived files (factories, views, queries, …) | | andurel db | Database lifecycle: create, drop, nuke, rebuild, migrate, seed, console | | andurel run (r) | Dev server with live reload | | andurel build | Production build (Templ, CSS, Vite, Go binary) | | andurel tool sync | Download pinned project binaries | | andurel upgrade | Bring an app forward to a newer Andurel | | andurel doctor | Project diagnostics | | andurel skill | Show / install the embedded agent skill | | andurel inspect | Read-only project shape (routes, models, …) | | andurel commands | Structured command discovery |

Use andurel --help for flags. Full CLI reference: andurel.com/docs/latest/cli.

Agents

The CLI is meant for humans and machines. Prefer discovery over scraping this README:

andurel commands --json
andurel inspect project --json
andurel skill install

Many mutating commands support --dry-run and --json. Agent workflows: andurel.com/docs/latest/agent-workflows.

Contributing

1. Fork and branch
2. Make changes
3. Run just check-fmt, just check-fix, and just vet (or gofmt / go fix / go vet with GOWORK=off)
4. Open a pull request

git clone https://github.com/mbvlabs/andurel
cd andurel
GOWORK=off go mod download
just vet

License

MIT. See LICENSE.

Sites built with Andurel

• DeployCrate: Remote boxes for your agents and teams
• MBV Blog: Personal blog
• Master Golang: Course platform
• Palantir: Open sourced analytics platform (WIP)

Author

Created by Morten Vistisen

• Twitter/X
• Mail