Skip to content
Ankole

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.

  1. 01

    Get the deployment package

    bash
    git clone https://github.com/AgentBull/ankole.git
    cd ankole/tools/deploy/docker-compose
    cp .env.example .env
    chmod 600 .env
  2. 02

    Generate four independent secrets

    Copy and run this command. Then paste its complete output into .env.

    bash
    printf '%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)"
  3. 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.

    bash
    stat -c %g /var/run/docker.sock   # Linux

    Access to the Docker socket grants root-equivalent control over the host. Treat the host as a trusted first-party compute boundary.

  4. 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.
    ACME_EMAIL
    [email protected]
    Contact address for Caddy certificate management.
  5. 05

    Start and verify the stack

    Compose starts PostgreSQL 18 and ankole-function-runtime, completes migrations, then starts the control plane and Caddy.

    bash
    docker compose pull
    docker compose up -d
    docker compose ps
  6. 06

    Open the first setup

    Open https://<ANKOLE_HOST>/setup and enter the activation code.

    bash
    docker 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

  1. 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.

  2. 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.

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

  4. 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:read

      Read member profiles

    • users:read.email

      Read member email addresses

    • usergroups:read

      Read 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.

  5. 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:write

      Let the App Token open a Socket Mode connection

  6. 06

    Subscribe to directory events

    Open Event Subscriptions and enable events. Under Subscribe to bot events, add each of the five events below.

    • team_join

      A member joins the workspace

    • user_change

      A member profile changes

    • subteam_created

      A user group is created

    • subteam_updated

      A user group changes

    • subteam_members_changed

      A user-group membership changes

  7. 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
  8. 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

  1. 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:write

      Let the App Token open a Socket Mode connection

  2. 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_mention

      Receive channel @-mentions

    • message.channels

      Receive public-channel messages

    • message.groups

      Receive private-channel messages

    • message.im

      Receive direct messages

    • message.mpim

      Receive multi-person direct messages

    • reaction_added

      Receive added reactions

    • reaction_removed

      Receive removed reactions

    • member_joined_channel

      Sync members who join a channel

    • member_left_channel

      Sync members who leave a channel

    • channel_rename

      Sync channel renames

    • group_rename

      Sync private-channel renames

    • channel_deleted

      Sync channel deletion

    • channel_archive

      Sync channel archival

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

  4. 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.

  5. 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:read

      Read messages that mention the bot

    • channels:read

      Sync public channels and their members

    • channels:history

      Read public-channel messages and reconcile replies

    • groups:read

      Sync private channels and their members

    • groups:history

      Read private-channel messages and reconcile replies

    • im:read

      Sync direct-message conversations

    • im:history

      Read direct messages and reconcile replies

    • mpim:read

      Sync multi-person direct messages and their members

    • mpim:history

      Read multi-person direct messages and reconcile replies

    • chat:write

      Send, update, and delete bot messages

    • reactions:read

      Receive reaction changes

    • reactions:write

      Add and remove reactions

    • files:read

      Read files attached to messages

    • files:write

      Upload files sent by the Agent

    • users:read

      Identify channel members and exclude bot accounts

    After a scope change, reinstall the app to the workspace and write the new Bot Token to Ankole.

  6. 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:

  1. The latest provider app version is published and covers your test user in its availability scope.
  2. The bot is installed in the target channel, team, or conversation.
  3. All required message event subscriptions and OAuth scopes are active.
  4. The signal routing rule is enabled and targets the intended Agent.
  5. An effective primary Model Profile resolves for the Agent (via Site/Pod defaults in Console → Model Profiles or Agent overrides).
  6. The LLM Provider credential and model selector are valid.
  7. 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.