Quickstart

Deploy a self-hosted Mogplex with Docker or Vercel, sign in, and add the services that unlock agent work.

This guide gets a signed-in deployment running first. Then it adds the services that let agents work on repositories.

Prerequisites

Node.js 22.22.x (see .nvmrc) and pnpm 10 through Corepack (corepack enable).
Docker path: Docker with Compose, on amd64 or arm64. Compose pulls the published image and runs Postgres for you.
Vercel path: a Postgres 17 database with the vector and pg_trgm extensions available. Neon has both.
A public HTTPS domain for the deployment. OAuth callbacks and webhooks must reach it.

1. Get the code

git clone https://github.com/Mogplex/mogplex.git
cd mogplex
pnpm install
cp .env.example .env.local    # use .env for Docker

Fork the repository first if you plan to change code or deploy from Git. The Docker path runs a prebuilt image; you still need the checkout to deploy the Trigger.dev tasks and to run the setup doctor.

2. Configure the minimum environment

Generate each secret with openssl rand -base64 32, except CONNECTIONS_ENCRYPTION_KEY, which must be 32 bytes of hex (openssl rand -hex 32).

# Backend switches. Both must be "neon".
MOGPLEX_DATA_BACKEND=neon
NEXT_PUBLIC_MOGPLEX_DATA_BACKEND=neon

# Public URL. APP_URL is read at runtime, so one build serves any domain.
APP_URL=https://mogplex.example.com

# Database. DATABASE_URL is the owner connection that migrations use.
# Docker Compose fills these in for its own Postgres when you leave them unset.
DATABASE_URL=postgres://...
DATABASE_URL_UNPOOLED=postgres://...

# Auth
BETTER_AUTH_SECRET=...
AUTH_GITHUB_CLIENT_ID=...        # or AUTH_GOOGLE_* / AUTH_MICROSOFT_*
AUTH_GITHUB_CLIENT_SECRET=...

# Secrets the app requires
CRON_SECRET=...
INTERNAL_API_SECRET=...
CONNECTIONS_ENCRYPTION_KEY=...   # 64 hex characters
EMAIL_UNSUBSCRIBE_SECRET=...     # required in production

# Give every signed-in user platform AI and sandbox access (no Stripe needed)
MOGPLEX_SELF_HOSTED=1

Database and auth explains the database URLs, the least-privilege runtime role, and each sign-in provider.

3. Deploy

docker compose up -d

This pulls ghcr.io/mogplex/mogplex:latest. To pin a release, set MOGPLEX_VERSION in .env, for example MOGPLEX_VERSION=v0.2.0. Set MOGPLEX_PORT to serve on a host port other than 3000.

Compose starts four services from that one image:

Service	What it does
`postgres`	Postgres 17 with pgvector, started by `COMPOSE_PROFILES=postgres` from `.env.example`. Set `POSTGRES_PASSWORD` to change the default password. To use an external database instead, set `DATABASE_URL` and `DATABASE_URL_UNPOOLED` and remove `COMPOSE_PROFILES`; no local Postgres starts.
`migrate`	Applies `neon/baseline.sql` and `neon/migrations/`, then exits. The app starts only after it succeeds.
`app`	The web app on port 3000. Its health check calls `GET /api/health`.
`cron`	Calls each cron route on its schedule with `Authorization: Bearer $CRON_SECRET`.

Put a TLS-terminating proxy in front of port 3000.

Some NEXT_PUBLIC_* values are compiled in at build time, so the published image leaves them unset: the Sentry DSN, the consent backend, the Vercel sign-in client ID, and the legacy Supabase keys. To set them, or to run unreleased code, build the image from your checkout instead:

docker compose -f docker-compose.yml -f docker-compose.build.yml up -d --build

Without Compose, the same image runs each role:

docker run --rm --env-file .env ghcr.io/mogplex/mogplex node scripts/migrate.cjs
docker run -d --env-file .env -p 3000:3000 ghcr.io/mogplex/mogplex
docker run -d -e CRON_SECRET -e CRON_TARGET_URL=https://mogplex.example.com \
  ghcr.io/mogplex/mogplex node scripts/self-host-cron.mjs

Open the deployment and sign in. If sign-in works, the app shell is done.

4. Add services for agent work

Add these in order. Each one is independent.

GitHub App: repository access, webhooks, PR reviews, and GitHub triggers. Create it in one step at /admin/setup/github.
Background jobs: a Trigger.dev project, on Trigger.dev Cloud or your own instance.
Sandboxes and models: Vercel Sandbox and model access, including your own OpenAI-compatible endpoint.
Slack app (optional), from the manifest in the repo.

5. Verify

pnpm setup:doctor          # add --live to test credentials against the services

# Docker: run it inside the image, no checkout needed
docker compose exec app node scripts/doctor.cjs

The doctor reports each service as pass, warn, or fail, and links the page that fixes each problem. It never prints secret values.

Then sign in, connect GitHub, import a repository, and start a run. Confirm in Observability that a sandbox starts and the job completes.

PrerequisitesCopy Anchor Link

1. Get the codeCopy Anchor Link

2. Configure the minimum environmentCopy Anchor Link

3. DeployCopy Anchor Link

4. Add services for agent workCopy Anchor Link