---
title: "Deploy Evo AI"
description: "Self-hosted AI agent platform with LangGraph workflows and MCP tools"
category: "AI/ML"
url: https://railway.com/deploy/evo-ai
---

# Deploy Evo AI

Self-hosted AI agent platform with LangGraph workflows and MCP tools

**[Deploy Evo AI on Railway](https://railway.com/template/evo-ai)**

- **Creator:** A3A
- **Category:** AI/ML
- **Total deploys:** 1

## Template content

### evo-ai-frontend https://raw.githubusercontent.com/evolution-foundation/evo-ai/main/frontend/public/favicon.svg

- **Source:** https://github.com/gridalpha/evo-ai-railway
- **Health check:** /login
- **Public domain:** Yes

### Postgres https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### mailpit https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/mailpit.svg

- **Image:** axllent/mailpit:latest
- **Health check:** /livez
- **Public domain:** Yes

### evo-ai-api https://raw.githubusercontent.com/evolution-foundation/evo-ai/main/frontend/public/favicon.svg

- **Source:** https://github.com/gridalpha/evo-ai-railway
- **Health check:** /
- **Public domain:** Yes

## Documentation

# 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.

![Diagram of the Evo AI API, frontend, Postgres and Mailpit services on Railway](https://res.cloudinary.com/rroe4rtk/image/upload/v1787350996/evo-ai-architecture.png)

## 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`.

![Evo AI agents list with four LLM agents for warranty support](https://res.cloudinary.com/rroe4rtk/image/upload/v1787351001/evo-ai-agents.png)
![Evo AI new agent form with role, goal and model settings](https://res.cloudinary.com/rroe4rtk/image/upload/v1787351007/evo-ai-agent-builder.png)
![Evo AI catalogue of Brave Search, GitHub and other MCP servers](https://res.cloudinary.com/rroe4rtk/image/upload/v1787351010/evo-ai-mcp-servers.png)
![Evo AI admin client list with two tenant organisations](https://res.cloudinary.com/rroe4rtk/image/upload/v1787351012/evo-ai-clients.png)

## 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](https://github.com/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

| Variable | Service | Purpose |
|---|---|---|
| `ADMIN_EMAIL` / `ADMIN_INITIAL_PASSWORD` | evo-ai-api | First administrator; read the password from the Variables tab |
| `ENCRYPTION_KEY_SEED` | evo-ai-api | Seeds the key encrypting provider keys — never change it |
| `JWT_SECRET_KEY` | evo-ai-api | Signs session tokens; changing it logs everyone out |
| `API_URL` / `APP_URL` | evo-ai-api | Public backend and frontend URLs, used in agent cards and emailed links |
| `MP_UI_AUTH` | mailpit | `user:password` guarding the inbox |

### Deployment Dependencies

- Source: [github.com/evolution-foundation/evo-ai](https://github.com/evolution-foundation/evo-ai)
- Images: [evoapicloud/evo-ai](https://hub.docker.com/r/evoapicloud/evo-ai), [evoapicloud/evo-ai-frontend](https://hub.docker.com/r/evoapicloud/evo-ai-frontend)
- Runtime: Python 3.10 / FastAPI, Node.js 20 / Next.js 15, PostgreSQL 13+
- A2A protocol: [google.github.io/A2A](https://google.github.io/A2A/)

## Hardware Requirements for Self-Hosting Evo AI

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 1 vCPU total | 2–4 vCPU |
| RAM | 1 GB backend, 512 MB frontend | 2 GB backend, 1 GB frontend |
| Storage | 1 GB for PostgreSQL | 5 GB+ as sessions build up |
| Runtime | Python 3.10, Node.js 20, PostgreSQL 13+ | Same |

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.


## Similar templates

- [Chat Chat](https://railway.com/deploy/-WWW5r) — Chat Chat, your own unified chat and search to AI platform.
- [stella](https://railway.com/deploy/stella) — Self-host stella with web, API, Postgres, Redis, and object storage.
- [Hermes Agent | OpenClaw Alternative with Dashboard](https://railway.com/deploy/hermes-agent-or-openclaw-alternative-wit) — Self-Hosted Hermes AI Agent for Telegram, Discord & Slack

Open this page in a browser: https://railway.com/deploy/evo-ai