axern

Documentation · Quickstart · SDKs · 简体中文

Axern is open-source, self-hosted infrastructure for single-host agent execution and persistent workspaces. It provides isolated execution through gVisor (runsc) and experimental single-writer Workspace resources. The CLI and Go, Python, and TypeScript SDKs expose the same public APIs for Environments, Runs, sandbox processes and files, Tunnels, lifecycle state, and Allocation-scoped access. gVisor/runsc is the sole long-term execution backend.

The primary use case is a personal agent system on one Linux host: independent workers, inspectable execution, retained working data, and a small operational surface. Agent sessions, configuration, planning, collaboration, and workflows belong to caller applications. See the product direction and single-host serving decision. Project status: Axern is pre-1.0 and under active development. An experimental native Linux installation provides a source-built runtime archive and managed systemd lifecycle. It is not yet a published release channel or a supported upgrade path. Docker Compose remains the local development path. Optional Workspace data requires XFS project quotas; other writable storage is Allocation-local. Supported backup/restore and upgrades remain unqualified, and sealed outputs expire 15 minutes after cleanup begins. Review the current deployment and storage boundaries before use.

The durable chain is Environment → Run → Allocation → runsc sandbox. The following concepts describe how an agent system uses that chain; they do not introduce another execution lifecycle or an Axern Agent resource. The default collaboration pattern is independent writable working directories, common read-only references, and explicitly published results that the caller merges or hands off. Use separate Workspaces or Allocation-local directories, read-only image mounts, and explicit result handoff. Simultaneous shared writable mounts remain outside the single-writer contract.

Agent workload images share a base and development toolchain, then add official Claude Code or Codex programs in separate layers. Build them locally with make agent-images; model credentials, provider selection, tasks and session policy remain runtime inputs owned by the caller.

Quickstart

For Linux single-host serving, build and stage a coherent native archive using the installation guide. Operate the installed server with axern server start, status, logs and stop. API contexts select remote execution services; they do not change the host managed by server.

Use the CLI, services and SDKs from one coordinated release or source revision. For repository development on Linux or a macOS Linux VM, use Go 1.26.10, Make and Docker Compose v2:

quickstart-source builds current service images and verifies the source Compose stack. The packaged Compose lifecycle is axern dev up|status|logs|down; it is separate from the installed server and retains the machine-local context/data identity. A published CLI's development bundle requires its matching published service images. See the CLI contract for deployment commands and contexts.

Workspace usage covers retained files through fresh Runs. Without a Workspace, existing ephemeral execution stays available. Agent programs, tasks and session recovery remain caller-owned.

For repository development, make verify-changed is the normal fast feedback entrypoint. Linux correctness, full regression, and release qualification are separate tiers. Every main commit starts a commit-bound full regression; a green PR check does not imply that this later run has passed. Check Post-Merge Full before release or promotion; see the verification tiers. What You Can Build Agent sandboxes: execute agent-generated code behind a runsc isolation boundary while retaining process, file, terminal, and output APIs. Concurrent agent tasks: execute coding, research, evaluation, or data processing work through independent Runs, with explici