project
A human-readable project identifier used for grouping related services.
Project services
Use relay.json when the app needs other containers beside it.
Relay can start Postgres, Redis, MySQL, and Mongo as companion containers on the same Docker network as your app. The app receives connection URLs automatically, and the dashboard can list the live services.
Minimal relay.json
{
"project": "myapp",
"services": [
{ "name": "db", "type": "postgres", "version": "16" },
{ "name": "cache", "type": "redis", "version": "7" },
{ "name": "web", "type": "app" }
]
}relay.json shape
The file describes the project and the named companion services.
`relay.json` is read from the repo root. It is separate from `.relay.json` and `relay.config.json` because it describes the runtime topology of the deployed project, not CLI defaults or buildpack overrides.
services
A list of named service containers like Postgres, Redis, MySQL, Mongo, and the main app service.
name, type, version
The service name becomes the hostname on the Docker network. Type and version select the image and default URL wiring.
Service networking
Relay creates one shared Docker network per app/env/branch.
The network name follows the deploy slot, so the app container and its companion services can resolve each other by hostname. Relay also injects connection URLs into the app container so you do not have to hand-wire the obvious cases.
db
Reachable from the app as `db` inside the network.
cache
Reachable from the app as `cache` inside the network.
DB_URL
Injected when a database service exists.
CACHE_URL
Injected when a cache service exists.
Typical injected URLs
DB_URL=postgres://postgres:postgres@db:5432/app
CACHE_URL=redis://cache:6379
MONGO_URL=mongodb://mongo:27017/appOperating services
Services are part of the deploy slot, not a separate database control plane.
Relay keeps these containers near the app because the goal is convenient companion services for previews and self-hosted environments. Persistent named volumes keep database state between container restarts.
Bridge network
Created as relay-<app>-<env>-<branch>.
Named volumes
Used for Postgres, MySQL, Redis, and Mongo persistence.
/api/projects
Lists projects with live services and connection strings.
Dashboard services panel
Shows running companion containers and copyable URLs.
Project inventory
GET /api/projects
[
{
"app": "demo",
"services": [
{ "name": "db", "type": "postgres", "connection_url": "postgres://..." }
]
}
]