Quickstart
Install the compiler. Write .carrier. Ship a fast, secure service.
The compiler is a Cargo workspace. Every command below is present in the carrierc CLI today — end-to-end from .carrier source to a native binary.
Step 1
Clone and build the compiler
# clone the repo$ git clone https://github.com/nikoma/carrier.git$ cd carrier$ # build & test the compiler workspace$ cargo test$ cargo run -p carrierc -- --helpRequirements
Rust toolchain (edition 2024). Postgres 14+ for services that use models, CRUD, policy RLS, jobs, schedules, events, or idempotency.
Optional
Redis — used by
cache.* and redis.* when REDIS_URL is configured. Without it the cache falls back to in-memory.Step 2
Scaffold a project, check, and build
Project layout
my-service/
carrier.toml
src/
main.carrier
carrier.toml
src/
main.carrier
carrier.toml
[package]
name = "my-service"
version = "0.1.0"
name = "my-service"
version = "0.1.0"
$ carrier new my-service$ cd my-service$ # validate types, CRUD, auth, policies, and more$ carrier check$ # generate rust + cargo + native binary$ carrier build$ # run the service (or ./.carrier/build/<binary>)$ carrier runStep 3
Write your first service
Copy the hello-carrier example into src/main.carrier. It uses only Tier 1 constructs and demonstrates service, auth jwt, type, and route.
src/main.carrier
Tier 1service App { openapi { title: "Hello Carrier API" version: "0.1.0" } server { host: env("HOST", "0.0.0.0") port: env_int("PORT", 3000) }} auth jwt Auth { issuer: env("JWT_ISSUER", "carrier") audience: env("JWT_AUDIENCE", "carrier-users") secret: env("JWT_SECRET", "local-dev-secret")} type RegisterRequest { email: String @email name: String @length(min: 2, max: 100) password: String @length(min: 8)} type AuthTokens { access_token: String refresh_token: String } route POST "/auth/register" public -> AuthTokens { input: RegisterRequest handler { let user = auth.register( email: input.email, name: input.name, password: input.password ) return auth.issue_tokens(user.id) }} route GET "/me" protect Auth -> MeResponse { handler { return auth.current_user() }}Iteratezsh
$ carrier dev # watch + rebuild$ carrier test # run in-language tests$ $ carrier openapi --output openapi.json$ carrier fmt$ carrier migrate generate$ carrier migrate up$ carrier agent-docs # AGENTS.md + CLAUDE.md$ carrier cleanStep 4
Where to read next
Every item links back to the real repo content. Pick the tier that matches the shape of your service.
Tier 1→
hello-carrier
Minimal single-file service. Start here to verify the toolchain.
Tier 2→
inventory-control
Production shape: multi-file, crud, actions, idempotency.
Tier 3→
booking-service
Tenant-aware workflow: @version, jobs, events, schedules.
Flagship→
doctor-directory
Cache, SQL, DB functions, clients, policy/RLS, audit.
CLI
All commands, one reference
Implemented today. Every one of these runs against every example in the repo.
carrier newscaffold a project (--recipe org/name from registry)carrier agent-docswrite project-local AGENTS.md + CLAUDE.mdcarrier checkvalidate; refresh manifest + OpenAPI; --verify --profile production --fail-on-unknowncarrier verifydeterministic bounded invariant verification (--invariant, --json)carrier testrun scenario tests, property tests, evalscarrier eval optimizescore system_prompt variants (--llm-client)carrier tunelocal sizing advisor → .carrier/tune.json + tune.runtime.carriercarrier hardenTank attack harness — budgets, depth, schemathesis, oha; --chaos --run --sandbox-dbcarrier manifest auditmanifest/OpenAPI/Rust sizes + suspicious literals (--json)carrier doctorinspect installed Postgres capability extensionscarrier buildcompile (--target rust | java | node, --release, --compile-remote=true, --out-dir)carrier runbuild and run the compiled servicecarrier workerrun the generated service in worker-only modecarrier devwatch & rebuild on changescarrier fmtformat .carrier sourcecarrier graphprint lifecycle trigger graph (--model)carrier openapiemit or write OpenAPI JSON (--output)carrier cleanremove .carrier/ artifactscarrier installinstall Git + registry modules; refresh carrier.lockcarrier publishpublish module to a filesystem registry (--registry)carrier auditverify locked module provenance + advisories (OSV.dev)carrier modules fetchfetch Git + registry modulescarrier replread-only replay debug REPL (--replay <run-id>)carrier migrate generateproduce SQL migrations & schema snapshotscarrier migrate upapply generated migrationscarrier compliance generateevidence bundle (--standard hipaa | ferpa | pci-dss | soc2)carrier compliance verify-audit-chainverify carrier_audit_log hash chaincarrier sdk react-nativemanifest-driven RN SDK (--output, --package-name)carrier form promotepromote runtime-authored form into managed bundlecarrier workflow promotesnapshot runtime workflow into managed promotion bundlecarrier workflow shadowreplay-mode validation against promoted native semanticscarrier workflow transitionownership / lifecycle / runtime-state transitionscarrier workflow replayread-only workflow time-travel from durability statecarrier remote loginstore Carrier Cloud session token + control-plane URLcarrier remote deploypackage + upload to Carrier Cloud (--service, --wait)carrier remote statusCarrier Cloud deploy state + rollout URLcarrier remote logsfetch deploy logs (--format json)carrier remote openopen the Cloud deploy URLcarrier remote whoamiCloud actor + token scopescarrier remote domainslist Cloud domains for a deployed servicecarrier remote logoutremove the locally stored Cloud sessioncarrier deploy composegenerate docker-compose + Dockerfile artifactscarrier deploy k8sgenerate k8s manifests (--multi-region for tenant residency)carrier deploy edgegenerate edge WASM adapters (--target cloudflare | fastly)carrier releasebump version + changelog + run release stability checks