Deploy Evo AI

Deploy and Host Evo AI on Railway

Evo AI is an open-source platform for building, running and sharing AI agents. It wraps Google's Agent Development Kit (ADK), LangGraph and CrewAI in a visual builder, so an agent is a role, a goal, instructions, a model and the tools it may reach — not a codebase you maintain. Every agent speaks Google's Agent-to-Agent (A2A) protocol and publishes a standard agent card. Teams reach for it when they want one shared place for prompt-and-tool work that product people edit and engineers call over HTTP.

This template lets you deploy Evo AI on Railway as a working stack rather than a single container. It runs four services: the FastAPI backend that executes agents and serves the A2A endpoints, the Next.js frontend people log into, a PostgreSQL database holding agents, tenants and sessions, and Mailpit as the mail server the platform needs for verification and password resets. Both web services get a public domain; Postgres and Mailpit's SMTP listener stay private.

Getting Started with Evo AI on Railway

Open the frontend URL once the deploy is green and you land on the sign-in page. The administrator is created on first boot from ADMIN_EMAIL and ADMIN_INITIAL_PASSWORD — read the password from the evo-ai-api Variables tab, sign in, then change it under My Account. Agents belong to a tenant, so start with Clients → New Client, then Enter as client from that row's menu. Inside the tenant, add your model provider key under API Keys — encrypted before it reaches the database — and create an agent with New Agent, giving it a name, role, goal and instructions and picking the key and model. Each agent immediately publishes an A2A card — the quickest health check — and Chat lets you talk to it. Colleagues sign up through the Register tab; their verification email lands in the Mailpit inbox behind MP_UI_AUTH.

About Hosting Evo AI

Evo AI sits between a no-code agent builder and a framework. Agents are database rows rather than files in a repository, so a non-engineer can adjust a prompt or swap a model without a deploy, and the result is still an HTTP service your code can call. Self-hosting matters because agents carry provider API keys and see whatever data you feed them.

• Seven agent types — LLM, A2A, Sequential, Parallel, Loop, Workflow (LangGraph) and Task, composable as sub-agents
• Model-agnostic — OpenAI, Anthropic, Gemini, Groq and Cohere keys, encrypted per tenant
• MCP tools — a shared catalogue of Model Context Protocol servers (Brave Search, GitHub, GitLab, Sequential Thinking, Firecrawl) grantable per agent
• A2A protocol — agent cards, streaming, push notifications and task history
• Multi-tenant — an admin manages client organisations and can enter any of them
• Langfuse tracing — OpenTelemetry export of prompts, responses and tool calls

evo-ai-api does everything — migrations, the REST API, the chat WebSocket, agent execution, the A2A endpoints — and evo-ai-frontend calls it from the browser, holding no state. PostgreSQL owns every row, and Mailpit is the mail server the verification flow needs.

Why Deploy Evo AI on Railway

Railway removes the setup work this stack needs:

• Backend, frontend, database and mail server provisioned together and already wired
• Managed PostgreSQL with backups and a persistent volume
• Public HTTPS domains and certificates for both web services, no reverse proxy
• Private networking between the API, its database and the mail server
• Health checks, restarts and dashboard scaling as agent traffic grows

Common Use Cases for Self-Hosted Evo AI

• Internal support triage — an agent that classifies tickets, pulls out product and serial numbers and routes each to the right team
• Research pipelines — a Workflow agent chaining a web-search MCP server, a summariser and a formatter into one endpoint
• A2A interoperability — an agent partner systems call through its card, not a bespoke API

Dependencies for Evo AI

• evo-ai-api — evoapicloud/evo-ai:0.1.0, the backend and agent runtime, public on port 8000
• evo-ai-frontend — evoapicloud/evo-ai-frontend:0.1.0, the web UI, public on port 3000
• Postgres — Railway's managed PostgreSQL, private, holding all platform state
• mailpit — axllent/mailpit:latest, private SMTP on 1025, inbox on 8025, on a volume

Both images launch through the public source repository gridalpha/evo-ai-railway, which adds one boot script to each: the backend derives its encryption key, waits for PostgreSQL and seeds only the administrator and the tool catalogue; the frontend raises Node's keep-alive timeout above the edge.

Environment Variables Reference

Deployment Dependencies

• Source: github.com/evolution-foundation/evo-ai
• Images: evoapicloud/evo-ai, evoapicloud/evo-ai-frontend
• Runtime: Python 3.10 / FastAPI, Node.js 20 / Next.js 15, PostgreSQL 13+
• A2A protocol: google.github.io/A2A

Hardware Requirements for Self-Hosting Evo AI

Agent runs mostly wait on your model provider, so add memory before cores.

Self-Hosting Evo AI

The backend image runs migrations, seeds data and starts the API in one command. A minimal Docker run against an existing PostgreSQL:

docker run -d --name evo-ai -p 8000:8000 \
  -e POSTGRES_CONNECTION_STRING="postgresql://user:pass@db:5432/evo_ai" \
  -e JWT_SECRET_KEY="$(openssl rand -hex 32)" \
  -e ENCRYPTION_KEY="$(openssl rand -base64 32 | tr '+/' '-_')" \
  -e ADMIN_EMAIL="admin@yourdomain.dev" -e ADMIN_INITIAL_PASSWORD="change-me" \
  -e API_URL="https://api.yourdomain.dev" -e APP_URL="https://app.yourdomain.dev" \
  evoapicloud/evo-ai:0.1.0

ENCRYPTION_KEY is the one value you cannot invent freely: it goes to Fernet, so it must be exactly 32 random bytes in URL-safe base64. Anything shorter stops the container at import; leaving it empty mints a new key each start, quietly making stored provider keys undecryptable.

To run from source with the frontend, use the shipped Compose file:

git clone https://github.com/evolution-foundation/evo-ai.git
cd evo-ai && cp .env.example .env
docker compose up -d

How Much Does Evo AI Cost to Self-Host?

Evo AI is free and open source under Apache 2.0, with no paid tier, seat limits or feature gates. The running costs are infrastructure — on Railway, two web services, a managed PostgreSQL database and a small mail server, billed on what they use — plus what your model provider charges for the tokens your agents use.

FAQ

What is Evo AI? An open-source AI agent platform built on Google's Agent Development Kit. You define agents in a web UI — role, goal, instructions, model, tools — and each becomes a callable HTTP endpoint speaking the Agent-to-Agent protocol.

What does this Railway template deploy? The Evo AI backend, the Next.js frontend, a managed PostgreSQL database and a Mailpit mail server. Both web services get public HTTPS domains; the database and SMTP listener stay private.

Why does this template include a mail server? Every account other than the seeded administrator is created unverified and sign-in is refused until the emailed link is opened, so without SMTP nobody past the first admin can log in. Point SMTP_HOST at a real relay to deliver mail off the box.

Why does Evo AI need PostgreSQL? Users, tenants, agent definitions, encrypted provider keys, the MCP catalogue and sessions live there — the containers keep nothing, which is what makes a redeploy non-destructive.

How do I connect my own apps to a self-hosted Evo AI? Each agent exposes an A2A card at /api/v1/a2a//.well-known/agent.json and accepts JSON-RPC at /api/v1/a2a/, authenticated by an x-api-key header. Anonymous requests are rejected, so the card is safe to share.

Does self-hosted Evo AI support Anthropic and Gemini, not just OpenAI? Yes — keys are stored per tenant with a provider attached, and each agent's model dropdown covers OpenAI, Anthropic, Gemini, Groq and Cohere.