EverRun Agent

EverRun Agent is a local durability layer for autonomous agents. It stores mission progress outside the conversation, records external effects before they run, and calculates the safest recovery action after a crash, restart, or handoff.

Clone to ready

On a server with Python 3.11 or newer, clone the repository and run one command:

git clone https://github.com/UcelX/everrun-agent.git
cd everrun-agent
./install.sh

The bootstrapper creates an isolated virtual environment, installs EverRun with MCP support, creates private state storage, detects Hermes when available, installs the profile-local MCP server and lifecycle policy, then runs an authoritative readiness check. It exits nonzero unless every selected component is ready.

For unattended servers:

./install.sh --agent hermes --profile default --non-interactive

Core-only installation, without an agent integration:

./install.sh --agent none --non-interactive

The installed CLI path and machine-readable report are printed at the end. Verify again anytime:

~/.local/share/everrun-agent/venv/bin/everrun doctor \
  --agent hermes --profile default \
  --state-dir ~/.local/share/everrun-agent/state

Upgrade idempotently by pulling the repository and rerunning ./install.sh --upgrade. Safe uninstall removes the managed runtime and unchanged EverRun integration while preserving mission state:

./install.sh --agent hermes --profile default --uninstall --non-interactive

It is built for work that cannot safely restart from the beginning: deployments, publishing, batch processing, infrastructure changes, payments, and other multi-step operations with real side effects.

EverRun is not another agent. It is the durable mission layer underneath an agent you already run.

Related MCP server: worldmodel-mcp

Why EverRun?

What it is for

• Long-running coding-agent tasks that may cross sessions

• Deployments and infrastructure changes

• Content production with approval gates

• Batch processing and data pipelines

• Payments, notifications, and other external side effects

• Agent handoff between profiles or processes

What it is not

• A hosted orchestration platform

• A replacement for your agent, queue, database, or provider

• A guarantee that an unknown external system executed exactly once

• An operating-system sandbox

• A cloud synchronization service

The problem

An agent can lose its context while the world keeps changing. A process may die after an API call succeeds but before the result reaches the transcript. Retrying blindly can publish twice, charge twice, or repeat an infrastructure change.

EverRun separates three things that normal agent transcripts mix together:

• what the agent intended to do;

• what the durable event log proves happened;

• what still needs an authoritative check.

After an interruption, EverRun returns one recovery mode and one next safe action. An unresolved effect becomes reconcile, never an assumed success or an automatic retry.

Core guarantees

How recovery works

agent starts mission
        |
        v
record progress and checkpoints
        |
        v
claim external effect before firing it
        |
        +---- process survives ----> complete action
        |
        +---- process dies --------> action remains uncertain
                                          |
                                          v
                                 fresh agent inspects reality
                                          |
                                          v
                                 reconcile occurred / not occurred
                                          |
                                          v
                                 operator review and explicit close

Recovery precedence is conservative:

corrupt chain       -> abort
uncertain effect    -> reconcile
unconfirmed work    -> request_review
goal reached        -> close_mission
otherwise           -> continue_work

Installation

EverRun requires Python 3.11 or newer. It is a local library: mission data stays on the machine where the agent runs.

From a checkout

git clone https://github.com/UcelX/everrun-agent.git
cd everrun-agent
python3 -m venv .venv
. .venv/bin/activate
python -m pip install '.[mcp]'

For development

python -m pip install '.[dev]'
pytest -q

The mcp extra is required only for the native MCP server and Hermes integration. The core library has no runtime dependency.

Editable development install

python -m pip install -e '.[mcp]'

Development environment

python -m pip install -e '.[dev]'
pytest -q
ruff check src tests scripts
ruff format --check src tests scripts
mypy src/everrun_agent
python -m build

Quick start

Create a mission and record progress:

everrun init release-1 "Ship the release" --total 3
everrun record-decision release-1 restart-policy "Do not restart production during traffic"
everrun complete-work release-1 build
everrun checkpoint release-1 --reason milestone
everrun status release-1 --json
everrun resume release-1 --json

resume exits with code 0 only when the returned state is safe. Unsafe, corrupt, review-required, or reconciliation states use a nonzero exit code, so shell automation can fail closed:

everrun resume release-1 && ./continue-agent.sh

A mission reaches verified_complete only through explicit closure:

everrun close release-1

Closure is rejected if progress is incomplete, the chain is invalid, agent-reported work is unconfirmed, a success contract is unmet, or any side effect remains unresolved.

External effects

Use the action ledger for anything that changes another system.

from everrun_agent import ActionLedger, EverRunStore, Mission
from everrun_agent.gate import protected_call

with EverRunStore("mission.db") as store:
    store.create_mission(Mission("deploy-1", "Deploy the service", 1))
    ledger = ActionLedger(store, "deploy-1")

    result = protected_call(
        ledger,
        "deploy.production",
        {"commit": "abc123"},
        run_deploy,
    )

If the process dies after run_deploy() changes production but before completion is recorded, a fresh process receives reconcile. It must inspect production and settle the action before continuing.

Hermes Agent integration

Install and verify the native MCP integration with one command:

everrun integrate hermes --profile default

For another Hermes profile:

everrun integrate hermes --profile creator

The installer first verifies the MCP dependency, then creates profile-local state, pins the authenticated stdio identity, registers the exact 13-tool contract, installs the everrun-lifecycle policy skill, and rolls back its newly-created MCP/skill assets if verification fails. The skill makes normal multi-step prompts discover/start/checkpoint automatically; users do not need to dictate EverRun tool names. Install with everrun-agent[mcp] (or source extra .[mcp]) before running integration.

Useful integration commands:

# Preview without changing Hermes
everrun integrate hermes --profile creator --dry-run

# Remove the EverRun MCP entry and unchanged EverRun-owned lifecycle skill
everrun integrate hermes --profile creator --uninstall

At the start of a fresh session, the agent can discover work without knowing a mission ID:

everrun list-missions --status blocked --json
everrun inspect <mission-id> --json

Operator approval

Agent progress is not self-certifying. The operator creates a digest-bound approval request through a separate trusted surface:

everrun approval-request release-1 --ttl 300

The response includes a single-use ticket, current recovery digest, expiry, progress, and pending risk count. Approval succeeds only if the mission state still matches that digest:

everrun approve release-1 <ticket> <digest> --operator release-manager

Tickets are stored only as hashes, expire automatically, and cannot be replayed.

Mission discovery and inspection

everrun list-missions --status active --json
everrun list-missions --status blocked --json
everrun list-missions --status review-required --json
everrun list-missions --status completed --json

The combined inspection view reports progress, recovery mode, next safe action, chain integrity, checkpoint state, approval coverage, recent events, and a secret-safe action summary:

everrun inspect release-1 --json

Checkpoints, environment pins, and handoff

Seal a checkpoint:

everrun checkpoint release-1 --reason pre-deploy

Pin facts that must remain stable:

everrun pin-env release-1 dataset=v3 model=opus
everrun declare-dep release-1 index dataset
everrun check-env release-1 dataset=v3 model=opus --json

Transfer a mission to another agent:

everrun handoff release-1 hermes --context-tokens 8000

The handoff includes verified progress, unresolved effects, decisions, the next safe action, and forbidden actions. EverRun refuses the handoff while an effect is uncertain.

Portable capsules

Export, sign, and verify mission state:

everrun keygen --out signer.key
everrun export release-1 mission.rly
everrun sign mission.rly --key signer.key --signer workstation
everrun verify-capsule mission.rly --key signer.key --signer workstation

Unsigned imports are rejected by default. A redacted export is safe to share but intentionally cannot be imported as trusted state.

Crash verification

Run the deterministic crash-recovery demo:

everrun demo --root /tmp/everrun-demo --total 100 --crash-at 40 --json

Expected invariants:

{
  "chain_valid": true,
  "completed": 100,
  "duplicates": 0,
  "side_effect_count": 1,
  "unique_outputs": 100
}

The test suite also performs real process-death fault injection on POSIX systems and verifies recovery at multiple interruption points. A separate opt-in Hermes harness waits for an authoritative boundary marker before sending literal SIGKILL and validating state from a fresh process.

MCP tools

The native MCP server exposes 13 tools:

everrun_start
everrun_record_work
everrun_checkpoint
everrun_claim_action
everrun_complete_action
everrun_reconcile_action
everrun_list_actions
everrun_list_missions
everrun_inspect
everrun_status
everrun_resume
everrun_briefing
everrun_close

Mutating tools deny access by default. Stdio integrations must pin a transport identity. Multiplexed transports must prove client identity with a per-client token. Operator approval authority is not exposed through the worker MCP surface.

Platform support

CI covers:

• Linux, macOS, and Windows;

• Python 3.11, 3.12, and 3.13;

• package build, unit and integration tests, Ruff, and strict Mypy;

• supported MCP 1.x resolution and explicit MCP 2.x conflict detection.

Literal POSIX SIGKILL and POSIX permission-bit tests run only on operating systems that provide those semantics. Windows runs the remaining persistence, recovery, integrity, concurrency, and MCP tests.

Project status

EverRun Agent is currently alpha software. The local durability core and Hermes integration are implemented and tested. Keep backups of important mission databases and evaluate the library in a controlled environment before relying on it for production changes.

See:

• ARCHITECTURE.md for invariants and modification rules;

• REQUIREMENTS.md for requirement-to-test traceability;

• SECURITY.md for the security policy;

• CONTRIBUTING.md for development workflow.

Limitations

• SQLite is single-host. The PostgreSQL backend is a contract, not an implementation.

• Attestation uses symmetric HMAC in v0.1. Anyone who can verify with the shared key can also sign.

• The command verifier enforces an allowlist but is not an operating-system sandbox.

• Exactly-once execution across an unknown crash gap is impossible. EverRun blocks and requires reconciliation instead.

• Capsules provide integrity, not encryption.

• The package does not include a hosted control plane, dashboard, RBAC, or cloud synchronization.

License

EverRun Agent is licensed under the Apache License 2.0. See LICENSE and NOTICE.