Railway Deployment

Railway provides the fastest path to a cloud-hosted Agentcy instance. You get managed PostgreSQL and Redis, automatic deployments from Git, and a generous free tier to start.

Architecture

Railway hosts the frontend, backend, Postgres, and Redis. The Context Engine is external: on the Basic provider it's Neo4j AuraDB (no Railway-native Neo4j plugin) — pass the neo4j+s:// URI as a backend env var. On the Advanced provider, deploy kyma as a third Railway service and point it at an S3-compatible bucket (Cloudflare R2 has zero egress and works great for this).

One-Click Deploy

The template creates all required services and wires up environment variables automatically.

Manual Setup

If you prefer to configure each service yourself:

Step 1: Create a New Project

1. Go to railway.app and create a new project
2. Choose Empty Project

Step 2: Add Infrastructure Services

PostgreSQL

1. Click + New > Database > PostgreSQL
2. Railway provisions a managed PostgreSQL 16 instance automatically
3. Note the DATABASE_URL from the service variables — it is injected as a reference variable

Redis

1. Click + New > Database > Redis
2. Railway provisions a managed Redis 7 instance
3. Note the REDIS_URL from the service variables

Neo4j (AuraDB) — Basic Context Engine

Railway does not offer a native Neo4j plugin. Use Neo4j AuraDB instead:

1. Go to console.neo4j.io
2. Create a free-tier AuraDB instance
3. Note the connection URI (neo4j+s://xxxxx.databases.neo4j.io), username, and password
4. You will add these as environment variables on the backend service

AuraDB Free Tier

The free tier includes 200K nodes and 400K relationships — sufficient for most small-to-medium deployments. Upgrade to AuraDB Professional for larger knowledge graphs.

Step 3: Deploy the Backend

1. Click + New > GitHub Repo
2. Connect your fork of the Agentcy repository
3. Set the Root Directory to / (or backend/ if deploying from a monorepo split)
4. Set the Build Command: cargo build --release -p agentcy-api
5. Set the Start Command: ./target/release/agentcy-api
6. Add environment variables (see Environment Variables)

Step 4: Deploy the Frontend

1. Click + New > GitHub Repo (same repo, different service)
2. Set the Root Directory to frontend/
3. Set the Build Command: npm ci && npm run build
4. Set the Start Command: npm start
5. Add the environment variable:
   • NEXT_PUBLIC_API_URL = the backend service URL (e.g., https://agentcy-backend-production.up.railway.app/api/v1)

Environment Variables

Configure these on the backend service:

Required

Variable	Value	Source
DATABASE_URL	${{Postgres.DATABASE_URL}}	Railway reference variable
REDIS_URL	${{Redis.REDIS_URL}}	Railway reference variable
NEO4J_URI	neo4j+s://xxxxx.databases.neo4j.io	From AuraDB console
NEO4J_USER	neo4j	From AuraDB console
NEO4J_PASSWORD	Your AuraDB password	From AuraDB console
LLM_API_KEY	sk-ant-...	Your Anthropic or OpenAI key
LLM_PROVIDER	anthropic	anthropic or openai

Recommended

Variable	Value	Description
AUTH_PROVIDER	local	Use oidc for SSO
JWT_SECRET	(generate a random 64-char string)	Used for signing JWTs
CORS_ORIGINS	https://your-frontend.up.railway.app	Frontend origin for CORS
LOG_LEVEL	info	debug for troubleshooting
RUST_LOG	agentcy_api=info	Rust-specific log filtering

Secrets

Never commit API keys or passwords to your repository. Always use Railway's environment variables UI or railway variables set.

Custom Domains

1. Go to the frontend service Settings > Networking
2. Click Generate Domain for a *.up.railway.app subdomain, or
3. Click Custom Domain and add your own domain
4. Update DNS with the provided CNAME record
5. Railway provisions TLS certificates automatically

Repeat for the backend service if you want a custom API domain. Update NEXT_PUBLIC_API_URL and CORS_ORIGINS accordingly.

Deployment Workflow

Railway deploys automatically when you push to your connected branch:

git push origin main
# Railway detects the push and builds both services

To deploy manually:

npm install -g @railway/cli
railway login
railway up

Costs Estimate

Railway uses usage-based pricing. Estimated monthly costs for a small team:

Service	Estimated Cost
Backend (Rust binary, ~256 MB RAM)	$5/mo
Frontend (Next.js, ~256 MB RAM)	$5/mo
PostgreSQL (1 GB)	$5/mo
Redis (25 MB)	$0/mo (included)
Neo4j AuraDB Free	$0/mo
Total	~$15/mo

Railway's Hobby plan ($5/mo) includes $5 of usage credits. The Pro plan ($20/mo) includes $10 of credits and higher resource limits.

Cost Optimization

• Use Railway's sleep feature to pause services during off-hours
• The Rust backend is very memory-efficient — 256 MB handles most workloads
• Monitor usage in the Railway dashboard to avoid unexpected charges

Troubleshooting

Build fails for the backend

Rust builds require significant memory. If the build is killed:

1. Go to service Settings > Build
2. Increase the build memory limit (Railway defaults may be insufficient for Rust)
3. Consider using pre-built Docker images instead:
   • Set Source to Docker Image
   • Image: ghcr.io/agentcy/backend:latest

Frontend cannot reach backend

Verify that:

1. NEXT_PUBLIC_API_URL points to the backend's Railway URL (including /api/v1)
2. CORS_ORIGINS on the backend includes the frontend's Railway URL
3. Both services are deployed and healthy (check Railway dashboard logs)

Database connection timeouts

Railway's internal networking uses private URLs. Use reference variables (${{Postgres.DATABASE_URL}}) instead of hardcoded connection strings to ensure you are using the internal network.

Context Engine

Railway deployments default to the Basic Context Engine (Neo4j-compatible via AuraDB) — production-ready and the path most teams pick on Railway.

The Advanced Context Engine is powered by kyma, Agentcy's Rust-based columnar engine with KQL/SQL/time-series and OTLP/Kafka ingest paths. To run it on Railway:

1. Deploy ghcr.io/agentcylabs/kyma:latest as a third Railway service.
2. Add a Cloudflare R2 bucket (zero-egress, S3-compatible) and set KYMA_OBJECT_STORE_URL=s3://your-bucket, AWS_ENDPOINT_URL, and the R2 access keys on the kyma service.
3. On the API service set CONTEXT_ENGINE=advanced, KYMA_BASE_URL=http://kyma.railway.internal:8080, KYMA_TOKEN=..., and drop NEO4J_*.

Agentcy Cloud also offers a fully-managed Advanced engine — bring-your-own-bucket (AWS S3, GCS, R2, MinIO) is supported there for data residency. See agentcylabs.com.