Quickstart: Your First Assistant

This tutorial walks you through building your first AI assistant with Polyant in about 10 minutes. By the end you’ll have an instance running locally, reachable via the OpenAI-compatible API, and visible in the admin panel.

For a more detailed walkthrough of the full installation (system requirements, secret generation, first-login flow), see Installation and Setup. This page is intentionally compact and focused on getting a working assistant end-to-end.

Quickstart with demo-agent

If you just want to try Polyant out without configuring anything, run the quickstart. The first migration after a fresh install seeds a vendor-neutral demo-agent instance you can chat with immediately.


git clone https://github.com/polyant-ai/polyant.git
cd polyant
cp .env.example .env
docker compose up -d              # postgres with pgvector
npm install
npm run db:migrate                # applies all migrations + seeds demo-agent
npm run dev                       # engine on :4000
# (in a second terminal)
npm run dev:web                   # admin panel on :3000

Open http://localhost:3000, sign in (use the Superadmin credentials printed once to the engine logs on first boot — see §5b below), select Demo Agent from the instance dropdown, and send your first message in the Playground.

The demo-agent has memory enabled, auth disabled, no channels and no pre-configured skills. Treat it as a sandbox — replace or delete it before moving to production. The seed migration is idempotent, so re-running db:migrate will not duplicate or overwrite the instance.

For a guided walkthrough of building your own instance from scratch, follow the rest of this document.

Prerequisites

Node.js 22+
Docker & Docker Compose
An OpenAI or Anthropic API key (for the assistant’s LLM calls)

1. Clone and install


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

2. Start the database


docker compose up -d

PostgreSQL 16 with pgvector runs on port 5432.

3. Configure environment

Copy the template and fill in the required values:


cp .env.example .env

Generate the required secrets:


# Engine encryption key (32-byte hex, protects instance secrets at rest)
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
 
# Auth secret (signs session tokens shared between web and engine)
openssl rand -hex 32
 
# Internal secret (bridges credentials login between web and engine)
openssl rand -hex 32

Paste them into .env as ENCRYPTION_KEY, AUTH_SECRET, and AUTH_INTERNAL_SECRET.

The simplest first-login path is the credentials provider (email + password):

Set INITIAL_ADMIN_EMAIL and INITIAL_ADMIN_PASSWORD in .env if you want to pick them yourself.
Otherwise the engine creates administrator@local on first boot with a random password and prints it once to the engine logs — copy it before you scroll past.

Google OAuth is optional — the Google sign-in button only appears when both GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set; otherwise email + password remains the only login method. To enable it, set GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET from the Google Cloud Console → APIs & Services → Credentials. Leave AUTH_ALLOWED_DOMAINS empty to allow any Google account to sign in.

Mirror the auth secrets into `packages/web/.env.local`

Next.js does NOT auto-load the monorepo-root .env. The admin panel reads its own .env.local, so duplicate the auth-related vars there. Same values you already pasted into .env:


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

AUTH_TRUST_HOST=true is required when running on localhost:3000 (Auth.js validates the request host; without this it rejects sessions with UntrustedHost errors).

4. Run migrations


npm run db:migrate

This creates all tables: instances, conversations, messages, memories, secrets, channels, skills, etc.

5. Start the engine and admin panel

Open two terminals:


# Terminal 1 — engine on :4000
npm run dev
 
# Terminal 2 — admin panel on :3000
npm run dev:web

After signing in for the first time, you’ll be redirected to /password-change — the seed admin is created with the must_change_password flag on (whether you set INITIAL_ADMIN_PASSWORD yourself or let the engine print a random one).

Type a new password twice and click Update password. You then land on the dashboard and Step 6 below picks up.

If your browser’s password manager (1Password, Bitwarden, etc.) tries to autofill the OLD saved password into the NEW password field, click outside the field once to dismiss the popover and re-type — Polyant explicitly tells the extensions to ignore those inputs but some still try.

6. Create your first instance

Open http://localhost:3000 and sign in with the Superadmin credentials (either the ones you set via INITIAL_ADMIN_*, or the random password printed to the engine logs on first boot). If you configured Google OAuth, that button is also available.

Click New Instance and fill in:

Field	Value
Slug	`hello-world`
Name	Hello World
Description	My first Polyant agent

Go to the Settings tab and add your LLM provider key (e.g. openai_api_key). Set the provider and model.

7. Customize the prompt

Go to the Prompts tab. You’ll see 8 sections (identity, soul, tooling, safety, skills, memory, user-identity, datetime) with sensible defaults.

Edit 01-identity — tell the assistant who it is. For example:


# Identity
 
You are Atlas, a helpful assistant that answers coding questions concisely.
Prefer short code examples over long explanations.

Save.

8. Test in the Playground

Go to the Playground tab, type a question, and watch the agent respond in real time with tool calls and streaming output.

9. Call the OpenAI-compatible API

Your instance is now reachable via HTTP:


curl -s http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hello-world",
    "messages": [{"role": "user", "content": "Hi, what can you do?"}]
  }'

The model field is your instance slug. Every instance in the admin panel is exposed as a selectable model.

What’s next?

Add memory — in the Settings tab, turn on the Memory toggle (memoryEnabled in the API payload), and the agent will automatically extract and recall facts from conversations.
Connect a channel — see Connect a Channel to wire up Telegram, Slack, or WhatsApp.
Add a tool — see the “Adding a New Tool” section of CONTRIBUTING.md .
Add a skill — see examples/skills/ for a minimal skill definition.
Deploy — see Deployment for Docker, Render, Fly.io, and Kubernetes recipes.
Glossary — unfamiliar with the terms? See Glossary.