Quick start
For AI Agents: the Markdown version of this page is at https://ankole.agentbull.com/en-US/docs/quickstart/index.md. The documentation index is at https://ankole.agentbull.com/en-US/llms.txt.
How Ankole is deployed
Every private Ankole deployment runs one control plane alongside a dedicated Agent Computer Worker for each Agent: the control plane owns durable domain state and supervision, while each Worker provides an isolated execution environment that acts as that Agent’s personal work computer.
Agents never share a Worker, just as human teammates each use their own workstation. Whenever you create an Agent, the control plane provisions its Worker automatically through the assigned WorkerProvider and manages stopping, replacing, and deleting that Worker throughout its lifecycle.
Every deployment requires PostgreSQL, a control-plane file store, and persistent storage for each Agent Home. In Kubernetes, the default Helm chart provisions a shared ReadWriteMany claim for Agent Homes alongside separate ReadWriteOnce cache claims—always back up Agent Homes, whereas cache claims are rebuildable.
A single site can also host multiple tenants: site operators run the shared infrastructure, while each tenant owns its own Principals, Agents, Brain, and integrations. By default, the Site Admin Console is served at /site-admin-console (configurable before startup via ANKOLE_SITE_ADMIN_CONSOLE_PATH or Helm’s controlPlane.siteAdminConsolePath).
Terms used in this guide
The table below maps the canonical terms used across Ankole’s interfaces and docs (with matching third-party or API terms in parentheses) to the short forms used throughout the rest of this guide:
| Canonical term | Meaning | Short form |
|---|---|---|
| Site | One complete Ankole deployment with shared infrastructure and trusted operators | Site |
| Tenant | One organization’s people, Agents, Brain, integrations, and work inside a site | Tenant |
| Principal | A person, Agent, or system service that holds an identity and permissions in Ankole | Principal |
| Identity Provider (IdP) | An external identity source that provides Console SSO and synchronizes employees, contacts, and organization structure | IdP |
| Chat platform | An external conversation platform such as Slack, Teams, Lark/Feishu, DingTalk, WeCom, Telegram, Discord, LINE, WhatsApp, or a mailbox | Platform |
| Channel Provider | One chat application or bot configuration that receives messages and sends Agent replies | Channel Provider |
| Conversation | A shared space for people and Agents; native messages use Ankole as their authority, while external messages use their host platform | Conversation |
| Message | A committed record visible to conversation participants | Message |
| Signal | A durable stimulus triggered by a message, schedule, external event, or task completion | Signal |
| Session | An execution context with its own signal queue and recoverable progress, used for conversations, scheduled work, background jobs, or workflow tasks | Session |
| Delivery | A durable intent, attempt, and result for sending a message to an external conversation | Delivery |
| Signal Routing Rule (Signal Binding) | The rule that routes messages or events from a signal source to a target Agent | Routing rule |
| LLM Provider | A configuration storing a model service endpoint, credentials, and available models | LLM Provider |
| Model Profile | A capability slot (primary, light, heavy, and multimodal or retrieval slots) inherited across Site -> Pod -> Agent/System |
Model Profile |
Let an Agent complete the setup
You can paste this prompt into Codex, Claude Code, or another terminal-capable coding Agent to walk through deployment and verification with you:
Use https://ankole.agentbull.com/en-US/docs/quickstart/index.md to help me deploy and configure a private Ankole deployment instance. First, inspect my environment and recommend Docker Compose, Kubernetes, or installing from source. Then help me set up sign-in via Email OTP or an Enterprise SSO Identity Provider (IdP), plus the LLM Provider, Agent, Channel Provider, and Signal Routing Rule (Signal Binding). If I did not specify a sign-in method and IM platform, ask which sign-in method (SMTP Email OTP or enterprise IdP) and chat platform I want to use. Do not choose them for me. Do not expose secrets in chat or command output. You are finished only when I receive a real Agent reply in my selected IM.
1. Deploy Ankole
Choose Docker Compose for single-host deployments, Kubernetes for production cluster deployments, or source installation for local development and debugging.
Tenant pages use <tenant-slug>.<site-host> (for example, team.ankole.example.com). For a public deployment, configure DNS, HTTPS certificates, and proxy or Ingress routing for every tenant host so it reaches the same control plane. The Compose Caddy and Helm Ingress examples below cover only the site host.
Before starting Ankole for the first time, pick a permanent Worker installation name (1–20 lowercase letters, digits, or hyphens, starting and ending with an alphanumeric character—for example, e2e-1011b01). Set it via ANKOLE_WORKER_INSTALLATION in Compose (default ankole) or worker.installation in Helm (defaulting to the Helm release name), and keep it unchanged afterward because Worker resources and persistent Agent Home paths are keyed to it.
One host runs PostgreSQL 18, ankole-function-runtime, the control plane, and Caddy. The selected provider creates one Worker per Agent.
Before you start
- A Linux, macOS, or Windows host that can run Linux amd64 or arm64 containers
- Docker Engine with the Compose plugin, or Docker Desktop
- Persistent disk, a DNS name, and ports 80 and 443
Basic setup
Install with Docker Compose
Keep provider API keys out of this deployment file. You will add them in the Console after sign-in.
- 01
Get the deployment package
bashgit clone https://github.com/AgentBull/ankole.git cd ankole/tools/deploy/docker-compose cp .env.example .env chmod 600 .env - 02
Generate four independent secrets
Copy and run this command. Then paste its complete output into .env.
bashprintf '%s\n' \ '# PostgreSQL database password' \ "POSTGRES_PASSWORD=$(openssl rand -hex 24)" \ '' \ '# ANKOLE master encryption key' \ "ANKOLE_SECRET_BASE=$(openssl rand -hex 32)" \ '' \ '# Erlang distribution cookie of the control plane' \ "RELEASE_COOKIE=$(openssl rand -hex 32)" \ '' \ '# Shared token between the control plane and ankole-function-runtime' \ "ANKOLE_FUNCTION_RUNTIME_TOKEN=$(openssl rand -hex 32)" - 03
Set the Docker socket group
The control plane runs as an unprivileged user and provisions Worker containers through the Docker socket using the socket’s owning group ID.
On Linux, set ANKOLE_DOCKER_GID in .env to the group ID printed below. On macOS with Docker Desktop, set ANKOLE_DOCKER_GID=0—Docker Desktop exposes the container socket as group 0 regardless of what the host reports. Set ANKOLE_DOCKER_SOCKET only if your socket path differs from /var/run/docker.sock.
bashstat -c %g /var/run/docker.sock # LinuxAccess to the Docker socket grants root-equivalent control over the host. Treat the host as a trusted first-party compute boundary.
- 04
Set the public host
Set ANKOLE_HOST to the DNS name that points to this host. Set ACME_EMAIL to an address that can receive certificate notices.
- ANKOLE_HOST
- ankole.example.com
- The HTTPS host that people and provider callbacks will use.
- 05
Start and verify the stack
Compose starts PostgreSQL 18 and ankole-function-runtime, completes migrations, then starts the control plane and Caddy.
bashdocker compose pull docker compose up -d docker compose ps - 06
Open the first setup
Open https://<ANKOLE_HOST>/setup and enter the activation code.
bashdocker compose logs control-plane | grep "SETUP ACTIVATION CODE"
2. Set up sign-in and identity first
Ankole is built for private enterprise deployments where a single site can host multiple tenants, each modeling its employees, Agents, and system services as Principals governed by AuthZ. Finishing /setup grants the initial administrator both siteadmin (for the Site Admin Console at /site-admin-console) and pod_admin on the default Pod—always select the target tenant in the Console before editing tenant-scoped settings.
During /setup, configure sign-in before setting up any chat channel: choose either passwordless Email OTP (email_otp via your SMTP server and a 6-digit verification code) or an Enterprise SSO Identity Provider (IdP) that also syncs employees, directory contacts, and organizational groups.
| Setting | What it controls | Configure it where |
|---|---|---|
Email OTP (email_otp) |
Passwordless 6-digit email verification (authn.email.mail SMTP transport and SiteCredential bindings) plus email invitations |
/setup (Email verification), or CLI mix ankole.authn.mail.put |
| Identity Provider (IdP) | Enterprise SSO and the employees, contacts, organization structure, and permission groups synchronized from the enterprise directory | /setup first, then Console → Identity Providers |
| Channel Provider | The IM app or bot that receives messages and sends Agent replies | Console → Signal Routing |
Sign-in and chat channels do not have to share the same platform: for example, you can sign in with Email OTP or Google Workspace while chatting in Slack, or run SSO through Microsoft Entra ID while routing conversations over Lark/Feishu, Slack, DingTalk, Teams, or WeCom.
Complete the setup for your sign-in method
Select Email OTP or your organization’s enterprise identity provider below (each enterprise SSO tab walks from app creation in the provider console through initial sign-in and full directory sync).
When enabling an enterprise adapter for the first time, restart the control plane after completing your initial sign-in so Ankole launches the plugin’s background workers, such as directory streams and Microsoft Graph subscriptions.
Use one Slack app for Console sign-in and for workspace member and user-group sync. The default setup needs an OAuth client, a Bot Token, and an App Token.
Before you start
- A workspace administrator who can create and install a Slack app
- A public HTTPS address for Ankole
- A workspace member account for the first sign-in
Basic setup
Set up the Slack IdP
- 01
Copy the callback URL from Ankole
Open https://<ANKOLE_HOST>/setup and enter the activation code. Select Slack Adapter on the plugin page, save the selection, and then select Slack.
Keep Configuration ID (Provider ID) as slack-main. Use Copy to copy the login callback URL. Do not type or change this URL by hand.
- 02
Create the Slack app
Open Slack API Your Apps and select Create New App → From scratch. Enter an app name and select the workspace that holds your employees.
Open Basic Information → App Credentials. Copy the Client ID and Client Secret.
- 03
Register the login callback
Open OAuth & Permissions → Redirect URLs. Select Add New Redirect URL, paste the complete URL from Ankole, and save it.
Ankole requests the openid, profile, and email sign-in scopes by default. Do not replace them with chat bot scopes.
- 04
Grant directory access and get the Bot Token
On OAuth & Permissions, add the three scopes below under Bot Token Scopes. Then select Install to Workspace and approve the installation.
users:readRead member profiles
users:read.emailRead member email addresses
usergroups:readRead user groups and their members
Copy the Bot User OAuth Token after installation. It must start with xoxb-. Reinstall the app after each scope change.
- 05
Get the App Token and enable Socket Mode
Open Basic Information → App-Level Tokens. Select Generate Token and Scopes, add the scope below, and copy the generated xapp- token. Then open Socket Mode and turn on Enable Socket Mode.
connections:writeLet the App Token open a Socket Mode connection
- 06
Subscribe to directory events
Open Event Subscriptions and enable events. Under Subscribe to bot events, add each of the five events below.
team_joinA member joins the workspace
user_changeA member profile changes
subteam_createdA user group is created
subteam_updatedA user group changes
subteam_members_changedA user-group membership changes
- 07
Enter the Slack values in Ankole
Keep Sync directory and Sync directory changes on. Select Validate configuration and sign in. Then complete the Slack authorization.
- Client ID: the Client ID from Basic Information
- Client Secret: the Client Secret on the same page
- Workspace ID: optional. Enter the T… value after /client/ in the Slack web URL to preselect a sign-in workspace; it does not limit directory sync
- Bot User OAuth Token: the xoxb- token
- App-Level Token: the xapp- token
- 08
Verify sign-in and the first sync
After Slack returns to Ankole, this user receives both siteadmin (Site Admin Console at /site-admin-console) and default Pod pod_admin. Open Console → Identity Providers, select slack-main, and select Run full sync.
When the sync finishes, check Console → Principals and Principal groups for the workspace members and Slack user groups.
3. Add an LLM Provider and create an Agent
Register your LLM Provider first: sign in to the Console, open Providers → New provider, pick the provider kind, paste its API key, and save. The Console suggests a Provider ID and uses the provider’s default endpoint, so only a service that assigns an address per resource, such as Azure OpenAI, or a self-hosted or compatible endpoint needs one. Ankole encrypts provider credentials inside the control plane—never place them in deployment .env files or Agent workspace files.
Next, open Console → Model Profiles to set your Site defaults across the core language-model slots, which every Pod and Agent inherits (Site -> Pod -> Agent/System, with cross-slot fallbacks heavy -> primary and light -> primary):
| Profile | First-run use |
|---|---|
primary |
Main reasoning model (required; light and heavy fall back here when unset) |
light |
High-volume, low-cost turns and ankole_brain extraction |
heavy |
Complex synthesis, Background Agent Jobs, Dreaming, and Skill lesson review |
Binding a known-good provider and model to primary in the Site defaults makes every Agent and ankole_brain ready to run right away; split light and heavy onto dedicated tiers once your end-to-end conversation path works.
Inside Pod, every internal member automatically receives a 1:1 Personal Assistant in Pod Chat. To create a shared specialist AI Colleague (for Pod rooms or external IM routing), open Agents → New Agent, set a meaningful lowercase tenant-scoped uid (such as research-analyst), display name, role, owner, and WorkerProvider, and save. Agents inherit your Site and Pod Model Profiles unless you override specific slots on the Agent, while behavioral and visual rules live in AGENTS.md and DESIGN.md under Meta Ankole → Agents.
4. Connect a chat channel and create its signal routing rule
Members can chat with their Personal Assistant and AI Colleagues in Pod Chat immediately without a routing rule. To connect an external IM platform, enable its Control Plane Plugin in the Console. On platforms supported by Ankole.Connectors—such as Lark / Feishu—registering a shared application connection (authConfigId) in Pod → Connections (/connectors) or Console lets you reuse that single app across SSO, directory sync, IM Signal routing, MCP Toolkits, and event triggers without creating duplicate apps or re-entering secrets. Whenever multiple AI Colleagues need distinct bot identities, avatars, or permission scopes, register dedicated bot connections for each Agent and bind them via separate routing rules.
How Ankole resolves chat senders depends on the platform category:
- Enterprise platforms (Slack, Teams, Lark/Feishu, DingTalk, WeCom): Senders match directly against directory Principals synced by your IdP.
- Consumer IMs (Telegram, Discord, LINE, WhatsApp): Senders have no directory employee record, so an administrator links each new sender under Identity → Pending mappings before the Agent serves them (except on WhatsApp when an existing account already owns that verified phone number).
- Email: Connects a dedicated mailbox and admits senders strictly through explicit Pod email identity bindings.
Slack uses Socket Mode. Ankole opens an outbound WebSocket, so the chat path does not need a public Slack webhook.
Before you start
- Permission to create and install a Slack app
- A test channel or direct message
Basic setup
Prepare a Slack app
- 01
Create the app and enable Socket Mode
Create a Slack app from scratch. Under Basic Information, create an App-Level Token, add the scope below, and then enable Socket Mode.
connections:writeLet the App Token open a Socket Mode connection
- 02
Subscribe to chat and channel-state events
Open Event Subscriptions → Subscribe to bot events. Add each event below. This set matches the message, reaction, and channel-state capabilities implemented by the Slack adapter.
app_mentionReceive channel @-mentions
message.channelsReceive public-channel messages
message.groupsReceive private-channel messages
message.imReceive direct messages
message.mpimReceive multi-person direct messages
reaction_addedReceive added reactions
reaction_removedReceive removed reactions
member_joined_channelSync members who join a channel
member_left_channelSync members who leave a channel
channel_renameSync channel renames
group_renameSync private-channel renames
channel_deletedSync channel deletion
channel_archiveSync channel archival
- 03
Enable direct messages
Open App Home → Show Tabs. Turn on Display Messages tab and select Allow users to send Slash commands and messages from the messages tab. The Messages tab alone shows the surface but does not let users send direct messages to the Agent.
- 04
Enable Slack-native interactivity
Open Interactivity & Shortcuts and enable Interactivity. Socket Mode delivers Block Kit button actions over the existing WebSocket, so a public Request URL is not required.
- 05
Grant the complete chat scopes and install the app
Under OAuth & Permissions → Bot Token Scopes, add each scope below. This set covers only Slack APIs that Ankole calls. Do not grant unused assistant, workflow, document, or meeting scopes.
app_mentions:readRead messages that mention the bot
channels:readSync public channels and their members
channels:historyRead public-channel messages and reconcile replies
groups:readSync private channels and their members
groups:historyRead private-channel messages and reconcile replies
im:readSync direct-message conversations
im:historyRead direct messages and reconcile replies
mpim:readSync multi-person direct messages and their members
mpim:historyRead multi-person direct messages and reconcile replies
chat:writeSend, update, and delete bot messages
reactions:readReceive reaction changes
reactions:writeAdd and remove reactions
files:readRead files attached to messages
files:writeUpload files sent by the Agent
users:readIdentify channel members and exclude bot accounts
After a scope change, reinstall the app to the workspace and write the new Bot Token to Ankole.
- 06
Collect the Console fields
- botToken
- xoxb-…
- Bot User OAuth Token. The xoxb- prefix is required.
- appToken
- xapp-…
- App-Level Token for Socket Mode. The xapp- prefix is required.
Complete the connection in the Console
Each signal routing rule links one Channel Provider to one target Agent—storing the adapter, app credentials, target Agent, and group-message policy—so create a separate rule per bot under Signal Routing → New routing rule:
| Field | What to choose |
|---|---|
| Target Agent | The Agent you created in step 3 |
| Adapter | Slack, Teams, Lark/Feishu, DingTalk, WeCom, Telegram, Discord, LINE, WhatsApp, or Email |
| Rule name | A stable name such as slack-main or lark-main |
| Group message mode | Start with addressed_only |
| Channel settings | Paste the credentials and values from the channel tab |
Save the rule and confirm that it appears as enabled. If Ankole rejects a credential on save, resolve that validation error before testing in chat—the adapter has not opened its platform connection yet.
5. Talk to the Agent in the IM
Invite the bot into a test conversation and, in group chats, start with an explicit @mention:
@Ankole What can you do, and which team are you serving?
Once you receive the first live reply, refine the Agent’s AGENTS.md and DESIGN.md contracts in Meta Ankole → Agents, tune its Model Profile tiers, and adjust the group-message policy for production use.
If the Agent does not reply
Walk through each boundary in order:
- The latest provider app version is published and covers your test user in its availability scope.
- The bot is installed in the target channel, team, or conversation.
- All required message event subscriptions and OAuth scopes are active.
- The signal routing rule is enabled and targets the intended Agent.
- An effective
primaryModel Profile resolves for the Agent (via Site/Pod defaults in Console → Model Profiles or Agent overrides). - The LLM Provider credential and model selector are valid.
- If the turn needs environment tools or a Codex task, check the Agent’s Worker under Console → Workers and inspect any startup failure shown there. Creating an Agent requests an initial Worker start; after idle release, plain Q&A and control-plane tools do not require a Ready Worker.
On Docker Compose, tail docker compose logs -f control-plane, list Worker containers with docker ps -a --filter label=ankole.installation=ankole, and inspect a specific Worker via docker logs CONTAINER_NAME. On Kubernetes, check the control-plane and Worker Pod logs—always reading only the relevant error lines without dumping environment variables or secrets.
Once your Agent replies end to end, continue with Agents, Signal routing rules, or Background Agent Jobs.