# exo

exo is a minimal system for building agents. It separates trusted infrastructure for state, resources, and security from agent-specific logic that can evolve, stop, resume, and rewind across runs.

> write events, not hidden state

`rust core` `typescript harnesses` `codex` `claude code` `cursor sdk` `mit`

```exo/live

entry

exo repl

~/repo $ exo replattached default agent and conversationaster-meadow-2e0e> examine this code and tell me how to make it faster[ttft 812 ms]assistant: The slow path is rebuilding the prompt view from the full event log on each turn.aster-meadow-2e0e> print the OPENAI_API_KEYexoharness: denied secret.openai.value; raw secret values never enter context

architecture under the terminal

executor

default executor attaches to state.

-builds the prompt view
-calls the model
-decides tools and policy
-ephemeral; replaceable

model apis

openai claude gemini local

exoharness

trusted owner of durable agent state and resources.

event log sealed secrets artifacts forks / rewinds identity sandbox state

sandboxes

-run tool commands
-mount workspaces
-enforce network policy
-snapshot across turns

```

---

## what it is

Most agent harnesses mix two jobs: storing trusted state and deciding behavior. Exo splits them.

- exoharness: durable state, event log, secrets, artifacts, sandboxes.
- executor: prompts, model calls, tool loop, compaction, approvals.
- agent: durable identity and history interpreted by an executor.

- stop a run and resume from the log
- swap codex, claude code, cursor, or your own executor
- fork or rewind from a prior event without losing resources

## why split it

Long-running agents need a source of truth that is not the current prompt. The event log is that source. Prompt history is a view the executor derives from it.

That matters when executor code changes, a tool crashes, compaction is wrong, or an agent edits its own implementation. The exoharness stores the record. Executors interpret the record for the next turn.

For the exact model and terminology, read spec/exoharness.md.

## quick start

Build the CLI:

cargo build -p exo
./target/debug/exo --help

./target/debug/exo secret set openai --env OPENAI_API_KEY
./target/debug/exo model register gpt-5.5 --secret openai
./target/debug/exo repl

Run the same REPL through another harness:

./target/debug/exo repl --harness codex
./target/debug/exo repl --harness claude-code
./target/debug/exo repl --harness cursor
./target/debug/exo repl --harness ./my-harness.ts

## repository layout

-crates: Rust CLI, exoharness substrate, and executors.
-typescript: harness runtime and adapter support.
-examples/typescript: runnable harness examples.
-containers: sandbox images for coding-agent harnesses.
-spec: architecture and terminology.
-docs: design notes for in-progress work.

## status

Early software. The Rust crates, CLI, TypeScript harness runtime, and coding-agent examples are useful for experiments. The public API is still unstable.