axiom server

axiom server works with a compiled backend contract and its private server plan: it scaffolds configuration, generates OpenAPI and handler types, runs managed and sandbox actions, drives durable delivery, and packages release bundles. This page covers all 22 subcommands in Axiom CLI 0.149.1.

All axiom server commands run locally without Cloud login. Commands that start a service or worker resolve provider values, such as a database URL or Redis URL, from environment variables named in your deployment files.

Diagram source

flowchart LR
  B[axiom build] --> C[Contract and plan]
  C --> D[server deployment]
  D --> V[server validate]
  V --> R[server run]
  V --> P[server package]
  P --> VB[server verify-bundle]
  VB --> RB[server run-bundle]
  VB --> RC[server rollback-check]

axiom build writes the contract and plan. server deployment scaffolds the private deployment file, which you review. server validate constructs the real providers without opening a listener. From there you either run the service locally with server run, or package an immutable bundle, verify it, and run it with server run-bundle. server rollback-check compares two verified bundles before you switch back to an older one.

axiom server

axiom server <COMMAND>

Shared inputs

Keep the plan, deployment, bindings and delivery files private. They never enter the public .axiom artifact. Scaffold commands refuse to overwrite an existing file: choose a new output path so a reviewed file is never replaced.

Native actions need a registered trusted Rust application host. The generic runtime behind axiom serve and axiom server run cannot resolve arbitrary native symbols. Python and Go services use their server adapter, which talks to axiom server boundary.

Scaffold and generate

axiom server plan

Scaffold a native action plan from a compiled contract when your handlers live in your own application (for example an extracted FastAPI or Go service). Review the generated status and body mappings before use.

axiom server plan --output <OUTPUT> <CONTRACT>

axiom server plan backend.axiom --output backend.server.json

axiom server deployment

Scaffold the private deployment file for a contract and plan. Resources, grants and providers start in a reviewable state: operation grants are empty, and a typed resource without a known provider is marked reviewRequired.

axiom server deployment --output <OUTPUT> <CONTRACT> <PLAN>

The scaffold refers to values by environment variable name. You set these when you run the service:

axiom server deployment backend.axiom backend.server.json --output deployment.json

axiom server delivery-deployment

Scaffold the private durable delivery file for a plan that declares jobs, events or webhooks. Operation grants start empty; add only the grants you want before starting a worker.

axiom server delivery-deployment --output <OUTPUT> <CONTRACT> <PLAN>

The scaffold uses namespace delivery, a 30-second lease, 24-hour receipt retention, and these environment variable names: AXIOM_DELIVERY_REDIS_URL, AXIOM_DELIVERY_JOB_<NAME>_TOKEN and AXIOM_DELIVERY_CONSUMER_<NAME>_TOKEN for worker credentials, and AXIOM_WEBHOOK_<NAME>_URL and AXIOM_WEBHOOK_<NAME>_KEY for webhook destinations and signing keys. See Events, jobs and webhooks for grants and Redis requirements.

axiom server openapi

Generate an OpenAPI 3.1 document from the effective contract and its server mappings, for API gateways or third-party clients.

axiom server openapi --output <OUTPUT> <CONTRACT> <PLAN>

axiom server openapi backend.axiom backend.server.json --output openapi.json

axiom server types

Generate typed handler inputs, outputs and handler signatures for a Python or Go service that implements the contract's actions.

axiom server types --language <LANGUAGE> --output <OUTPUT> <CONTRACT> <PLAN>

axiom server types backend.axiom backend.server.json --language python --output handler_types.py
axiom server types backend.axiom backend.server.json --language go --output handler_types.go

Inspect and compare

axiom server targets

List every deployment target profile with its runtime, platform, capabilities, providers, limits and evidence. Unavailable or uncertified profiles fail closed: they cannot validate or package.

axiom server targets

No options other than --help.

See Deployment targets for each profile's limits.

axiom server inspect

Validate the exact contract identity and show each action's guards, effects and transitive requirements, plus a target compatibility assessment. Without --deployment, provider review stays pending and the result cannot establish release compatibility.

axiom server inspect [OPTIONS] <CONTRACT> <PLAN>

The same assessment, with optional redacted startup observations, is available from axiom inspect server.

axiom server diff

Compare the private behavior of two contract and plan pairs, such as guards, effects and provider requirements. The public contract diff is unchanged; use axiom diff for public changes.

axiom server diff <BEFORE_CONTRACT> <BEFORE_PLAN> <AFTER_CONTRACT> <AFTER_PLAN>

Validate and run locally

axiom server validate

Check that a deployment works before you start a listener: it assesses target compatibility, constructs the actual providers and authentication, verifies sandbox assets and confirms cleanup. Missing credentials fail validation.

axiom server validate [OPTIONS] --deployment <DEPLOYMENT> <CONTRACT> <PLAN>

axiom server validate backend.axiom backend.server.json --deployment deployment.json

On success it prints one JSON object with "validated":true, the targetAssessment, "listenerOpened":false and the cleanup result.

axiom server run

Serve the plan's managed and sandbox actions as an HTTP service. It never starts mocks. Use it to run a compiled contract and plan exactly as deployed; for source-first development use axiom serve or axiom server dev.

axiom server run [OPTIONS] --deployment <DEPLOYMENT> <CONTRACT> <PLAN>

axiom server run backend.axiom backend.server.json --deployment deployment.json --listen 127.0.0.1:8080

axiom server dev

Build .acore source, serve it, and reload when project files change, within the providers and grants of a reviewed deployment.

axiom server dev [OPTIONS] --deployment <DEPLOYMENT> <SOURCE>

The watcher snapshots up to 1,024 source, manifest and lock files. It skips hidden directories, symlinks, secret files and target, node_modules, build, dist, venv and __pycache__. A rejected reload keeps the running service. If a new snapshot fails to start, the last validated snapshot restarts.

axiom server dev service.acore --deployment deployment.json --listen 127.0.0.1:8080

axiom server invoke

Call one authored action directly, without HTTP, through its mandatory guards. Use it to test an action's guards and output from a script.

axiom server invoke [OPTIONS] --deployment <DEPLOYMENT> --request <REQUEST> <CONTRACT> <PLAN>

The result prints as JSON.

axiom server boundary

Run the private JSON-lines enforcement bridge that a native framework adapter (for example the Python or Go server adapter) starts over stdin and stdout. It opens no network listener. You normally do not run it by hand.

axiom server boundary [OPTIONS] <CONTRACT> <PLAN>

Durable delivery

These commands need a plan with delivery declarations, a reviewed delivery file and a reachable Redis server named by AXIOM_DELIVERY_REDIS_URL (or the name in your delivery file). Execution is at least once. See Events, jobs and webhooks for grants, retries and Redis configuration.

axiom server worker

Execute durable jobs, event consumers, schedules and signed webhook attempts. SIGTERM or Ctrl+C stops new attempts and drains current work.

axiom server worker [OPTIONS] --deployment <DEPLOYMENT> --delivery <DELIVERY> <CONTRACT> <PLAN>

axiom server worker backend.axiom backend.server.json --deployment deployment.json --delivery delivery.json

axiom server enqueue

Submit a typed job, or publish to an event binding, using an explicitly granted operation.

axiom server enqueue --delivery <DELIVERY> --request <REQUEST> <CONTRACT> <PLAN>

The receipt prints as JSON. Repeating the same identity and payload during retention returns the same receipt.

axiom server delivery-inspect

Inspect redacted provider state, attempts, failures and recovery history. The output never includes payloads or credentials.

axiom server delivery-inspect [OPTIONS] --delivery <DELIVERY> <CONTRACT> <PLAN>

axiom server delivery-cancel

Cancel pending work, or signal the attempt that currently holds the lease. The delivery file must grant cancellation for that binding.

axiom server delivery-cancel --delivery <DELIVERY> --id <ID> <CONTRACT> <PLAN>

axiom server delivery-redrive

Move one dead letter back into delivery. It needs a recovery grant, and external effects of earlier attempts can repeat.

axiom server delivery-redrive --delivery <DELIVERY> --id <ID> <CONTRACT> <PLAN>

Package and release bundles

Bundles are local artifacts. Provisioning, publication and hosting stay external. Legacy axiom-server-release/v1 bundles have no bound target or runtime contract: repackage the original artifacts with the current CLI before verification, activation or rollback. See Release a backend.

axiom server package

Create an immutable, hash-bound release directory for one target after an artifact-only preflight. Production credentials are not resolved.

axiom server package [OPTIONS] --deployment <DEPLOYMENT> --output <OUTPUT> <CONTRACT> <PLAN>

A sealed container profile may contain only axiom-cloud-database and axiom-cloud secret sources with identity = "google-metadata", and only env configuration sources; other profiles fail with AXSECRET_CONTAINER_SOURCE. See connect a server on Google Cloud.

What each target produces:

axiom server package backend.axiom backend.server.json --deployment deployment.json --target native-server --output release-v1

axiom server verify-bundle

Verify a release directory offline: exact file inventory, platform, bound contract and plan, target and runtime, capability requirements and sealed sandbox assets. It also verifies local Worker bundles.

axiom server verify-bundle <DIRECTORY>

The JSON result reports "verified":true, the platform, plan and target hashes and the file count. Configuration is validated again at startup.

axiom server verify-bundle release-v1

axiom server run-bundle

Run a verified native release using its exact packaged executable and a fresh configuration preflight. Start it with the bundled binary, on the matching platform.

axiom server run-bundle [OPTIONS] <DIRECTORY>

release-v1/bin/axiom server run-bundle release-v1 --listen 127.0.0.1:8080

axiom server rollback-check

Compare two immutable releases before you switch from the current one back to a previous one. Both must verify, share the same target, runtime and platform, and keep a compatible public contract. Private behavior changes are reported for review. Nothing rolls back automatically.

axiom server rollback-check <CURRENT> <PREVIOUS>

axiom server rollback-check release-v2 release-v1

Run a configuration preflight before activating the previous release.

Related pages

• Run a backend locally
• Deployment targets
• Release a backend
• Build and run commands