Carrier

Build systems, not software.

From idea to production. Describe it. Approve it. Compile it. Ship it.

Official homepage: carrierlang.com
Carrier and CarrierLang are trademarks (TM) of Nikolai Manek.
Licensed under the Apache License 2.0. Copyright 2026 Nikolai Manek.

Carrier is a standalone compiled language for API services and backend business logic. You write .carrier files once; the compiler turns that source graph into service code, OpenAPI, migrations, manifest metadata, generated tests, hardening probes, agent/tool schemas, and deployable runtime artifacts.

The point is not to save a few controller files. The point is to stop rebuilding the same backend platform on every project:

• schema, CRUD, typed routes, auth, policies, transactions, jobs, events, schedules, workflows, and external clients are declared in one place
• Postgres migrations, OpenAPI, runtime metadata, generated tests, SDK/MCP/tool schemas, and hardening evidence come from the same compiler-known model
• AI-generated changes stay inside a typed language surface instead of diffusing across framework glue, hand-written JSON schemas, policy snippets, route handlers, and background workers
• production concerns such as idempotency, tenant context, row-level security, audit, realtime, runtime limits, evidence bundles, and ops routes are first-class instead of late-project chores

Carrier is intentionally narrow: it is built for CRUD-heavy APIs, Postgres-backed services, workflow-aware backend systems, and agent/tool surfaces that need to be reviewable. It is not a Rust framework, a macro wrapper, or a general-purpose scripting language.

Targets

Carrier has three code generation targets that share the same lexer, parser, semantic analysis, IR, manifest, OpenAPI, and migration contract:

Target	Use it for	Status
Rust	Default production services and the broadest Carrier feature surface.	Primary target. Generates native services through Cargo and owns the fullest runtime behavior.
Java / Spring Boot	Teams that want a production Spring MVC/JDBC service for the accepted Carrier surface.	Production-supported target with parity gates for OpenAPI, manifest, migrations, CRUD, auth, workflows, jobs, queues, schedules, events, CSA starts, tests, and deployment artifacts.
Node.js / Fastify	Fast local iteration, dev/test loops, and route/CRUD-heavy feedback cycles.	Deliberate development slice. It shares compiler contracts and supports executable CSA starts, but production should move to Rust or Java after target checks.

Parity is a compiler contract, not a slogan: accepted source should preserve the shared manifest, OpenAPI, migration, and API semantics across the supported target surface. Rust remains the default and broadest target; Java is where production parity is actively gated; Node.js is optimized for fast iteration rather than broad production coverage. See Target Selection for the target boundaries.

Why It Saves Weeks

Most backend projects do not lose time because the first route is hard. They lose time because every feature drags along a second pile of work: database shape, migrations, API contract, auth checks, tenant scoping, policy context, generated docs, background jobs, retries, audit, tests, observability, SDKs, local tooling, and now agent/tool metadata.

Carrier compiles those cross-cutting pieces together. A model or route can affect CRUD, OpenAPI, RLS, generated tests, manifest metadata, React Native SDK shape, MCP tool schemas, API Explorer metadata, hardening probes, and runtime evidence without you wiring each one by hand. That is the "save weeks" part: the compiler keeps the boring platform work attached to the business model.

Highlights

• Three targets from one source: Rust first, Java/Spring for production teams that need it, and Node/Fastify for fast local iteration.
• Generated API surface: typed routes, CRUD, search/filter/sort/pagination, soft delete, restore, optimistic versions, idempotency keys, OpenAPI, and docs UI.
• Data and policy: Postgres migrations, raw SQL escape hatches, transactions, row locking, policy/RLS generation, tenant/role session context, audit, seed helpers, and schema drift checks.
• Async runtime: jobs, queues, schedules, events, workflows, worker mode, realtime streams, subscriptions, watches, retries, timeouts, and route cache metadata.
• Carrier Structured Agents (CSA): typed durable agents over llm client declarations with structured output, declared fn/action tools, guardrails, tenant/auth checks, retries, fallbacks, telemetry, manifest/OpenAPI metadata, and UI thread-participant bindings.
• MCP without adapters: generated services can expose Carrier actions and workflows as MCP tools, while carrier-mcp gives AI coding agents compiler diagnostics, symbols, hover, definitions, formatting, build/check, pattern lookup, and policy-context tools.
• Hardening built in: runtime depth limits, JSON/OpenAPI/artifact budgets, panic capture, evidence bundles, Flight Recorder, carrier tune, carrier manifest audit, and carrier harden live probes.
• AI-friendly authoring: project-local AGENTS.md/CLAUDE.md, deterministic manifests, generated evidence, and a small language surface that keeps human and AI edits reviewable.

What Compiles Today

Implemented today:

• service, runtime, auth jwt, import, enum, type, model, crud, fn, action, policy, route, client, llm client, rag, agent, workflow, event, job, schedule, stream, subscription, watch, sla, test, invariant, and ui
• arrays, optionals, enums, Time, Date, UUID, Decimal, validation attributes, and JSON helpers
• path params, query blocks, typed input bodies, OpenAPI generation, and docs UI
• CRUD with filters, pagination, sorting, search, soft delete, and restore
• batch import loops plus model bulk insert/upsert helpers
• transactions, row locking, optimistic @version, and route idempotency
• raw SQL helpers, DB function helpers, and typed external JSON clients
• policy/RLS generation with tenant and role session context
• cache/Redis helpers, jobs, schedules, events, workflows, realtime streams, and audit recording
• blob/file helpers, image helpers, PDF helpers, locale/address/phone helpers, and healthcare/FHIR helpers
• LLM clients and Carrier Structured Agents with typed tool schemas, structured outputs, guardrails, tenant budgets, and realtime streams
• scenario tests, property tests, bounded invariant verification, and generated API tests
• runtime depth guards, panic capture, evidence bundles, and the in-process Carrier Flight Recorder
• manifest generation, MCP metadata, migration generation, and application commands

Still intentionally constrained:

• imports define the loaded source graph from src/main.carrier when present, with root-file fallback for older layouts
• migration diffing is structural and explicit, with conservative table and column rename detection
• hardening can either prepare local Schemathesis/oha/curl bombardment scripts or run a bounded live probe harness against a generated child service with carrier harden --run, including an owned disposable Postgres database with carrier harden --run --sandbox-db
• ops routes such as /ops/runtime and /ops/flight are generated as operational surfaces and should be protected by deployment policy until Carrier grows first-class ops-route auth configuration

API Surface Depth

Carrier is not just a CRUD generator. A generated service can include several API layers at once:

• Public and authenticated REST routes with typed path params, query structs, request bodies, response types, cache policy, idempotency keys, and OpenAPI metadata.
• Generated CRUD APIs with tenant-aware filters, list/search pagination, soft delete, restore, sorting, relation metadata, bulk insert/upsert, and optimistic write protection.
• Business actions that can be called from routes, jobs, event handlers, workflows, tests, and LLM tool dispatch while carrying the same auth, tenant, trace, and transaction context.
• Durable workflows, jobs, schedules, events, and on handlers for async and post-commit work.
• Realtime streams, subscriptions, watches, and LLM streaming endpoints with transport negotiation.
• External clients for typed JSON APIs, generated federation endpoints, MCP/tool metadata, React Native SDK metadata, and manifest-driven downstream tooling.
• Data helpers for Postgres, raw SQL, DB functions, cache/Redis, audit, blobs, images, PDFs, healthcare payloads, vector similarity, and hybrid search.
• Runtime and ops APIs including /health, /ready, /openapi.json, /docs, /ops/runtime, /ops/flight, blob download routes, and worker/runtime entrypoints.

The important product shape is that these surfaces are compiler-known. Carrier emits target service artifacts, OpenAPI, .carrier/manifest.json, migrations, generated tests, verification reports, MCP metadata, and hardening artifacts from the same source graph.

Carrier Tank Hardening

Carrier Tank is the hardening track for making generated APIs survive hostile inputs and recursive runtime behavior.

• service.runtime supports explicit limits for request/action/route/workflow/expression depth, JSON body depth, schema expansion depth, OpenAPI ref depth, body size, artifact size, timeouts, panic policy, evidence bundle emission, and generated ops-route exposure.
• Depth failures return structured CARRIER_DEPTH_LIMIT_EXCEEDED errors with limit, location, and hint metadata instead of panicking or overflowing the stack.
• Runtime panics are caught as CARRIER_RUNTIME_PANIC where the execution span can recover safely.
• Evidence bundles capture request id, route/action/workflow context, tenant/auth shape, input shape, stack hash, panic/error metadata, source locations where available, suggested tests, and recent Flight Recorder events.
• The Flight Recorder keeps bounded in-process probe events and exposes snapshots through /ops/flight?request_id=<id> when runtime.ops_routes is not off; the default ops policy is local_only.
• carrier manifest audit reports manifest/OpenAPI/generated target sizes, largest manifest sections, budget status, and suspicious secret-like literals.
• carrier tune inspects local CPU/memory/process/open-file limits, generated API shape, artifact sizes, and optional Postgres reachability, then writes .carrier/tune.json and a copy-ready .carrier/tune.runtime.carrier snippet with recommended service.runtime and DATABASE_MAX_CONNECTIONS values.
• carrier harden runs compile checks, artifact budget checks, production-profile invariant verification, generated tests, static schema/ref depth checks, and writes deterministic smoke/fuzz/load scripts.
• carrier harden --run builds and starts the generated service on loopback when the port is env-driven, then runs health/readiness/OpenAPI/ops/auth-boundary/malformed-body/deep-body/ oversized-body/concurrency probes and records them in .carrier/harden/report.json.
• carrier harden --run --sandbox-db creates a unique carrier_harden_* Postgres database from the configured/default DATABASE_URL, points only the generated child service at it, runs live probes, and drops that owned database after the child exits.
• Live hardening also probes tenant-scoped protected CRUD when a local JWT config is available: tenant A create/read/list control, tenant B list/read/update/delete isolation, missing tenant claims, invalid JWTs, wrong roles, and restore isolation for soft-deleted records.
• carrier harden --chaos adds destructive payload fixtures for malformed JSON, deep bodies, weird Unicode, missing tenant claims, and overlap/concurrency probes.

Authoring Tiers

Carrier works best when you choose the smallest construct that matches the job.

Tier 1: Minimal / First-Pass-Safe

Use this for quick starts and AI-generated first drafts:

• one service
• optional auth jwt
• type, route, and client
• model plus crud
• simple fn helpers
• single-file projects or very small multi-file projects

Start here with examples/hello-carrier.

Tier 2: Recommended Production Pattern

Use this for most business services:

• multi-file layout under src/
• model, type, crud, action, route
• idempotent edge routes where retries matter
• transactions for business writes
• policy declarations for role and tenant rules
• structured logs.* metadata

Start here with examples/inventory-control.

Tier 3: Advanced Runtime / Platform Pattern

Use this when the service needs more operational machinery:

• cache/Redis
• jobs and schedules
• events and audit trails
• raw SQL / DB function escape hatches
• richer policy/RLS use
• typed external integrations

Start here with api and use examples/booking-service as the concurrency/workflow supplement.

Tier 4: Tank / Chaos Pattern

Use this when you want to exercise the runtime under deliberately hostile API shapes:

• deeply nested models and recursive-looking relationships
• public and protected routes
• CRUD, restore, soft delete, search, list, pagination, and overlap checks
• malformed inputs, large payloads, weird Unicode, missing tenant claims, and invalid JWT paths
• actions calling actions, routes calling clients, workflow hooks, file/blob paths, and concurrency probes

Start here with examples/carrier-chaos-clinic.

Learning Ladder

1. examples/hello-carrier Minimal single-file starter. Shows auth, typed request/response records, and simple routes.
2. examples/inventory-control Recommended multi-file production shape. Shows imports, sorted file layout, CRUD, actions, idempotent admin routes, and thin-route patterns.
3. api Advanced doctor-directory showcase. Shows policy/RLS, row locking, cache, jobs, events, schedules, raw SQL, DB function helpers, and external clients.
4. examples/booking-service Supplemental scheduling and concurrency example. Shows tenant-aware models, @version, jobs, schedules, events, idempotent routes, and action-driven locking flows.
5. examples/carrier-chaos-clinic Tank hardening testbed. Shows deliberately broad API shapes and carrier harden --chaos fixtures for hostile payloads and runtime boundary probes.

Repository Layout

api/
benchmarks/
  doctor-directory-bench/
crates/
  carrier-ast/
  carrier-lexer/
  carrier-parser/
  carrier-semantic/
  carrier-ir/
  carrier-codegen-rust/
  carrier-runtime/
  carrierc/
docs/
examples/
  carrier-chaos-clinic/
  hello-carrier/
  inventory-control/
  booking-service/

Install

Install the Carrier CLI from the public source repo:

curl -fsSL https://raw.githubusercontent.com/nikoma/carrier/main/install_carrier.sh | sh

The installer builds carrierc with cargo install and writes the carrier executable to ~/.local/bin by default. It requires Git plus Rust/Cargo 1.85 or newer.

Install the companion MCP server too:

curl -fsSL https://raw.githubusercontent.com/nikoma/carrier/main/install_carrier.sh | sh -s -- --with-mcp

Install from a checkout or choose a different prefix/ref:

./install_carrier.sh --prefix "$HOME/.local" --branch main
./install_carrier.sh --with-mcp

Use --tag or --rev when you want to pin installation to a release tag or commit.

CI And Build Caches

The GitHub Actions workflow runs formatting, cargo check --workspace, and workspace package tests on Linux and macOS. The default test step excludes the carrierc integration suite because those tests spawn many nested generated-service Cargo builds and need a separate resource-controlled job. The workflow uses repository-scoped Actions caches for Cargo registry data, Git dependencies, and target/ build output, keyed by OS plus Cargo.lock/Cargo.toml changes.

Commands

Build and test the compiler workspace:

cargo check --workspace --locked
cargo test --workspace --exclude carrierc --locked
cargo run -p carrierc -- --help

Build the same Carrier project for each target:

carrier build --target rust
carrier build --target java
carrier build --target node

Check and build the minimal starter:

cd examples/hello-carrier
carrier check
carrier build

Write project-local AI instructions for Codex and Claude:

cd /path/to/your/carrier-project
carrier agent-docs

Check and build the recommended multi-file example:

cd examples/inventory-control
carrier check
carrier build
carrier openapi > openapi.json

Check and build the advanced showcase:

cd api
carrier check
carrier build
carrier migrate generate
carrier openapi > openapi.json

Check and build the workflow supplement:

cd examples/booking-service
carrier check
carrier build
carrier migrate generate

Run the Tank hardening harness:

cd examples/carrier-chaos-clinic
carrier harden --chaos --run --sandbox-db

Ask Carrier for local runtime sizing advice:

carrier tune --profile production

Generated hardening artifacts are written under .carrier/harden/. Project-local .carrier/manifest.json files are generated artifacts unless the project is one of the checked-in fixture projects that intentionally pins manifest/OpenAPI compatibility output.

Documentation

Core references:

• Language Reference
• Stability Policy
• CLI Reference
• Runtime Errors
• Observability
• AI Authoring Guide
• Architecture
• Target Selection
• MCP Integration
• LLM Clients And Agents
• Chat Mount Protocol
• React Native SDK

Task-focused guides:

• Construct Guide
• Multi-File Projects
• Workflow Patterns
• Batch Imports
• Healthcare FHIR Helpers
• PDF Generation
• Security Notes
• Performance Reference
• Migrations And Safety

Why Carrier Is AI-Friendly

Carrier’s advantage is not maximal language power. Its advantage is that it narrows backend choices into a compiler-checked set of patterns:

• explicit models, routes, actions, policies, jobs, and clients
• generated CRUD instead of hand-written repetition
• real transactions and escape hatches when generated CRUD is not enough
• machine-readable manifest, OpenAPI, verification, evidence, and hardening output for tooling
• predictable project structure and multi-file guidance
• project-local AGENTS.md and CLAUDE.md scaffolding via carrier agent-docs

That makes Carrier easier to generate correctly, review, and keep consistent over time.