Skip to Content
Polyant is open source under AGPL-3.0 — star us on GitHub.
Getting StartedInstallation

Installation and Setup

This chapter walks through a full installation — from a fresh checkout to the first successful login. Total time on a developer machine: under fifteen minutes.

System requirements

  • Node.js 22 or newer (engine and admin panel both target Node 22; CI matrix tests on 22; the Dockerfiles base on node:22-alpine).
  • Docker and Docker Compose (for PostgreSQL with pgvector).
  • A modern browser for the admin panel.
  • Optional: pandoc and xelatex (only if you plan to build the printable manual locally).

You do not need an account with any LLM provider to install Polyant. Provider API keys are configured later, per instance, from the admin panel.

Step 1: Clone and install

git clone https://github.com/polyant-ai/polyant.git
cd polyant
npm install

Note. Polyant is an npm workspaces monorepo with two workspaces (packages/engine, packages/web). Always run npm install from the repository root — never inside an individual package directory. The documentation site you are reading lives in a separate repository, polyant-ai/docs .

Step 2: Start PostgreSQL

docker compose up -d

This launches a PostgreSQL 16 container with the pgvector extension enabled, on port 5432, with a persistent named volume so your data survives container restarts.

Verify the container is healthy:

docker compose ps

You should see polyant-postgres with status healthy.

Step 3: Configure environment variables

Copy the example env file and edit it:

cp .env.example .env

The minimum required variables for a successful first boot are:

VariablePurpose
DATABASE_URLFull PostgreSQL connection string used by the engine. Required. Either set DATABASE_URL directly, or set the POSTGRES_* quartet (POSTGRES_USER, POSTGRES_PASSWORD, POSTGRES_DB, host/port) used by docker-compose and let the engine compose the URL from them.
POSTGRES_PASSWORDThe Postgres password used by docker-compose and the engine.
ENCRYPTION_KEY64-character hex string used to encrypt instance secrets at rest.
AUTH_SECRET32+ character random string used to sign and encrypt session JWTs.
AUTH_INTERNAL_SECRETShared secret used by the credentials login bridge between web and engine. Required for email/password sign-in.

Generate a 64-character hex encryption key:

openssl rand -hex 32

Generate a 32+ character auth secret (same command works for AUTH_SECRET and AUTH_INTERNAL_SECRET):

openssl rand -hex 32

The same .env file is shared by the engine and docker-compose.yml. The admin panel reads its own packages/web/.env.local (Next.js does not auto-load monorepo-root .env); at minimum it needs AUTH_SECRET, AUTH_INTERNAL_SECRET, and DATABASE_URL duplicated there. See the Environment Variables Reference for the full list.

Step 4: Run migrations

npm run db:migrate

This applies every pending migration in order. On a fresh database it creates all tables (instances, conversations, messages, memories, audit logs, room, users, and so on) and installs the pgvector extension if needed.

Step 5: Boot the engine and the admin panel

In one terminal:

npm run dev:engine

The engine starts on port 4000 by default. You should see log lines confirming database connectivity, the tool registry size, and the channel manager waking up.

In a second terminal:

npm run dev:web

The admin panel starts on port 3000. Open http://localhost:3000 in your browser.

Step 6: First login

On first boot the engine creates an initial Superadmin user if the users table is empty:

  • If you set INITIAL_ADMIN_EMAIL and INITIAL_ADMIN_PASSWORD in .env, those credentials are used.
  • Otherwise the engine creates administrator@local with a random password and prints the password once to the engine logs. Save it before you scroll past.

Log in at http://localhost:3000/login:

  • Email + Password: use the Superadmin you just got. This path requires AUTH_INTERNAL_SECRET to be configured identically on both web and engine.
  • Google OAuth: optional. The sign-in button is hidden unless both GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set. When enabled, the allow-list is empty by default — see “Self-hosters: changing the Google OAuth domain” in Authentication to restrict it.

You are now in. Go to Instances in the sidebar to create your first assistant — see the Quickstart for a guided walkthrough.

Optional: build the printable manual

A printable PDF version of this manual is produced by a separate repository, polyant-ai/docs . Clone it alongside the engine, install pandoc + xelatex, and run:

git clone https://github.com/polyant-ai/docs.git
cd docs
npm install
npm run build:pdf      # writes user-manual.pdf at the repo root

See that repo’s README.md for the full prerequisites (Linux / Windows / macOS) and the authoring rules for shared content.

Last updated on
Quickstart