axrecipe

Centrally-managed, versioned command recipes with run history and event streaming.

Overview

axrecipe is a headless API server for storing and versioning command recipes, tracking runs against those recipes, and recording run events. It uses PostgreSQL for storage and database-backed API keys with scoped permissions for access control.

Interactive API documentation is available at /docs (Swagger UI) when the server is running (enabled by default; disable with AXRECIPE_ENABLE_DOCS=false).

The web UI for axrecipe lives in axconsole.

Configuration

| Variable | Description | Default | | --------------------------- | ----------------------------------------------------------------------------- | -------------------------------------- | | AXRECIPE_PORT | Port to listen on | 3849 | | AXRECIPE_HOST | Host to bind to | 127.0.0.1 | | AXRECIPE_DATABASE_URL | PostgreSQL connection URL | postgresql://localhost:5432/axrecipe | | AXRECIPE_LOG_LEVEL | Pino log level (silent, trace, debug, info, warn, error, fatal) | info | | CORS_ORIGINS | Comma-separated allowed origins (empty = CORS disabled, * = all) | "" | | CORS_CREDENTIALS | Allow credentials in CORS requests | false | | RATE_LIMIT_MAX | Max requests per time window | 100 | | RATE_LIMIT_TIME_WINDOW | Rate limit time window | 1 minute | | FASTIFY_CLOSE_GRACE_DELAY | Graceful shutdown delay (ms) | 500 | | TRUST_PROXY | Proxy trust mode (true, false, hop count, or comma-separated IPs) | "" (disabled) | | AXRECIPE_LOG_PRETTY | Pretty-print logs (true, false; unset = auto-detect TTY) | "" (auto) | | AXRECIPE_ENABLE_DOCS | Enable Swagger UI at /docs (true, false) | true |

Prerequisites

• Node.js >= 22.19.0
• PostgreSQL 14+ — the database must exist before running axrecipe init (which runs migrations but does not create the database itself)

# Example: create the database
createdb axrecipe
# Or via Docker:
docker run -d --name axrecipe-db -p 5432:5432 \
  -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=axrecipe \
  postgres:17-alpine

Authentication

Authentication uses database-backed API keys with scoped permissions (read, execute, manage, grant).

Quick start:

# Initialize database and create the first admin key
axrecipe init --create-admin-key

# Or create keys separately
axrecipe key create --name "Admin" --read "*" --execute "*" --manage "*" --grant "*"

Client Configuration

The axrecipe run command uses these environment variables when connecting to a server:

| Variable | Description | Default | | ------------------ | ---------------- | ------- | | AXRECIPE_URL | Server URL | — | | AXRECIPE_API_KEY | API key for auth | — |

These can also be set via --server and --api-key flags (prefer env vars to avoid process list exposure).

CLI flags (--port, --host, --database-url, --log-level) override the corresponding server environment variables.