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 24 (engine and admin panel both target Node 24, which .nvmrc names; CI tests on 24; the Dockerfiles base on node:24-alpine). Node 22 is no longer tested.
• Docker and Docker Compose (for PostgreSQL with pgvector).
• A modern browser for the admin panel.

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 (with managed services, as provider connections).

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. The workspace glob is packages/*, which contains packages/engine and packages/web. Always run npm install from the repository root, never inside an individual package directory.

Step 2: Configure environment variables

Copy the example env file and edit it before starting PostgreSQL:

cp .env.example .env

Choose the PostgreSQL password before you start the database. The template sets both POSTGRES_PASSWORD and DATABASE_URL, and DATABASE_URL takes precedence when it is present. Replace changeme in POSTGRES_PASSWORD, then put the same password in the DATABASE_URL password component. Use that same connection string in packages/web/.env.local below. If the password contains special characters, percent-encode the password component in both connection strings; do not encode the entire URL.

The minimum required variables for a successful first boot are:

Generate the three required secrets and paste each value into .env:

openssl rand -hex 32   # ENCRYPTION_KEY
openssl rand -hex 32   # AUTH_SECRET
openssl rand -hex 32   # AUTH_INTERNAL_SECRET

Set the initial admin credentials in .env:

INITIAL_ADMIN_EMAIL=[email protected]
INITIAL_ADMIN_PASSWORD=choose-a-strong-password

The admin panel reads packages/web/.env.local. Copy the web values there, using the same auth secrets and the same percent-encoded database password as .env:

cat > packages/web/.env.local <<'EOF'
AUTH_SECRET=<same value as .env>
AUTH_INTERNAL_SECRET=<same value as .env>
AUTH_TRUST_HOST=true
DATABASE_URL=postgresql://polyant:<your POSTGRES_PASSWORD>@localhost:5432/polyant
NEXT_PUBLIC_API_URL=http://localhost:4000
INTERNAL_ENGINE_URL=http://localhost:4000
EOF

Replace every angle-bracket placeholder in this block before starting either service.

See the Environment Variables Reference for the full list.

Step 3: 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.

Note. Docker Compose reads POSTGRES_PASSWORD from .env and refuses to start when it is missing.

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.

A fresh database starts with no agent. Since 1.2.0 the migrations no longer leave a demo-agent behind: you create your first agent from the panel, and the guided setup offered at the first sign-in walks you through it.

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 platform admin if the users table is empty:

• Set INITIAL_ADMIN_EMAIL and INITIAL_ADMIN_PASSWORD in .env before the first boot. Those credentials create the initial platform admin when the users table is empty.

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

• Email + Password: use the platform admin credentials from .env. This path requires AUTH_INTERNAL_SECRET to be configured identically on both web and engine.
• Google OAuth: Managed services, optional. The open-source build signs in with email and password only. With managed services the sign-in button is hidden unless both GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set. Configuring the provider does not by itself admit any Google account - see Who may sign in with Google.

After your first sign-in with the initial admin credentials, the panel redirects you to /password-change. Enter a new password twice and click Update password before continuing.

Go to Agents in the sidebar to create your first assistant - see the Quickstart for a guided walkthrough.