Getting Started
Install stax, define your first agent, build it, push it to a registry, and materialize it into a runtime
This guide walks you through the full stax lifecycle in under five minutes: define an agent, build a deterministic artifact, push it to a registry, and materialize it into a runtime.
Prerequisites
- Node.js 18+
- An OCI-compatible registry (GitHub Container Registry, Docker Hub, or any OCI registry)
Install stax
npm install -g staxVerify the installation:
stax --versionScaffold a project
mkdir my-agent && cd my-agent
stax init --agentThis creates:
my-agent/
├── agent.ts # Agent definition
├── prompt.md # System prompt
├── rules/ # Behavioral rules
│ └── code-style.md
├── skills/ # Reusable skill files
├── knowledge/ # Reference documents
└── tsconfig.jsonDefine your agent
Open agent.ts and customize it:
import { defineAgent, definePersona } from "stax";
const engineer = definePersona({
name: "alex",
displayName: "Alex Chen",
role: "Senior Backend Engineer",
expertise: ["TypeScript", "distributed systems", "API design"],
});
export default defineAgent({
name: "backend-engineer",
version: "1.0.0",
description: "A senior backend engineer for TypeScript projects",
runtime: "claude-code",
model: "claude-sonnet-4-1",
persona: engineer,
prompt: "./prompt.md",
rules: ["./rules/*.md"],
skills: ["./skills/*.md"],
knowledge: ["./knowledge/"],
});Write a system prompt in prompt.md:
You are a senior backend engineer specializing in TypeScript and Node.js.
You write clean, well-tested code with clear error handling.
You prefer composition over inheritance and value explicit over implicit behavior.Build the artifact
stax buildBuilt artifact: sha256:a3f8c1…e7d2
path: /repo/.stax/artifacts
layers: 6The build compiles your TypeScript definitions, validates referenced layer paths, produces deterministic OCI layers, and writes the artifact locally under .stax/artifacts/.
Inspect the artifact
Before pushing, verify what you built:
stax inspect ./.stax/artifactsAgent: backend-engineer v1.0.0
Runtime: claude-code (claude-sonnet-4-1)
Persona: alex (Alex Chen, Senior Backend Engineer)
Layers:
config application/vnd.stax.config.v1+json 1.2 KB
prompt application/vnd.stax.prompt.v1+markdown 0.4 KB
persona application/vnd.stax.persona.v1+json 0.3 KB
rules application/vnd.stax.rules.v1.tar+gzip 0.8 KB (1 rule)
skills application/vnd.stax.skills.v1.tar+gzip 0.0 KB (0 skills)
knowledge application/vnd.stax.knowledge.v1.tar+gzip 5.5 KBPush to a registry
Authenticate with your registry first:
stax login ghcr.ioThen push:
stax push ghcr.io/yourorg/backend-engineer:1.0.0Pushed ghcr.io/yourorg/backend-engineer:1.0.0
digest: sha256:a3f8c1…e7d2The artifact is now available to anyone with registry access.
Materialize into a runtime
Pull and translate the artifact into runtime-native files:
stax materialize ghcr.io/yourorg/backend-engineer:1.0.0 --out ./workspaceMaterialized backend-engineer@1.0.0
adapter: claude-code
fidelity: best-effort
files written: 4
output: ./workspaceThe output depends on the target runtime. For Claude Code, you get:
workspace/
├── CLAUDE.md # System prompt + rules + knowledge refs
├── .claude/
│ ├── settings.json # Model and MCP configuration
│ └── skills/ # Skill files
└── .mcp.json # MCP server definitionsTo preview the render without writing files:
stax materialize ghcr.io/yourorg/backend-engineer:1.0.0 --plan --consumer claude-codeTo inspect machine-readable output after writing files:
stax materialize ghcr.io/yourorg/backend-engineer:1.0.0 --jsonTo target a different runtime:
stax materialize ghcr.io/yourorg/backend-engineer:1.0.0 --adapter codex --out ./workspace