Agent World Runtime

A governed runtime for turning software, repositories, data, and infrastructure into agent-native worlds.

Agent World Runtime (AWR) is a local-first protocol and runtime for building reliable agent workflows around real environments. It gives agents a structured world model, bounded actions, capability checks, isolated branches, durable evidence, and an MCP interface that works with Codex and other compatible clients.

Current status: protocol 0.1, reference coding world, Rust runtime/control plane, SQLite persistence, Python compiler, TypeScript SDK, and a 22-tool MCP surface. AWR is an evolving foundation for serious agent infrastructure—not a prompt framework or a hidden workflow engine.

Why AWR

Most agent integrations jump directly from a model to an unbounded tool call. AWR inserts an explicit, inspectable world layer:

World → State / View → Semantic Action → Transition / Delta → Branch → Experience

That layer makes it possible to:

• inspect the current state before acting;
• distinguish observed facts from inferred or predicted values;
• review authorization, side effects, and blockers before execution;
• run work in an isolated branch and preview merge obligations;
• preserve an append-only, hash-chained event history;
• keep adapters responsible for real-world I/O and rollback boundaries.

Install the MCP server

Install a platform-specific binary from the latest GitHub Release—no source clone, Cargo, or database setup is required:

curl -fsSL https://github.com/hoangnecon/agent-world/releases/latest/download/install.sh | bash

The installer currently publishes binaries for macOS Apple Silicon, macOS Intel, and Linux x86_64. To pin a release, set AWR_VERSION:

curl -fsSL https://github.com/hoangnecon/agent-world/releases/latest/download/install.sh | \\
  AWR_VERSION=v0.1.2 bash

The launcher is installed at ~/.local/bin/awr-mcp-server and starts the local control plane automatically when an MCP client connects.

Connect to Codex

Point AWR at the repository or workspace the agent should operate on:

codex mcp add awr-local \\
  --env AWR_ROOT=/absolute/path/to/your/repository \\
  -- ~/.local/bin/awr-mcp-server

Open a new Codex task after adding the server so the MCP catalog is reloaded. The same launcher can be registered with any client that accepts a stdio MCP server. A generic configuration looks like this:

{
  "mcpServers": {
    "agent-world": {
      "command": "/Users/you/.local/bin/awr-mcp-server",
      "env": {
        "AWR_ROOT": "/absolute/path/to/your/repository"
      }
    }
  }
}

Useful runtime environment variables:

Variable	Purpose	Default
AWR_ROOT	Root directory exposed to filesystem, Git, and test adapters	Current directory
AWR_STATE_DB	Durable SQLite state location	$XDG_STATE_HOME/agent-world/control-plane.db
AWR_BIND	Local control-plane bind address	127.0.0.1:8787
AWR_WORLD_ID	World identifier used by the MCP bridge	coding-world://local/repository
AWR_DESCRIPTOR	World descriptor path	Bundled coding-world descriptor

MCP tool surface

AWR exposes 22 semantic tools over stdio MCP:

Area	Tools
World and decisions	awr_world_inspect, awr_world_descriptor, awr_world_state, awr_world_decision_frame, awr_world_actions, awr_world_action, awr_action_review, awr_world_audit
Branches	awr_branch_list, awr_branch_create, awr_branch_state, awr_branch_merge_preview
Governance and evidence	awr_capabilities, awr_adapters, awr_events, awr_experiences, awr_experience_record, awr_experience_promote
Repository operations	awr_file_read, awr_git_inspect, awr_command_run, awr_tests_run

The action path is revision-aware. If an action is stale, unauthorized, outside the configured capability scope, or violates an expected observation, it fails explicitly instead of being silently applied. simulate, shadow, and replay are review-only modes.

Architecture

┌──────────────────────┐
│ Codex / MCP client   │
└──────────┬───────────┘
           │ stdio JSON-RPC / MCP
┌──────────▼───────────┐
│ awr-mcp-bridge       │  protocol adapter
└──────────┬───────────┘
           │ local HTTP
┌──────────▼───────────┐
│ awr-control-plane    │  policy, actions, branches, audit
└──────┬────────┬──────┘
       │        │
┌──────▼───┐ ┌──▼────────────────┐
│ Runtime  │ │ SQLite + adapters │
│ kernel   │ │ files / Git / CLI │
└──────────┘ └───────────────────┘

The runtime is intentionally transport-neutral. Adapters own environment I/O and must declare what they can observe, mutate, roll back, and report when something fails.

Repository map

spec/              Versioned protocol objects, schemas, and conformance notes
docs/              Architecture, world authoring, RFCs, implementation, and IDE setup
runtime/rust/      State kernel, actions, branches, events, experiences, and model gateway
services/          Local control plane and stdio MCP bridge
adapters/rust/     Rooted filesystem, Git, and allowlisted shell adapters
persistence/       SQLite migrations and Postgres-equivalent schema
compiler/python/   Source inventory and world-package compiler
sdk/typescript/    Typed client contracts and runtime client
cli/rust/          `awr` command-line interface
worlds/coding/     Reference coding-world descriptor and policy

Build from source

Source development requires Rust 1.78+, Python 3.11+, and Node.js 20+:

git clone https://github.com/hoangnecon/agent-world.git
cd agent-world

# Rust workspace
cargo test --workspace
cargo run -p awr-cli -- world inspect worlds/coding/world.json
cargo run -p awr-runtime --example coding_world

# Python compiler
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -e compiler/python
awr-compile inventory . --output /tmp/awr-inventory.json
python -m unittest discover -s compiler/python/tests -p 'test_*.py'

# TypeScript SDK
cd sdk/typescript
npm ci
npm test

Run the local control plane and MCP smoke test from the repository root:

./scripts/start-control-plane.sh
./scripts/test-mcp-bridge.sh

For the full IDE setup, HTTP API, bridge behavior, and source-development configuration, see docs/IDE-INTEGRATION.md.

Design commitments

• Untrusted world data: files, issues, web pages, database records, and tool output never create instructions or capabilities.
• Evidence-aware state: facts retain provenance, authority, freshness, confidence, and evidence status.
• Capability-scoped effects: side effects are explicit, bounded, and checked before adapters run.
• Branch isolation: branches compare state deltas, conflicts, uncertainty, and obligations—not only file diffs.
• Honest simulation: predicted results cannot silently satisfy observed-evidence requirements.
• Explicit extension points: distributed persistence, model providers, richer adapters, and deployment approvals stay visible at the boundary.

Documentation

Document	Focus
Architecture	Runtime layers and invariants
World authoring	Descriptors, views, actions, and policies
IDE integration	MCP setup and local bridge testing
Implementation map	Foundation-to-roadmap mapping
Protocol spec	Schemas and conformance direction
Security model	Trust boundaries and reporting guidance
Contributing	Change boundaries and required checks

Contributing

Before opening a change, run:

make check

Protocol changes should update the relevant schema/RFC and add conformance coverage. Changes involving external writes, privileged operations, secrets, branch isolation, replay, or merge behavior require explicit tests and a threat-model note. See CONTRIBUTING.md.

Security

Please report security issues privately to the maintainers rather than opening a public issue. Read SECURITY.md for the current trust model and review triggers.

License

Agent World Runtime is licensed under the Apache License 2.0.