Plexus can be run via Docker, as a standalone binary, or from source using Bun.
- Bun 1.4.4+: Plexus is built with Bun. If you are running from source or building binaries, you will need Bun 1.4.4 or newer installed (
mise installinstalls the pinned 1.4.4; Docker and CI pinoven/bun:1.4.4).
The easiest way to run Plexus is using the pre-built Docker image.
Pull the image:
docker pull ghcr.io/mcowger/plexus:latestRun the container:
docker run -p 4000:4000 \
-v plexus-data:/app/data \
-e ADMIN_KEY="your-admin-key" \
-e DATABASE_URL=sqlite:///app/data/plexus.db \
-e LOG_LEVEL=info \
ghcr.io/mcowger/plexus:latest- Mount a volume to
/app/datato persist usage logs, configuration, and other data. ADMIN_KEYis required — set it to a secure password for accessing the admin dashboard and management API.DATABASE_URLis optional (defaults to SQLite at./data/plexus.dbwhen unset) — set it to asqlite://path (inside the mounted volume) or apostgres://connection string when connecting to PostgreSQL or custom locations.- Set
LOG_LEVELto control verbosity. - The Docker image includes
bunxanduvxso Plexus can run configured Local HTTP MCP servers inside the container.
If you want to build the image yourself:
Build the image:
docker build -t plexus .Run the container:
docker run -p 4000:4000 \
-v plexus-data:/app/data \
-e ADMIN_KEY="your-admin-key" \
-e DATABASE_URL=sqlite:///app/data/plexus.db \
-e LOG_LEVEL=info \
plexusPlexus can be compiled into a single, self-contained binary that includes the Bun runtime, all backend logic, the pre-built frontend dashboard, and the database migration files.
-
Clone the repository:
git clone https://github.com/mcowger/plexus.git cd plexus -
Install dependencies:
bun install
-
Compile:
- macOS (ARM64/Apple Silicon):
bun run compile:macos - Linux (x64):
bun run compile:linux-amd64 - Linux (ARM64):
bun run compile:linux-arm64 - Windows (x64):
bun run compile:windows
- macOS (ARM64/Apple Silicon):
The resulting executable will be named plexus-macos, plexus-linux-amd64,
plexus-linux-arm64, or plexus.exe in the project root.
The binary is fully self-contained: migration SQL files are embedded inside it at compile time, so no separate drizzle/ directory or DRIZZLE_MIGRATIONS_PATH environment variable is needed when running the standalone binary.
If plexus.exe opens and closes immediately, run it from a terminal so startup errors remain visible. ADMIN_KEY must be set before starting the server.
Windows PowerShell:
$env:ADMIN_KEY = "your-admin-password"
$env:DATABASE_URL = "sqlite://./data/plexus.db"
.\plexus.exeWindows Command Prompt:
set ADMIN_KEY=your-admin-password
set DATABASE_URL=sqlite://./data/plexus.db
plexus.exe-
Clone the repository:
git clone https://github.com/mcowger/plexus.git cd plexus -
Install dependencies:
bun install
-
Start Development Stack:
ADMIN_KEY="your-admin-key" DATABASE_URL=sqlite://./data/plexus.db bun run devIf mise is not activated in your shell, use
mise exec -- bun run dev. Runmise installonce to install the project-managed tools. FRP is optional; withoutfrpconPATH, or withoutFRPC_SERVER_ADDRandFRPC_AUTH_TOKEN, the dev server runs without a tunnel. The tunnel is stopped with the direct dev process, or when Paseo stops its managed service.To run the background lifecycle instead:
bun run dev:agent --detach bun run dev:stop
Prefix these commands with
mise exec --when mise is not activated. When Paseo manages the stack, make sure Paseo itself runs with the project mise environment if you want to use the mise-managedfrpcbinary.
When running Plexus, you can use the following environment variables to control its behavior:
ADMIN_KEY(Required): Password for the admin dashboard and management API.- Must be set before starting the server. Server will refuse to start without it.
DATABASE_URL(Optional): Database connection string (defaults to SQLite at./data/plexus.db).- SQLite:
sqlite:///app/data/plexus.dborsqlite://./data/plexus.db - PostgreSQL:
postgres://user:password@host:5432/dbname
- SQLite:
ENCRYPTION_KEY(Optional): Encryption key for sensitive data at rest (API keys, OAuth tokens, provider credentials).- Generate with:
openssl rand -hex 32 - If not set, data is stored in plaintext. A warning is logged at startup.
- See Configuration: Encryption at Rest for details.
- Generate with:
LOG_LEVEL: The verbosity of the server logs.- Supported values:
error,warn,info,debug,silly. - Default:
info. - Note:
sillylogs all request/response/transformations. - Runtime override: You can change log level live via the management API/UI (
/v0/management/logging/level). This override is ephemeral and resets on restart.
- Supported values:
PORT(Optional): HTTP server port. Default:4000(Note: When runningbun run devlocally, the port is automatically derived from the git worktree directory name).HOST(Optional): Address to bind to. Default:0.0.0.0DATA_DIR(Optional): Directory for SQLite database. Default:./dataFRPC_SERVER_ADDR(Development only): LAN-reachable address of the frps server.FRPC_AUTH_TOKEN(Development only): Token shared with frps.FRPC_SERVER_PORT(Development only): frps control port. Default:7000.FRPC_SUBDOMAIN_HOST(Development only): Optional suffix used only to print the full HTTPS URL. The frpssubDomainHostsetting controls routing.
ADMIN_KEY="your-secret" DATABASE_URL=sqlite://./data/plexus.db LOG_LEVEL=debug ./plexusFor configuration details, please refer to the Configuration Guide.