Axern

Documentation · Quickstart · SDKs

Axern is open-source agentic infrastructure for running AI agents and code in isolated, stateful sandboxes. It is designed as a high-performance sandbox platform with one resource model for creating environments, executing processes, exposing services, attaching storage, opening reverse tunnels, observing lifecycle state, and retaining task evidence.

Axern is designed for teams that need more than a code-execution RPC: the control plane, node runtime, gateway, image path, SDKs, and agent harness share the same identity, lease, cleanup, and observability contracts.

Project status: Axern is pre-1.0 and under active development. It is suitable for evaluation and contribution, but operators should review the security and production boundaries before deploying multi-tenant workloads.

Why Axern

• Sandbox as the primitive: runs, services, functions, coding workspaces, and agent tasks compose the same execution and lifecycle APIs.
• Durable control plane: PostgreSQL-backed intent, placement, leases, retries, health, cleanup, and storage state remain authoritative across process or node restarts.
• Runtime choice behind one model: runc and runsc workloads use the same public APIs; OCI and Nydus image paths converge at the node runtime. The resource model remains independent of a single sandbox backend.
• Real data-plane access: process streams, files, archives, HTTP services, SSH-compatible terminals, and reverse TCP tunnels are explicit capabilities.
• Agent execution with evidence: Axrun runs external agent bundles, verifies results, records trajectories and usage, and preserves typed artifacts.
• Local-to-cluster continuity: Docker Compose, kind, and the cloud-neutral Helm chart exercise the same service boundaries.

Architecture

flowchart LR
    Client["CLI and SDK clients"] --> Gateway["gatewayd\npublic control and data edge"]
    Gateway --> Control["controld\ndurable intent and placement"]
    Gateway --> Tunnel["tunneld\nreverse TCP relay"]
    Gateway --> Node["axnoded\nsandbox execution"]
    Control --> Storage["storaged\nstorage control plane"]
    Control --> Node
    Storage --> Volume["volumed\nnode volume publish"]
    Node --> Image["imagemgr + imagefsd\nOCI and Nydus rootfs"]
    Node --> Runtime["runc / runsc sandboxes"]
    Axrun["axrun\nagent tasks and evidence"] --> Gateway

Loading

controld is the authority for product state. gatewayd resolves and forwards public traffic without owning placement. Node services own host-local runtime, image, network, and volume operations. See the runtime architecture and resource model for the detailed contracts.

Local Quickstart

The supported local path runs the complete stack with Docker Compose. It needs Docker with Compose v2, GNU Make, curl, OpenSSL, and SSH tooling. Linux is the primary runtime platform; Docker Desktop provides the supported macOS path.

git clone https://github.com/cofy-x/axern.git
cd axern
make quickstart

The command downloads the versioned CLI and multi-architecture images, starts PostgreSQL, MinIO, the control and node services, waits for readiness, and runs a smoke through the public gateway. It does not require a local Go, Rust, Python, or Node.js toolchain.

Use the generated local CLI context:

AXERN_CLI=deploy/local/state/releases/v$(cat VERSION)/axern
"${AXERN_CLI}" context current
"${AXERN_CLI}" catalog list
"${AXERN_CLI}" run create \
  --template-id python311 \
  --runtime-class runsc \
  --argv python \
  --argv -c \
  --argv 'print("hello from Axern")'

Inspect or remove the environment:

make local-compose-status
make local-compose-purge

The local environment uses generated development credentials and loopback listeners. Do not reuse them in a shared or production deployment.

Source development remains a first-class, separate path. It builds the current checkout into local :dev images and exercises the same Compose contract:

make quickstart-source

For local Helm development, build the images with make local-images-build and pass values-local-development.yaml to the chart. Provider and regional values stay outside this repository.

Kubernetes Install

Axern publishes its cloud-neutral chart as an OCI artifact and the CLI as checksummed release archives. Install the chart into the current Kubernetes context:

helm install axern oci://ghcr.io/cofy-x/charts/axern \
  --version "$(cat VERSION)" \
  --namespace axern-system \
  --create-namespace \
  --wait \
  --timeout 15m

After installing the CLI archive for your operating system, keep the gateway port-forward open and import the chart-generated mTLS identity:

kubectl --namespace axern-system port-forward svc/gatewayd \
  25100:25000 25101:25080 25122:25022

axern context import-kubernetes local \
  --namespace axern-system \
  --current
axern catalog list

The bundled PostgreSQL and single-node defaults are intended for evaluation. Durable or shared deployments must provide persistent storage, externalized secrets, ingress, and scheduling values described by the Helm chart.

Components

Component	Responsibility
controld	Durable control-plane state, placement, leases, lifecycle, rollout, and reconciliation
storaged	Storage classes, claims, bindings, and topology-aware resolution
gatewayd	Public gRPC, HTTP, SSH, terminal, tunnel, service, and sandbox data edge
axnoded	Node-local sandbox lifecycle, execution, files, process streams, and cleanup
volumed	Node-local volume publish, unpublish, and reconciliation
imagemgr / imagefsd	OCI and Nydus image resolution, mount lifecycle, and read-only data plane
tunneld	Internal reverse TCP relay and sandbox-local tunnel binding
axern	Product CLI for platform resources and access
axrun	Agent task harness, rollout worker, verifier, trajectory, usage, and evidence capture

Public clients are available in Go, Python, and TypeScript under sdk/. Shared wire contracts are defined in sdk/proto.

Development

Bootstrap and verify all language workspaces:

make bootstrap
make build
make test
make lint
make proto-generated-check
make agent-doc-check
make open-source-check

Use make help for the complete command surface. Module ownership and focused validation live in the module guide. Automated coding agents and contributors should begin with the agent contract and the nearest module-local contract.

Deployment

• Docker Compose and kind are the repository-owned local truth environments.
• The Axern Helm chart is cloud-neutral and accepts operator-owned image registries, certificates, storage classes, and secrets.
• Provider account setup, cluster creation, credentials, and regional release automation intentionally live outside this repository.

Axern does not claim that a default local or example deployment is safe for an untrusted multi-tenant environment. Review authentication, TLS, network policy, runtime isolation, image trust, secret storage, resource limits, and persistent storage before production use. Report vulnerabilities according to SECURITY.md.

Documentation

• Official documentation
• Long-term product direction
• Runtime architecture
• Storage architecture
• Durable rollout control plane
• Local verification
• Documentation index

Contributing

Contributions are welcome. Read CONTRIBUTING.md, follow the Code of Conduct, and sign every commit under the Developer Certificate of Origin. Project decisions follow the governance model.

License

Copyright 2026 Chen Yingwei.

Licensed under the Apache License, Version 2.0.