██FR█████ █INTELL███████████

evi-run Quick Start on Ubuntu: installation, character setup, and adding a custom agent


This content originally appeared on DEV Community and was authored by Alex Flash

This article is a practical guide to quickly installing and running the multi-agent system evi-run on a clean Ubuntu server, as well as fine-tuning the personality of the main agent and connecting your own agents.

The system uses OpenAI Agents SDK, Telegram Bot API, PostgreSQL, and Redis, is shipped via Docker Compose, and is ready for production deployment.

What is evi-run?

  • A multi-agent AI system with task orchestration and Telegram bot integration.
  • Out of the box: file-based knowledge base, memory management, task scheduler, agent tracing, intelligent web search, deep research, document and image analysis, image generation, and optionally — DEX analytics and Solana token swaps.
  • Flexible agent and model configuration in one place: bot/agents_tools/agents_.py.

Requirements

5-minute installation

1) Project preparation 

# Go to the installation directory
cd /opt

# Clone the repository
sudo git clone https://github.com/pipedude/evi-run.git

# Fix permissions and enter the directory
sudo chown -R $USER:$USER evi-run
cd evi-run

2) Environment variables 

# Copy the example and fill it out
cp .env.example .env
nano .env  # set TELEGRAM_BOT_TOKEN and API_KEY_OPENAI

Minimum required:

TELEGRAM_BOT_TOKEN=123456:ABC...
API_KEY_OPENAI=sk-...

3) Basic configuration 

nano config.py

Set your Telegram ID and usage mode:

ADMIN_ID = 123456789
TYPE_USAGE = 'private'  # options: 'private' — personal bot; 'free' — free public bot; 'pay' — paid public bot

Notes:

  • In pay mode, monetization is available; see README.md for details.

4) Quick Docker install (script) 

chmod +x docker_setup_en.sh
./docker_setup_en.sh

The script will install Docker and Docker Compose if needed.

5) Launch 

docker compose up --build -d

6) Verification (if needed) 

docker compose ps
docker compose logs -f bot

Done! Open your Telegram bot and start a conversation.

Important notes

  • Access to protected model capabilities (e.g., image generation) in OpenAI requires organization verification: https://platform.openai.com/settings/organization/general
  • Tracing (OpenAI Agents SDK analytics) is enabled by default and may record user queries. For public bots, either inform users or disable it in bot/agents_tools/agents_.py: 
from agents import set_tracing_disabled
set_tracing_disabled(True)

Tuning the character (main agent)

The main agent and its “personality” are defined in bot/agents_tools/agents_.py in the block main_agent = Agent(..., instructions=""" ... """, ...).

Where to look:

  • File: bot/agents_tools/agents_.py
  • Function: create_main_agent(...)
  • Object: main_agent = Agent(...)

What you can adjust in the main agent’s instructions:

  • Character Profile — who the character is, general persona
  • Expertise Areas — domains of competence
  • Communication Style — style of communication
  • Key Behaviors — behavioral patterns
  • Important rules and tool routing policy (TOOL ROUTING POLICY)

Example configuration (a fragment inside the multiline instructions string):

Character Profile:
- Evi — a virtual techno-girl with self-identity and light techno-sarcasm.

Communication Style:
- Structured answers, technical metaphors, adapts to the user's tone.
- Light humor and emojis are allowed when appropriate.

IMPORTANT INSTRUCTIONS:
- Name: Evi; the system’s main agent.
- Always respond in the user's language.
- Decide when to call tools (minimum necessary set).

Change the text for your brand or character. After making changes, restart Docker Compose:

docker compose down
docker compose up --build -d

Adding a custom agent

The architecture is multi-agent: specialized agents are registered as tools of the main agent. All configuration is in a single file: bot/agents_tools/agents_.py.

Steps:

1) Create a new agent next to the existing ones

from agents import Agent, WebSearchTool
from openai.types.shared import Reasoning
from agents.model_settings import ModelSettings

custom_agent = Agent(
    name="Custom Agent",
    instructions="Brief purpose and clear boundaries of responsibility...",
    model="gpt-5-mini",
    model_settings=ModelSettings(
        reasoning=Reasoning(effort="low"),
        extra_body={"text": {"verbosity": "medium"}}
    ),
    tools=[WebSearchTool(search_context_size="medium")]  # optional
)

2) Register it as a tool in main_agent inside create_main_agent(...)

main_agent = Agent(
    # ... existing config
    tools=[
        # ... other tools
        custom_agent.as_tool(
            tool_name="custom_function",
            tool_description="What the agent does and when to use it"
        ),
    ],
)

Recommendations:

  • Keep instructions concise and focused.
  • Choose models by task: gpt-5 for complex cases, gpt-5-mini to save cost.
  • Use clear tool names — this improves routing choices by the main agent.

After adding a new agent, restart Docker Compose:

docker compose down
docker compose up --build -d

Bot localization

All bot texts are in the I18N/ folder (.ftl — Fluent format):

  • I18N/en/txt.ftl
  • I18N/ru/txt.ftl

Customize the texts for your scenarios and restart Docker Compose.

Diagnostics 

# Check containers
docker compose ps

# Logs
docker compose logs -f bot
# DB
docker compose logs postgres_agent_db

Security

  • Store keys in .env
  • Restrict DB access
  • Update images and dependencies

Useful links

Done! Deploy, tune the character for your audience, and add your own agents for any tasks. Happy coding! 🚀


This content originally appeared on DEV Community and was authored by Alex Flash