Self-Hosting

Deploy the flexx relay and API on your own infrastructure. Docker Compose setup, required environment variables, and CLI configuration.

Architecture

The flexx platform consists of three backend services:

Service	Purpose	Default URL
BFF	API gateway (auth, OAuth 2.1, billing, remotes)	`bff.flexx.dev`
Relay	WebSocket hub for MCP and SSH	`relay.flexx.dev`
Dashboard	Web UI for managing remotes and onboarding	`app.flexx.dev`

Plus infrastructure:

All services have Dockerfiles in the monorepo. For local development:

docker compose up -d

This starts PostgreSQL, Redis, and the development services.

The services are designed to run on any container platform. The default deployment uses Railway.

Key variables for each service:

Variable	Service	Description
`DATABASE_URL`	BFF	PostgreSQL connection string
`REDIS_URL`	BFF, Relay	Redis for caching
`REDIS_QUEUE_URL`	BFF	Redis for job queues
`JWT_SECRET`	BFF	JWT signing key
`BFF_EXTERNAL_URL`	BFF	Public URL of the BFF (e.g., `https://bff.flexx.dev`)
`BFF_INTERNAL_URL`	Relay	Internal URL to reach BFF (e.g., `http://bff:4000`)
`BFF_INTERNAL_TOKEN`	BFF, Relay	Shared secret for internal APIs
`RELAY_EXTERNAL_URL`	Relay	Public URL of the relay
`DASHBOARD_URL`	BFF	Public URL of the dashboard (for CORS, OAuth redirects)
`BETTER_AUTH_SECRET`	BFF	Better Auth encryption secret
`BETTER_AUTH_URL`	BFF	Same as `BFF_EXTERNAL_URL`

Edit ~/.flexx/config.json:

{
  "apiUrl": "https://your-bff-host.com/api",
  "apiKey": "your-key"
}

The relay URL is derived automatically from the API URL (replacing bff with relay), or set explicitly in ~/.flexx/remote.json:

{
  "relayUrl": "https://your-relay-host.com",
  "remoteId": "...",
  "secret": "...",
  "workspace": "/path/to/workspace"
}

The BFF runs Drizzle ORM migrations on startup via entrypoint.sh. For manual migrations:

cd packages/db
DATABASE_URL=your_connection_string npx drizzle-kit push