Reusable Go packages for building a web backend: configuration, structured logging, HTTP serving, Postgres access and migrations, search, background jobs, events and transactional email, and durable, governed AI agents: runs that survive a crash, wait for a person's approval and are held to written rules, on Postgres alone. Each package is usable on its own, and every package that talks to an external service ships an in-process default, so a project running only Postgres gets a complete backend.
Tutorial and package showcase: https://manava.github.io/keel/
go get github.com/ManavA/keel
Go 1.26 or later. Docker is needed only by pg/testdb.
A service that uses Postgres and nothing else:
package main
import (
"context"
"fmt"
"log/slog"
"os"
"github.com/ManavA/keel/config"
"github.com/ManavA/keel/httpx"
"github.com/ManavA/keel/log"
"github.com/ManavA/keel/pg"
)
type Config struct {
Port int `envconfig:"PORT" default:"8080"`
DatabaseURL string `envconfig:"DATABASE_URL" required:"true"`
}
func main() {
slog.SetDefault(log.New(log.Options{}))
var cfg Config
if err := config.Load(&cfg); err != nil {
slog.Error("load config", "error", err)
os.Exit(1)
}
ctx := context.Background()
pool, err := pg.Open(ctx, pg.Options{URL: cfg.DatabaseURL})
if err != nil {
slog.Error("open database", "error", err)
os.Exit(1)
}
defer pool.Close()
r := httpx.NewRouter(httpx.RouterOptions{})
r.Mount("/", httpx.Health(httpx.HealthOptions{
Checks: map[string]httpx.Check{"database": pg.HealthCheck(pool)},
}))
srv := httpx.NewServer(httpx.ServerOptions{
Addr: fmt.Sprintf(":%d", cfg.Port),
Handler: r,
})
if err := srv.ListenAndServe(ctx); err != nil {
slog.Error("server stopped", "error", err)
os.Exit(1)
}
}examples/minimal is a runnable service built this way, with a notes API over
Postgres. Run it with make run-local, or start your own from it with
go run ./cmd/keel new <name>.
| Package | Description |
|---|---|
config |
Environment loading over envconfig, optional dotenv, validation, secret trimming and redaction |
log |
A JSON slog handler carrying request ids, with credential-shaped keys redacted |
httpx |
HTTP server with graceful shutdown, chi router, middleware, JSON responses, health endpoints, server-sent event streams |
httpx/middleware |
Real client address, request id, request log, panic recovery, CORS, rate limiting |
httpx/buildinfo |
The revision the running binary was built from |
pg |
pgx v5 pool, transaction helper, offset and keyset paging |
pg/migrate |
Migration runner with a ledger, and a replay check |
pg/testdb |
Docker Postgres harness for tests |
search |
Document index over Postgres, or Meilisearch via search/meili |
jobs |
Background work with run outcomes, an in-process scheduler, and jobs/cloudrun triggers |
events |
Publish and subscribe in memory, or over Cloud Pub/Sub via events/pubsub |
mail |
Transactional email over a log sender or Postmark |
media |
Object storage and image derivatives, local filesystem or Google Cloud Storage |
geocode |
Address to coordinate lookup with a degrade chain, Mapbox or a no-op default |
perf |
Response caching, ETag, gzip, and singleflight middleware for HTTP handlers |
auth |
Authentication composable across local, Firebase and generic OIDC sources; sessions, verification, password reset (auth/pg for Postgres) |
admin |
Administrative session auth, a CORS-scoped router, and a helper for keeping admin-only fields out of public responses (admin/pg for Postgres) |
textpolicy |
One normalize-then-match guard for generated and forwarded text, with no domain-specific rules of its own |
retry |
Exponential backoff with full jitter, and context cancellation |
idempotency |
HTTP middleware that replays a stored response for a repeated Idempotency-Key |
flags |
Per-subject feature flags with percentage rollout and allowlist (flags/pg for Postgres) |
outbox |
Writes an event with a domain transaction, then relays it to events |
metrics |
Counters and histograms for HTTP, pool, jobs, outbox, events and geocode, with a no-op default and OTel via metrics/otel |
webhooks |
Signed HTTP delivery of events to external URLs, over the outbox relay |
notifyprefs |
Per-user notification opt-outs with send-path enforcement (notifyprefs/pg for Postgres) |
llm |
One call to a language model: text, tool calls, structured replies, streaming, embeddings; wrappers for retries, fallback, budgets and metering; no provider and no price table |
llm/anthropic |
The Anthropic Messages API over net/http, no vendor SDK |
llm/openai |
The OpenAI chat completions and embeddings API, and compatible servers, over net/http |
policy |
Rules that allow, ask a person about, or block an action, with every decision recorded under the rule that made it |
policy/pg |
The Postgres recorder for policy: an append-only decision log |
agent |
A run as a journal: model and tool calls written down around each step, a lease any process can take over, budgets, approvals and child runs |
agent/pg |
The Postgres agent.Store, its migration, and Once for tools that write to the same database |
agent/httpapi |
Runs, timelines, approvals and an event stream over HTTP; it names the caller but does not authenticate or authorise |
agent/agenttest |
A hand-moved clock, a scripted model, a fault-injecting store and the Store contract suite |
app |
The service lifecycle: logger, pool, migrations, router, auth and admin mounts, jobs, shutdown; and the adapters that put llm and policy behind agent |
cmd/keel |
Scaffolds a project from a template profile (keel new <name> [-profile minimal|standard|api|worker|webhook|agent]; minimal copies examples/minimal, standard copies examples/fullstack, api copies examples/apionly, worker copies examples/worker, webhook copies examples/webhook, agent copies examples/agentdemo) |
config.Load reads a struct from the environment, calls Validate if the
struct implements it, and trims whitespace from fields holding a secret or a
URL.
type Config struct {
Port int `envconfig:"PORT" default:"8080"`
DatabaseURL string `envconfig:"DATABASE_URL" required:"true"`
APIToken string `envconfig:"API_TOKEN"`
}
var cfg Config
if err := config.Load(&cfg); err != nil {
return err
}config.Redacted(&cfg) renders the struct as name and value pairs safe to log
at startup: secrets are replaced, collections report a count, and URLs keep
their host and lose their password.
Each package that talks to an external service selects its backend by configuration and falls back to an in-process default:
| Package | Default | External option |
|---|---|---|
search |
Postgres full-text (PostgresIndex) |
Meilisearch (search/meili) |
mail |
log sender (LogSender) |
Postmark |
events |
in-memory bus (InMemoryBus) |
Cloud Pub/Sub (events/pubsub) |
jobs |
in-process scheduler | Cloud Run triggers (jobs/cloudrun) |
media |
local filesystem (LocalStore) |
Google Cloud Storage (GCSStore) |
geocode |
NoopProvider returns nil when it has no result |
Mapbox |
auth |
local — email, password, verification, reset, sessions, all in-memory (auth/pg for Postgres) |
firebase (ID tokens), oidc (any issuer) |
idempotency |
in-memory (MemoryStore) |
Postgres (idempotency/pg) |
flags |
in-memory (MemoryStore) |
Postgres (flags/pg) |
metrics |
no-op recorder, in-process capture (InMemory) |
OpenTelemetry (metrics/otel) |
llm |
Scripted model and HashEmbedder, answering with no network |
Anthropic (llm/anthropic), OpenAI and compatible servers (llm/openai) |
policy |
in-memory recorder (MemoryRecorder) |
Postgres (policy/pg) |
agent |
in-memory store (MemoryStore), whose runs last as long as the process |
Postgres (agent/pg) |
Nothing in llm/anthropic or llm/openai has been run against a real provider
yet. Each has a live test behind the live build tag that needs an API key.
See docs/agents.md for the agent packages.
deploy/ holds a Dockerfile that injects the build revision, Cloud Build
configuration, and scripts that check a deployed revision is the one that was
pushed. scripts/ holds the repository's own developer and CI scripts.
See docs/deploy.md for health checks, proxy configuration, migrations,
shutdown, pool sizing and build identification, and docs/backup.md for
the backup and restore runbook.
See CONTRIBUTING.md. ARCHITECTURE.md describes the package layout and the
import rules. Tests run with:
make test # everything that needs no Docker
make test-db # database-backed packages, Docker required
make migrations-check # replay every migrations directory in the module
pg/testdb starts a real Postgres in Docker for tests. KEEL_REQUIRE_DB=1
turns a missing Docker from a skip into a failure. See docs/testing.md.
Apache License 2.0. See LICENSE.