Arasaka

Rust runtime for governed AI agents.

Arasaka sits between an LLM and the systems an agent can read or change. The LLM proposes responses and tool calls; the runtime decides what is allowed, what needs validation, what requires approval, and what must be recorded.

Scope

Arasaka is a runtime and control plane for building agents that need explicit governance:

• a ReAct-style agent loop with policy checks around tool execution
• human approval gates for sensitive actions
• tenant-aware memory and retrieval
• optional GraphRAG for authority-aware context
• logical sandboxing, tool allowlists, and SSRF/path/shell protections
• durable run state, idempotency, and resumable workflows
• per-tenant HTTP rate limiting and replay protection
• RunTrace JSON traces, redaction, and read-only control-plane inspection
• API key or JWT HS256 auth with RBAC and tenant isolation
• HTTP, CLI, Docker, and evaluation workflows
• TOML/JSON eval datasets, Markdown/JUnit reports, and a release smoke gate
• DomainPacks for packaging domain-specific tools, policies, workflows, and evals

Arasaka is not a prompt collection, a model-hosting layer, or a general chatbot UI. It is the safety and operations layer around agents that interact with tools, memory, and production-like state.

How It Works

flowchart TD
  User[User or API] --> Runtime[AgentRuntime]
  Runtime --> Context[Context compiler]
  Context --> Retrieval[Unified retrieval]
  Retrieval --> Memory[Layered memory]
  Retrieval --> Graph[Optional GraphRAG]
  Runtime --> LLM[LlmClient]
  Runtime --> Tools[ToolRuntime]
  Tools --> Policy[Policy engine]
  Tools --> Sandbox[Sandbox policy]
  Tools --> Approval[Approval store]
  Runtime --> State[Workflow state]
  Runtime --> Trace[Run trace]
  Runtime --> Domains[DomainPacks]

Loading

The core rule is simple: tools do not execute just because the model asked for them. Tool calls are validated, checked against policy, sandboxed by capability, optionally paused for approval, executed idempotently, and written to the trace.

Quick Start

Prerequisites: Rust 1.75+.

git clone https://github.com/praedico/arasaka
cd arasaka
cargo build
cargo test

Run the first governed workflow:

cargo run --example governed_support_agent

This example uses mock model output and in-memory stores, so it needs no API key or external service. The maintained examples are governed_support_agent, governed_research_agent, and governed_ops_agent.

CLI

cargo build --features cli --bin arasaka

./target/debug/arasaka config validate --env development
./target/debug/arasaka run --request "Summarize the refund policy"
./target/debug/arasaka domain list
./target/debug/arasaka eval list --dir evals

HTTP Server

Development:

export ARASAKA_API_KEY=dev-local-key
cargo run --features server,auth-jwt --bin arasaka-server

Production-style config:

cp config/example.production.toml config/production.local.toml
export ARASAKA_API_KEY="$(openssl rand -hex 32)"
export OPENAI_API_KEY="sk-..."
cargo run --features server,auth-jwt,openai --bin arasaka-server -- \
  --config config/production.local.toml

You can also pass explicit runtime settings:

arasaka-server --config config/production.local.toml --bind 0.0.0.0:8080

Health endpoints:

curl http://localhost:8080/healthz
curl http://localhost:8080/readyz

Docker

docker compose --profile local-json up --build

The compose file is intentionally local-only. The image can also be run with a production-style config that you copy, adapt, and mount explicitly:

docker build -t arasaka .
docker run --rm -p 8080:8080 \
  -e ARASAKA_CONFIG=/config/production.local.toml \
  -e ARASAKA_API_KEY="$(openssl rand -hex 32)" \
  -e OPENAI_API_KEY="$OPENAI_API_KEY" \
  -v "$PWD/config/production.local.toml:/config/production.local.toml:ro" \
  -v arasaka-data:/var/lib/arasaka \
  arasaka

See docs/deployment.md and docs/production-posture.md.

External LLM Provider Adapters

Mock mode is the deterministic core path for local examples. OpenAI, Anthropic, and LocalHttp are beta external provider adapters. To use OpenAI-compatible chat completions:

export OPENAI_API_KEY="sk-..."
export ARASAKA_LLM_PROVIDER=openai
export ARASAKA_LLM_MODEL=gpt-4o-mini
cargo run --features "cli,openai" --bin arasaka -- run --request "Say OK in one word"

For local OpenAI-compatible endpoints:

export ARASAKA_LLM_PROVIDER=local_http
export ARASAKA_LLM_MODEL=llama3.2
export ARASAKA_LOCAL_LLM_URL=http://127.0.0.1:11434/v1/chat/completions
cargo run --features "cli,openai" --bin arasaka -- run --request "ping"

More options: docs/quickstart-llm.md.

DomainPacks

DomainPacks package a specialization without changing the runtime core. A pack can contribute:

• tools and validators
• policy rules and approval thresholds
• workflow templates
• graph schema and extractors
• eval datasets

Base beta packs:

Pack	Focus	Status
support	Support workflows, knowledge search, CRM-style writes	beta
research	Document search, citations, claim extraction	beta
ops	Incident workflows, runbooks, guarded mock tool definitions	beta

Ops tools are blocked by default and require explicit high-risk tool permission. The OpsPack governance contract is beta; real service restarts, alert acknowledgements, metrics backends, incident systems, and runbook backends are environment-specific integrations outside the strict beta core. Additional packs or extensions should be treated as examples or experimental until their manifests, permissions, exposed tools, and eval coverage are explicitly stabilized.

[domains.permissions]
allow_high_risk_tools = true

Storage And Retrieval

Default local mode uses in-memory stores and keyword retrieval. Production-style configs can use JSON file storage. Memory governance, lifecycle, import/export, and reindex are part of the beta core. OpenAI embeddings are a beta adapter for semantic retrieval. External-service backends such as PostgreSQL, Redis, Qdrant, and pgvector are deployment adapters outside the strict beta core. GraphRAG is opt-in and disabled by default.

Useful docs:

• Documentation index
• Architecture
• Getting started
• Runnable examples
• Evals and release gate
• HTTP API
• DomainPacks
• Memory
• Observability
• Reliability
• Security
• Tool safety
• Feature matrix
• Limitations

Project Layout

src/
  agent/          runtime, ReAct loop, builder
  tools/          tool registry and tool execution
  policy/         policy engine and built-in rules
  approval/       human-in-the-loop approval store
  memory/         layered memory and retrieval pipeline
  graph/          graph store and GraphRAG support
  domain/         DomainPack trait, registry, built-in packs
  state/          workflow state and resumability
  storage/        store factories and persistence adapters
  observability/  traces and event names
  server/         HTTP API
  cli/            command-line interface
config/           safe generic TOML profiles and production-style template
docs/             organized guides, architecture, deployment, and references
examples/         maintained examples and runnable references
evals/            TOML scenario datasets
scripts/          release smoke gate and maintenance helpers

Stability

Arasaka is beta software (0.2.0-beta.1). The core runtime, CLI, HTTP API, approval flow, JSON/in-memory memory stores, memory governance/lifecycle/admin operations, eval runner/datasets/reports, maintained governed examples, and base DomainPacks (support, research, ops) are the supported path. Advanced interfaces, benchmark/performance harnesses, and experimental integrations are documented in docs/advanced.md and docs/feature-matrix.md.

License

MIT. See LICENSE.