Quickstart

Get Everruns running with Docker Compose in 5 minutes

Get Everruns up and running with Docker Compose, create your first agent, and send a message.

Prerequisites

• Docker and Docker Compose installed
• Python 3 (for encryption key generation)
• curl (for API requests)

Deploy with Docker Compose

1. Download Docker Compose file

   Create a directory and download the production-ready compose configuration:

   mkdir everruns && cd everruns
   curl -o docker-compose.yaml https://raw.githubusercontent.com/everruns/everruns/main/examples/docker-compose-full.yaml
   
2. Generate encryption key

   Generate a secure encryption key for storing secrets:

   python3 -c "import os, base64; print('kek-v1:' + base64.b64encode(os.urandom(32)).decode())"
   

   Copy the output (starts with kek-v1:).

3. Create environment file

   Create a .env file with your encryption key:

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

   Replace <your-key> with the key from step 2.

4. Start services

   Launch all services (PostgreSQL, Server, Workers, UI):

   docker compose up -d
   

   This starts:

   • PostgreSQL database (port 5432)
   • Everruns server (port 9300)
   • 3 worker instances
   • Web UI (port 9300)
5. Verify deployment

   Check that services are running:

   docker compose ps
   curl http://localhost:9300/health
   

   You should see all services as “Up” and the health endpoint returning {"status":"ok"}.

Access the Platform

Web UI

Management dashboard at http://localhost:9300

API

REST API at http://localhost:9300/api/v1

Create Your First Agent

Use the API to create an agent with capabilities:

curl -X POST http://localhost:9300/v1/agents \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Assistant",
    "system_prompt": "You are a helpful assistant with access to web search and file management.",
    "capabilities": [
      "current_time",
      "web_fetch",
      "session_file_system"
    ]
  }'

Response:

{
  "id": "01933b5a-0000-7000-8000-000000000001",
  "name": "Assistant",
  "system_prompt": "You are a helpful assistant with access to web search and file management.",
  "capabilities": ["current_time", "web_fetch", "session_file_system"],
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z"
}

Save the id field - you’ll need it to create a session.

Create a Session

Sessions are where conversations happen. Create one with your agent:

curl -X POST http://localhost:9300/v1/sessions \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "01933b5a-0000-7000-8000-000000000001"
  }'

Response:

{
  "id": "01933b5a-0000-7000-8000-000000000100",
  "agent_id": "01933b5a-0000-7000-8000-000000000001",
  "status": "idle",
  "created_at": "2024-01-15T10:31:00Z"
}

Save the session id for sending messages.

Send a Message

Send your first message to the agent:

curl -X POST http://localhost:9300/v1/sessions/01933b5a-0000-7000-8000-000000000100/messages \
  -H "Content-Type: application/json" \
  -d '{
    "message": {
      "content": [
        {"type": "text", "text": "What is the current time?"}
      ]
    }
  }'

This triggers the agent to process your message and generate a response.

Stream Events

Watch the agent’s response in real-time using Server-Sent Events (SSE):

curl -N http://localhost:9300/v1/sessions/01933b5a-0000-7000-8000-000000000100/sse

You’ll see events like:

• turn.started - Agent begins processing
• tool.started - Agent calls the get_current_time tool
• tool.completed - Tool execution finishes
• llm.generation - LLM generates response
• output.message.completed - Final response ready
• turn.completed - Processing complete

View Message History

Retrieve the conversation:

curl http://localhost:9300/v1/sessions/01933b5a-0000-7000-8000-000000000100/messages

Response:

{
  "data": [
    {
      "role": "user",
      "content": [{"type": "text", "text": "What is the current time?"}]
    },
    {
      "role": "tool_result",
      "content": [{
        "type": "tool_result",
        "tool_call_id": "...",
        "result": "2024-01-15T10:32:00Z"
      }]
    },
    {
      "role": "agent",
      "content": [{
        "type": "text",
        "text": "The current time is January 15, 2024 at 10:32 AM UTC."
      }]
    }
  ]
}

Next Steps

Core Concepts

Learn about agents, sessions, and capabilities

API Reference

Explore all API endpoints

Capabilities

Discover available capabilities

Installation Guide

Production deployment and configuration

This quickstart uses anonymous authentication mode (no login required). For production deployments, see the Authentication Guide to configure user accounts and OAuth.