Everruns

Note: This repository is under active development. Expect rapid changes, experimental features, and unconventional approaches as we explore ideas quickly.

Headless durable agentic harness engine. Run durable AI agents reliably and scalably.

Overview

Everruns is a service that runs AI agents in the most reliable way possible. Each step and tool call in an agent run is persisted using a PostgreSQL-backed durable execution engine.

Key Features

• Durable execution: Agent sessions survive restarts via PostgreSQL-backed workflows
• Streaming events: Real-time SSE streaming of agent responses and tool calls
• Management UI: Dashboard for agents, sessions, and chat
• Extensible capabilities: Add tools and behaviors to agents via modular capabilities
• Multi-provider support: OpenAI, Anthropic, and more
• Open Responses: Vendor-neutral API for multi-provider LLM interfaces

Quick Start

Deploy Everruns with Docker Compose:

# Download docker-compose file
mkdir everruns && cd everruns
curl -o docker-compose.yaml https://raw.githubusercontent.com/everruns/everruns/main/examples/docker-compose-full.yaml

# Generate encryption key for secrets
python3 -c "import os, base64; print('kek-v1:' + base64.b64encode(os.urandom(32)).decode())"

# Create .env with your key
echo "SECRETS_ENCRYPTION_KEY=kek-v1:<your-key>" > .env

# Start services
docker compose up -d

Access the platform:

• Web UI: http://localhost:8080
• API Docs: http://localhost:8080/swagger-ui/

For detailed setup instructions, see the Docker Compose Quickstart.

Documentation

• Getting Started - Introduction and key concepts
• Docker Compose Quickstart - Full deployment guide
• API Reference - Complete API documentation
• Capabilities - Extend agent functionality

API Example

# Create an agent
curl -X POST http://localhost:8080/api/v1/agents \
  -H "Content-Type: application/json" \
  -d '{"name": "Assistant", "system_prompt": "You are a helpful assistant."}'

# Create a session (agent_id in request body)
curl -X POST http://localhost:8080/api/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "{agent_id}"}'

# Send a message
curl -X POST http://localhost:8080/api/v1/sessions/{session_id}/messages \
  -H "Content-Type: application/json" \
  -d '{"message": {"role": "user", "content": [{"type": "text", "text": "Hello!"}]}}'

Contributing

See CONTRIBUTING.md for local development setup and guidelines.

License

MIT