Installation

Installation

AgentCTX can be installed as an npm package, run via Docker Compose, or built from source.

npm Package

The fastest way to get started:

npm install @agentctx/core

This gives you:

• The actx CLI (via npx actx or globally with npm install -g @agentctx/core)
• The TypeScript SDK for programmatic use
• All core modules (parser, gateway, sidecar, memory, knowledge)

Global CLI

To use actx directly without npx:

npm install -g @agentctx/core
actx --version

Docker Compose

For the full platform stack with SurrealDB, NATS, and all services:

git clone https://github.com/ryan-haver/agentctx.git
cd agentctx
docker compose up -d --build --wait

This starts 6 services:

Service	Port	Role
surrealdb	:8000	SurrealDB v3 database (in-memory)
surrealdb-init	—	Schema bootstrapper (loads 10 .surql files, then exits)
nats	:4222	NATS JetStream message bus
mock-mcp	:3200	Mock MCP backend for testing
agentctx	:3100	TypeScript SSE gateway (main entry point for agents)
ctx-gateway	:8420	Rust HTTP gateway (LLM traffic interception + compression)

With OpenTelemetry

For observability (Jaeger, Prometheus):

docker compose -f docker-compose.yml -f docker-compose.otel.yml up -d --build

With Benchmarks

docker compose -f docker-compose.yml -f docker-compose.bench.yml up --build

From Source

git clone https://github.com/ryan-haver/agentctx.git
cd agentctx
npm install
npm run build
npm link          # Makes `actx` available globally

Development Mode

npm run dev       # TypeScript watch mode
npm test          # Run all unit tests
npm run test:integration   # Integration tests (requires Docker)

Rust Crates (Optional)

Performance-critical paths are available as native Rust crates. These are optional — the TypeScript implementation handles everything by default.

Prerequisites

• Rust 1.93+ with wasm32-unknown-unknown target
• wasm-pack (for WASM builds)

Available Crates

Crate	Targets	Role
ctx-parser	Native, NAPI, PyO3, WASM	Rust CTX parser + serializer
ctx-compactor	Native	Context compaction engine
ctx-compactor-napi	NAPI (Node.js)	N-API bridge for compactor
ctx-compactor-wasm	WASM (browser)	Browser-based compaction
ctx-gateway	Native	Rust HTTP gateway (axum)

Building Crates

# Build the parser for Node.js
cd crates/ctx-parser
cargo build --release

# Build WASM for browser
cd crates/ctx-compactor-wasm
wasm-pack build --target web --no-opt

# Run Rust tests
cargo test --workspace

System Requirements

Requirement	Minimum	Recommended
Node.js	20.0.0	22+ (LTS)
npm	9+	10+
Docker	24+ (optional)	25+ with Compose v2
Rust	1.93+ (optional)	Latest stable
Memory	512 MB	2 GB+ (with Docker stack)
OS	Linux, macOS, Windows	Any with Node.js 20+

Next Steps

• Configuration → — configure actx.yaml, environment variables, and secrets
• Quick Start → — run your first CTX operations