# Quickstart

> First successful run: set at least one LLM key, docker compose up, open https://localhost:8443, change admin@pentagi.com defaults, create a flow, and verify provider and UI health.

- Repository: vxcontrol/pentagi
- GitHub: https://github.com/vxcontrol/pentagi
- Human docs: https://grok-wiki.com/public/docs/vxcontrol-pentagi-eca0cf4de5f5
- Complete Markdown: https://grok-wiki.com/public/docs/vxcontrol-pentagi-eca0cf4de5f5/llms-full.txt

## Source Files

- `README.md`
- `.env.example`
- `docker-compose.yml`
- `frontend/src/pages/login.tsx`
- `frontend/src/pages/flows/new-flow.tsx`
- `backend/pkg/server/services/auth.go`
- `backend/pkg/server/services/flows.go`

---

---
title: "Quickstart"
description: "First successful run: set at least one LLM key, docker compose up, open https://localhost:8443, change admin@pentagi.com defaults, create a flow, and verify provider and UI health."
---

PentAGI boots as a Docker Compose stack (`pentagi`, `pgvector`, `scraper`, and optional exporters) that serves the web UI and REST/GraphQL APIs on HTTPS port **8443**. A first successful run needs: at least one LLM provider key (or local endpoint) in `.env`, a healthy core stack, sign-in as the seeded local admin, a password change when `password_change_required` is set, and a flow created with a ready provider.

<Warning>
Only assess systems you own or are explicitly authorized to test. Acceptable use is defined in the repository `EULA.md`.
</Warning>

## Prerequisites

| Requirement | Notes |
|---|---|
| Docker and Docker Compose | Or Podman (scraper needs non-privileged port config in rootless mode) |
| CPU / memory / disk | Minimum 2 vCPU, 4 GB RAM, ~20 GB free |
| Network | Pull images and call LLM/search endpoints (unless fully local inference) |
| BYOK credentials | At least one provider: OpenAI, Anthropic, Gemini, Bedrock, DeepSeek, GLM, Kimi, Qwen, Ollama, or custom `LLM_SERVER_*` |

Optional later: search engines, OAuth, Langfuse, OpenTelemetry, Graphiti. They are not required for first UI login and a minimal flow.

## Path overview

```text
.env (LLM key) ──► docker compose up -d
        │
        ▼
https://localhost:8443 ──► login admin@pentagi.com / admin
        │
        ▼
password change (password_change_required) ──► /flows/new
        │
        ▼
Automation or Assistant flow ──► monitor status / report
```

For guided `.env` generation and deploy, use the interactive installer instead of the manual path below.

## Step-by-step: first run

<Steps>
<Step title="Prepare working directory and env file">

From a clean directory (or a clone of the repo):

```bash
mkdir -p pentagi && cd pentagi
curl -o .env https://raw.githubusercontent.com/vxcontrol/pentagi/master/.env.example
curl -O https://raw.githubusercontent.com/vxcontrol/pentagi/master/docker-compose.yml
curl -o example.custom.provider.yml \
  https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/custom-openai.provider.yml
curl -o example.ollama.provider.yml \
  https://raw.githubusercontent.com/vxcontrol/pentagi/master/examples/configs/ollama-llama318b.provider.yml
```

Compose mounts `example.custom.provider.yml` and `example.ollama.provider.yml` by default. Touching or downloading them avoids missing bind-mount paths.

</Step>
<Step title="Set at least one LLM provider">

Edit `.env` and set **one or more** of the following (empty keys leave that provider disabled in `ProvidersReadinessStatus`):

| Provider | Primary env keys |
|---|---|
| OpenAI | `OPEN_AI_KEY`, optional `OPEN_AI_SERVER_URL` |
| Anthropic | `ANTHROPIC_API_KEY`, optional `ANTHROPIC_SERVER_URL` |
| Gemini | `GEMINI_API_KEY`, optional `GEMINI_SERVER_URL` |
| AWS Bedrock | `BEDROCK_REGION` + one of default auth / bearer / access keys |
| DeepSeek / GLM / Kimi / Qwen | `DEEPSEEK_API_KEY`, `GLM_API_KEY`, `KIMI_API_KEY`, `QWEN_API_KEY` |
| Ollama (local or cloud) | `OLLAMA_SERVER_URL`, optional `OLLAMA_SERVER_API_KEY`, `OLLAMA_SERVER_MODEL` |
| Custom OpenAI-compatible | `LLM_SERVER_URL`, `LLM_SERVER_KEY`, optional `LLM_SERVER_MODEL`, `LLM_SERVER_CONFIG_PATH` |

Minimal cloud example:

```bash
OPEN_AI_KEY=sk-...
# or
ANTHROPIC_API_KEY=sk-ant-...
# or
GEMINI_API_KEY=...
```

Minimal local Ollama example:

```bash
OLLAMA_SERVER_URL=http://host.docker.internal:11434
OLLAMA_SERVER_MODEL=llama3.1:8b
```

<Tip>
Provider API keys and base URLs are server-side (`.env` / compose). After the stack is up, **Settings → Providers** manages user-defined profiles (per-agent models, reasoning, pricing) and can run `testProvider` / `testAgent` checks. Env keys still gate whether a built-in type is marked enabled.
</Tip>

</Step>
<Step title="Harden defaults before production use">

For anything beyond a local lab, change at least:

| Variable | Default / note |
|---|---|
| `COOKIE_SIGNING_SALT` | Example value `salt` — replace with a random secret |
| `PUBLIC_URL` / `CORS_ORIGINS` | Default `https://localhost:8443` |
| `PENTAGI_POSTGRES_PASSWORD` | Default `postgres` |
| Scraper `LOCAL_SCRAPER_*` | Defaults `someuser` / `somepass` |

Optional for first run: `DUCKDUCKGO_ENABLED=true`, `SPLOITUS_ENABLED=true`, or other search keys. They improve agent research tools but are not required to start the UI.

</Step>
<Step title="Start the core stack">

```bash
docker compose up -d
```

Core services from `docker-compose.yml`:

| Service | Role |
|---|---|
| `pentagi` | API + UI on host `127.0.0.1:8443` → container `8443` |
| `pgvector` | PostgreSQL + pgvector (`pentagidb`); healthchecked before `pentagi` starts |
| `scraper` | Isolated browser fetch (default host `127.0.0.1:9443` → container `443`) |
| `pgexporter` | Postgres metrics exporter (optional for first run) |

Default bind is **localhost only** (`PENTAGI_LISTEN_IP=127.0.0.1`). Docker socket is mounted so agent containers can be spawned.

</Step>
<Step title="Verify containers and open the UI">

```bash
docker compose ps
docker compose logs -f pentagi
```

Expected: `pgvector` healthy, `pentagi` running, port mapping similar to `127.0.0.1:8443->8443/tcp`.

Open **https://localhost:8443**. Accept the self-signed certificate warning if you did not mount custom `SERVER_SSL_CRT` / `SERVER_SSL_KEY`.

</Step>
<Step title="Sign in as the default admin">

There is no public self-service sign-up on the login page. Migration seed creates:

| Field | Value |
|---|---|
| Email | `admin@pentagi.com` |
| Password | `admin` |
| Status | `active` |
| Role | Admin (`role_id` 1) |
| `password_change_required` | `true` |

Login uses `POST /api/v1/auth/login` with session cookies (`HttpOnly`, `Secure` when TLS is present). Successful login loads privileges from the admin role (including `flows.create`, settings, providers, and so on).

Default post-login destination when no return URL is set: **`/flows/new`**.

</Step>
<Step title="Change the default password">

On first login, local users with `password_change_required` see **Update Password** (UI allows skip, but changing is required before real work).

- Endpoint: `PUT /api/v1/user/password`
- Body fields: `current_password`, `password`, `confirm_password`
- Backend validator (`stpass`): password must be **longer than 15 characters**, **or** at least **8** characters with number, lowercase, uppercase, and one of `!@#$&*`
- Success clears `password_change_required`

If the admin password is lost later, use the installer maintenance path to reset `admin@pentagi.com`.

</Step>
<Step title="Confirm providers are ready">

In the UI, open **Settings → Providers** (or the provider picker on the new-flow form).

GraphQL exposes readiness as booleans per type under `ProvidersConfig.enabled` (`openai`, `anthropic`, `gemini`, `bedrock`, `ollama`, `custom`, `deepseek`, `glm`, `kimi`, `qwen`). At least one type you configured should be available for selection.

Optional health check before a real engagement:

1. Create or edit a user-defined provider profile under **Settings → Providers**.
2. Run the UI test actions backed by GraphQL `testProvider` / `testAgent`.
3. Prefer a cheap agent/model for smoke tests.

</Step>
<Step title="Create the first flow">

Route: **`/flows/new`** (sidebar **Flows → New Flow**).

1. Choose mode:
   - **Automation** — autonomous end-to-end run (`createFlow`)
   - **Assistant** — interactive session (`createFlowWithAssistant`); optional **Use Agents** (default from `ASSISTANT_USE_AGENTS` / system settings)
2. Select a provider name (built-in or user-defined).
3. Optionally attach resources / use a flow template.
4. Enter a natural-language objective (target, scope, expected outcome).

Example first prompt:

```text
Assess https://target.example for common web application vulnerabilities.
Focus on authentication, file handling, and injection issues.
Stay within the provided target only and summarize confirmed findings
with reproduction steps.
```

Longer checklists live under `examples/prompts/` (for example `base_web_pentest.md`).

Submit creates a flow via GraphQL/REST (`createFlow` / `POST /api/v1/flows/`) with required `input` and `provider`. The UI navigates to `/flows/{id}?tab=automation|assistant`.

Flow lifecycle statuses: `created`, `running`, `waiting`, `finished`, `failed`. Patch actions include `stop`, `finish`, `input`, and `rename`.

</Step>
<Step title="Confirm the run is healthy">

On the flow page:

- Messages and agent activity stream (GraphQL subscriptions over WebSocket when the UI is connected)
- Tasks/subtasks appear as the planner executes
- Terminal/tool logs show Docker-sandbox command activity when tools run
- **Report** menu: web view, clipboard copy, Markdown download, PDF download

Stack-level checks:

```bash
docker compose ps
docker compose logs --tail=100 pentagi
curl -k -s -o /dev/null -w "%{http_code}\n" https://localhost:8443/
```

Swagger (after login or with a token): `https://localhost:8443/api/v1/swagger/index.html`.

</Step>
</Steps>

## Core compose surface

Default host ports (override with `*_LISTEN_IP` / `*_LISTEN_PORT`):

| Port (host) | Service |
|---|---|
| `8443` | PentAGI UI + API (`SERVER_USE_SSL=true` by default) |
| `5432` | pgvector (localhost-bound by default) |
| `9443` | scraper HTTPS |
| `9187` | postgres-exporter |

Data volumes: `pentagi-data`, `pentagi-ssl`, `pentagi-ollama`, `pentagi-postgres-data`, `scraper-ssl`. Networks: `pentagi-network` (plus empty `observability-network` / `langfuse-network` for optional overlays).

Start overlays only after the base compose file has created shared networks:

```bash
docker compose -f docker-compose.yml -f docker-compose-observability.yml up -d
docker compose -f docker-compose.yml -f docker-compose-langfuse.yml up -d
docker compose -f docker-compose.yml -f docker-compose-graphiti.yml up -d
```

## External access (optional)

Default bind is loopback. For LAN/server access, set in `.env` then recreate:

```bash
PENTAGI_LISTEN_IP=0.0.0.0
PENTAGI_LISTEN_PORT=8443
PUBLIC_URL=https://192.168.1.100:8443
CORS_ORIGINS=https://localhost:8443,https://192.168.1.100:8443
```

```bash
docker compose down
docker compose up -d --force-recreate
```

Use a real IP/hostname in `PUBLIC_URL` and `CORS_ORIGINS` (not `0.0.0.0`).

## Troubleshooting

| Symptom | Likely cause | Action |
|---|---|---|
| No providers in the new-flow picker | No LLM keys / endpoints in `.env` | Set at least one provider env, recreate `pentagi` |
| Login fails for admin | Wrong credentials or inactive user | Use `admin@pentagi.com` / `admin`; check DB seed; installer reset if needed |
| Browser certificate warning | Self-signed TLS | Expected locally; mount custom certs for production |
| `pentagi` waits on DB | `pgvector` not healthy | `docker compose logs pgvector`; check Postgres password/volume |
| Flow create 403 / not permitted | Missing `flows.create` privilege | Use Admin role account |
| Flow create fails with provider not found | Name/type mismatch or disabled provider | Align picker name with enabled provider; recheck env |
| Agent tools cannot reach Docker | Socket not mounted / permission | Confirm `/var/run/docker.sock` mount; compose runs `pentagi` as root for socket access |
| Overlay compose network errors | Overlay started without base networks | Start `docker-compose.yml` first |
| Cannot reach from another host | Bound to `127.0.0.1` | Set `PENTAGI_LISTEN_IP` / `PUBLIC_URL` / `CORS_ORIGINS`, recreate |

## Minimal API smoke test (after UI token)

Create a Bearer token under **Settings → API Tokens** (shown once). Example flow create:

:::endpoint POST /api/v1/flows/
Create a flow for the authenticated user (session cookie or Bearer token). Requires `flows.create`.

**Body**

- `input` (string, required) — first task objective  
- `provider` (string, required) — provider name known to the controller  
- `functions` (object, optional) — tool allowlist overrides  
- `resource_ids` (uint64[], optional) — attach library resources  

**Responses**

- `201` — flow created  
- `400` — invalid payload  
- `403` — not permitted  
- `500` — provider missing or internal create error  
:::

## What not to expect on day one

- Public registration from the login page (admin-created local users or OAuth only)
- MCP management UI (not a live settings surface today)
- Search/Langfuse/Graphiti without extra env and compose overlays
- JSON report export from the Report menu (web / copy / Markdown / PDF only)

## Next

<CardGroup>
  <Card title="Installation" href="/installation">
    Full prerequisites, volumes, SSL, and compose overlays for observability, Langfuse, and Graphiti.
  </Card>
  <Card title="Interactive installer" href="/installer">
    TUI wizard for system checks, .env generation, SSL hardening, deploy, and admin password reset.
  </Card>
  <Card title="Configure LLM providers" href="/configure-llm-providers">
    Wire cloud and built-in providers, UI profiles, and pre-flow tests.
  </Card>
  <Card title="Local and custom providers" href="/local-and-custom-providers">
    Ollama, LLM_SERVER_*, OpenRouter/DeepInfra-style endpoints, and config YAML mounts.
  </Card>
  <Card title="Flows, tasks, and subtasks" href="/flows-tasks-subtasks">
    Lifecycle states and control boundaries after the first flow is running.
  </Card>
  <Card title="Sample pentest prompts" href="/sample-pentest-prompts">
    Ready-made automation inputs from examples/prompts.
  </Card>
  <Card title="Authentication and API tokens" href="/auth-and-api-tokens">
    Session login, OAuth, password change, and Bearer tokens for REST/GraphQL.
  </Card>
  <Card title="Environment variables" href="/environment-variables">
    Authoritative Config and .env.example reference.
  </Card>
</CardGroup>