cofy-x/axern
Documentation · Quickstart · SDKs · 简体中文 Axern is an open-source sandbox platform for AI agents. It isolates untrusted agent-generated code with runsc and runs trusted long-lived services with runc through one resource and lifecycle model. The CLI and the Go, Python, and TypeScript SDKs expose the same public APIs for environments, processes, files, services, storage, tunnels, lifecycle state, and task evidence.
catalog 简介 / catalog descriptioncatalog description：Open-source sandboxes for AI agents, untrusted code execution, and durable services.
安装Install
dsh plugin --profile web add github:cofy-x/axern把 cofy-x/axern 加入你的 DSH 配置（web profile）即可启用。
READMEREADME
Documentation · Quickstart · SDKs · 简体中文
Axern is an open-source sandbox platform for AI agents. It isolates untrusted agent-generated code with runsc and runs trusted long-lived services with runc through one resource and lifecycle model. The CLI and the Go, Python, and TypeScript SDKs expose the same public APIs for environments, processes, files, services, storage, tunnels, lifecycle state, and task evidence.
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.
Quickstart
The supported local path runs the complete stack with Docker Compose.
It needs only the axern CLI and Docker Compose v2 — no source checkout, Make, Helm, or language toolchains.
brew install cofy-x/tap/axern
Without Homebrew, use the standalone checksummed installer:
curl -fsSL https://raw.githubusercontent.com/cofy-x/axern/main/install.sh | sh
Then start Axern and run the first workload:
axern local up
axern local image load python:3.12-slim --pull
axern run python:3.12-slim -- python -c 'print("hello from axern")'
local up starts PostgreSQL, MinIO, the control and node services, waits for readiness, and creates the local context. local image load streams the selected host Docker image into that local node without a temporary archive:
axern context current
axern run list
axern local status
axern local down
The local environment uses generated development credentials and loopback listeners. Do not reuse them in a shared or production deployment.
Source development is a separate contributor path.
It builds the current checkout into local :dev images and exercises the same public contract:
make quickstart-source
What You Can Build
- Agent sandboxes: execute agent-generated code behind a runsc isolation boundary while retaining process, file, terminal, and output APIs.
- Durable services: run trusted, performance-sensitive processes with runc while the control plane owns replicas, health, storage, and rollouts.
- Reproducible agent execution: use Axrun to coordinate immutable tasks, verification, trajectories, usage, and typed artifacts.
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.
- Real data-plane access: process streams, files, archives, HTTP services, SSH-compatible terminals, and reverse TCP tunnels are explicit capabilities.
- 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
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.
| 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.
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.
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.
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 cofy-x.
Licensed under the Apache License, Version 2.0.
相关推荐Related
- deepseek-ai/deepseek-harness DeepSeek Harness: Everything is a Plugin.
- deepseek-ai/deepseek-harness DeepSeek Harness (dsh) — 由 DeepSeek AI 开发的开源 agent harness（智能体框架）。一切皆插件：核心 + 插件 + 技能 = 可热插拔的 AI 编程工作台。DeepSeek Harness: …
-
nexu-io/open-design
🎨 Best DeepSeek Harness Design Plugin. The open-source Claude Design alternative. 🖥️ Local-first desktop app. 🖼️ Your…
-
ruvnet/ruflo
🌊 The original agent meta-harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build c…
-
amruthpillai/reactive-resume
A one-of-a-kind resume builder that keeps your privacy in mind. Completely secure, customizable, portable, open-source a…
-
volcengine/OpenViking
Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.
-
Molunerfinn/PicGo
:rocket: The Ultimate Image Uploader for Efficient Creators. Supports Obsidian, Typora, VS Code etc. and 60+ image hosti…
-
titanwings/colleague-skill
将冰冷的离别化为温暖的 Skill，欢迎加入数字生命1.0！Transforming cold farewells into warm skills? It's giving rebirth era. Welcome to Digital …