Retrieved article excerpt
Open article · Retrieved 2026-09-17T13:22:31.430991+00:00
[apowerb](https://avatars.githubusercontent.com/u/310538280?v=4&s=160)
# apowerb
**The open-source agentic framework to build, orchestrate, and operate production AI agents.**
[Documentation](https://docs.apowerb.com/)
[PyPI version](https://pypi.org/project/apowerb/)
[Python](https://www.python.org/)
[License](https://github.com/apowerb/apowerb/blob/main/LICENSE)
[Discord](https://discord.com/channels/1470717940075597896)
[Documentation](https://docs.apowerb.com/) •
[Quickstart](https://docs.apowerb.com/quickstart) •
[API Reference](https://docs.apowerb.com/api-reference/introduction) •
[Deployment](https://docs.apowerb.com/deployment/dockercompose) •
[thaink2](https://thaink2.com)
---
This repository is the **open-source core**. Some capabilities named in the product —
billing, the consumption analysis screen, prospection, identity-provider sign-in,
multi-factor authentication, agent evaluation, the supervision screen, organisation
management — ship as separate commercial bricks and are **absent here**. Where the
core holds a hook for one, it is documented as such. A `404` on those routes means
"not in this edition", not "object not found".
The **administration panel is part of this edition**: users, groups, permissions, MFA
enforcement. Only the management of *organisations* is sold separately — deciding which
tenant a person belongs to governs other people's reach, rather than serving whoever runs
the install.
Full documentation: [docs.apowerb.com](https://docs.apowerb.com).
---
## Quick start
Three commands, a database included, and **nothing to fill in**:
```
git clone https://github.com/apowerb/apowerb-hosting.git && cd apowerb-hosting
cp .env.example .env && ./scripts/generate-secrets.sh
docker compose -f docker-compose/docker-compose.yml --env-file .env up -d
```
The interface is on <http://localhost:3000>, the API on
port `8000`. `generate-secrets.sh` writes the random values the stack needs, and
Postgres runs inside the stack — there is no external database to provide.
Agents need a model to answer, and that is the one thing this cannot invent for
you. Add your own key in the interface, or declare a shared one in `.env`
(`DEFAULT_LLM_MODEL` and `DEFAULT_LLM_API_KEY`). Until then everything else
works and the model simply does not appear in the list.
[`apowerb-hosting`](https://github.com/apowerb/apowerb-hosting) holds this
stack, plus Kubernetes manifests, a Helm chart and a Traefik overlay.
[Installation from source](https://github.com/apowerb/apowerb#installation-from-source) below is the other path:
it wants your own PostgreSQL.
## Table of Contents
- [Quick start](https://github.com/apowerb/apowerb#quick-start)
- [Features](https://github.com/apowerb/apowerb#features)
- [Prerequisites](https://github.com/apowerb/apowerb#prerequisites)
- [Installation from source](https://github.com/apowerb/apowerb#installation-from-source)
- [Configuration](https://github.com/apowerb/apowerb#configuration)
- [Running](https://github.com/apowerb/apowerb#running)
- [CLI](https://github.com/apowerb/apowerb#cli)
- [Architecture](https://github.com/apowerb/apowerb#architecture)
- [API Reference](https://github.com/apowerb/apowerb#api-reference)
- [Available Tools](https://github.com/apowerb/apowerb#available-tools)
- [Integrations](https://github.com/apowerb/apowerb#integrations)
- [Webhooks](https://github.com/apowerb/apowerb#webhooks)
- [RAG (Retrieval-Augmented Generation)](https://github.com/apowerb/apowerb#rag-retrieval-augmented-generation)
- [Text-to-SQL](https://github.com/apowerb/apowerb#text-to-sql)
- [SSE Streaming](https://github.com/apowerb/apowerb#sse-streaming)
- [Credits and billing](https://github.com/apowerb/apowerb#credits-and-billing)
- [Scheduled runs](https://github.com/apowerb/apowerb#scheduled-runs)
- [Agent Hub](https://github.com/apowerb/apowerb#agent-hub)
- [Development](https://github.com/apowerb/apowerb#development)
- [Troubleshooting](https://github.com/apowerb/apowerb#troubleshooting)
---
## Features
- **REST API** based on FastAPI with automatic OpenAPI documentation
- **Google ADK** (Agent Development Kit) for agent management and execution
- **LiteLLM** for multi-model compatibility (Anthropic, OpenAI, Mistral, Google, OVHcloud, etc.)
- **Multi-pattern orchestration**: base, parallel, sequential, loop
- **Sub-agents**: hierarchical agent composition
- **Modular tool system** with 31 tool modules (Google Workspace, Microsoft 365, databases, RAG, etc.)
- **RAG as a Service**: index files, URLs, databases, and S3 into knowledge bases
- **Text-to-SQL**: natural language to SQL query conversion
- **Webhooks**: Gmail (Pub/Sub) and Outlook (Graph API) push notifications to trigger agents
- **OAuth integrations**: GitHub, Google, Microsoft, LinkedIn
- **SSE streaming**: real-time agent responses, RAG progress, and notifications
- **Artifact generation**: agents can create and execute code files
- **Agent Hub**: publish and clone agents across organizations
- **Scheduled runs**: cron-based agent execution, driven by an external orchestrator
- **Bug reports**: any user files a defect from the app; the server attaches the server
log lines of the failing request (correlated by `X-Request-ID`), where the user was,
and an optional consented screenshot. Reviewed in a triage screen before any issue
is created — and the GitHub sink refuses a public repository
- **Supervision**: an auditable session list, scoped to what the caller may read
- **Revocable sessions**: a per-account cut-off that refuses tokens minted before it
- **Persistent sessions** with conversation context
- **PostgreSQL database** with auto-migrations
- **Encryption** for API keys, tokens, and sensitive data
- **Full CLI** for agent and server management
---
## Prerequisites
The [quick start](https://github.com/apowerb/apowerb#quick-start) above needs **Docker and Docker Compose**, and
nothing else. What follows is for running the core from its sources:
- Python 3.13+
- PostgreSQL
- UV (package manager)
---
## Installation from source
1. **Install UV and create virtual environment**:
```
pip install uv
uv venv
```
2. **Activate the virtual environment**:
```
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate
```
3. **Install dependencies**:
```
uv sync
uv pip install .
```
4. **Configure environment**:
```
cp .env.example .env
```
---
## Configuration
### Required Variables
**On the [quick start](https://github.com/apowerb/apowerb#quick-start) path, none of these are yours to fill in**
— the Compose stack wires the database and generates the key. This section is
for an installation that brings its own PostgreSQL.
Five settings, and the server refuses to boot without them
(`RUNTIME_REQUIRED_FIELDS` in `configs/settings.py`):
| Variable | Description |
| --- | --- |
| `DB_HOST` | PostgreSQL database host |
| `DB_NAME` | Database name |
| `DB_USER` | Database username |
| `DB_PASSWORD` | Database password |
| `ENCRYPT_KEY` | Encryption key for secrets and JWT signing — a url-safe base64 32-byte key, `Fernet.generate_key()` |
Two more are read from the same block and are **not** required, each having a
default: `DB_PORT` (`5432`) and `DB_SCHEMA` (`public`).
`TEST_TOKEN` is **not** required either, and has not been since 0.2.x. The only
middleware that reads it is mounted nowhere, so demanding it forced every
deployment to invent one. An `.env` that still carries it is harmless.
### Optional Variables
#### Security & JWT
| Variable | Default | Description |
| --- | --- | --- |
| `WORKING_MODE` | `development` | `development` or `production` |
| `ALGORITHM` | `HS256` | JWT signing algorithm |
| `ACCESS_TOKEN_EXPIRE_MINUTES` | `120` | JWT token lifetime |
#### Public URLs
Where this installation is reached, and where it sends people. Each one ships
with a `localhost` default, which is right on a laptop and wrong everywhere
else — a value handed to a browser or written into a mail points at the
*reader's* machine, not at the server.
**Set `APP_PUBLIC_URL` and four others follow.**
| Variable | Default | Description |
| --- | --- | --- |
| `APP_PUBLIC_URL` | `http://localhost:3000` | Public URL of the front app. **Password-reset and e-mail-verification links are built from it**, and the settings below are deduced from it |
| `PUBLIC_BASE_URL` | `http://localhost:8000` | Public URL of this API, for the callback URLs it hands out to webhooks |
| `ROOT_PATH` | `http://localhost:8000` | Base of the HTTP calls this API makes to **itself**. Usually an internal address, not the public one |
Declaring `APP_PUBLIC_URL` fills these in, their paths being fixed by the
pages that serve them — only the origin varies:
| Deduced | Becomes |
| --- | --- |
| `GITHUB_INTEGRATION_REDIRECT_URI` | `<APP_PUBLIC_URL>/integrations/github/callback` |
| `GOOGLE_INTEGRATION_REDIRECT_URI` | `<APP_PUBLIC_URL>/integrations/google/callback` |
| `FRONTEND_URLS` | `<APP_PUBLIC_URL>` |
| `CORS_ALLOWED_ORIGINS` | `<APP_PUBLIC_URL>` |
**Anything you set yourself always wins** — deducing only fills a blank, and
only from a base that is a single absolute URL, scheme included. A base
declared but empty, or holding a comma-separated list, deduces nothing and is
reported by the startup warning below. An installation that configures none of
these behaves exactly as before.
⚠️ `CORS_ALLOWED_ORIGINS` deduced from your front URL **widens** what the
browser is allowed to call from, compared with the `localhost` default. That
is the intent — but it is a security setting, so set it yourself if your
policy is narrower than "the front I just declared".
⚠️ `GITHUB_REDIRECT_URI` and `GOOGLE_REDIRECT_URI` are **not** deduced, and not
read either: the front computes its own sign-in callback from the browser's
origin and sends it with the code exchange. Setting them changes nothing.
#### CORS
| Variable | Default | Description |
| --- | --- | --- |
| `CORS_ALLOWED_ORIGINS` | `http://localhost:3000` | The origin whitelist CORS actually uses (comma-separated) |
| `FRONTEND_URLS` | `http://localhost:3000` | Despite the name, **not** read by CORS — only used to derive the Outlook mail OAuth callback |
#### OAuth — User Login
| Variable | Description |
| --- | --- |
| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | GitHub OAuth (login) |
| `GITHUB_REDIRECT_URI` | GitHub login callback |
| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | Google OAuth (login) |
| `GOOGLE_REDIRECT_URI` | Google login callback |
| `MICROSOFT_CLIENT_ID` / `MICROSOFT_CLIENT_SECRET` | Microsoft OAuth (login) |
| `MICROSOFT_TENANT_ID` | Microsoft tenant (`common` for multi-tenant) |
| `LINKEDIN_CLIENT_ID` / `LINKEDIN_CLIENT_SECRET` | LinkedIn OAuth (login) |
#### OAuth — Workspace Integrations
| Variable | Description |
| --- | --- |
| `GOOGLE_INTEGRATION_CLIENT_ID` | OAuth app for Google Workspace (Drive, Gmail, Calendar, Sheets, Docs) |
| `GOOGLE_INTEGRATION_CLIENT_SECRET` | Google integration secret |
| `GOOGLE_INTEGRATION_REDIRECT_URI` | Google integration callback |
| `MICROSOFT_INTEGRATION_CLIENT_ID` | OAuth app for Microsoft 365 (Outlook, Teams, OneDrive, SharePoint) |
| `MICROSOFT_INTEGRATION_CLIENT_SECRET` | Microsoft integration secret |
| `MICROSOFT_INTEGRATION_TENANT_ID` | Microsoft integration tenant |
| `MICROSOFT_INTEGRATION_REDIRECT_URI` | Microsoft integration callback |
| `OUTLOOK_MAIL_REDIRECT_URI` | Callback for the Outlook Mail tool connection. Deduced from `APP_PUBLIC_URL` |
| `GITHUB_INTEGRATION_CLIENT_ID` | OAuth app for GitHub workspace integration |
| `GITHUB_INTEGRATION_CLIENT_SECRET` | GitHub integration secret |
| `GITHUB_INTEGRATION_REDIRECT_URI` | GitHub integration callback |
#### Gmail Pub/Sub Webhooks
| Variable | Description |
| --- | --- |
| `GMAIL_PUBSUB_PROJECT_ID` | Google Cloud project ID |
| `GMAIL_PUBSUB_TOPIC` | Pub/Sub topic name (just the name, not the full path) |
#### RAG & Webhooks
| Variable | Default | Description |
| --- | --- | --- |
| `PUBLIC_BASE