# Ankole

> Ankole is the open source Claude Tag alternative with a Company Brain. Its enterprise Agent Harness gives Agents shared context for company decisions.

Ankole documentation for AI Agents. Each page link opens the Markdown version of the page.

To deploy or configure an Ankole instance, read [Quick start](https://ankole.agentbull.com/en-US/docs/quickstart/index.md) first. It covers every deployment method, identity provider, LLM Provider, and chat channel. To find the cause of a failure, read [FAQ and troubleshooting](https://ankole.agentbull.com/en-US/docs/faq/index.md).

## Getting started

- [Introduction](https://ankole.agentbull.com/en-US/docs/introduction/index.md): What the Ankole Agent Harness and Company Brain provide, and how a private deployment instance works.
- [Quick start](https://ankole.agentbull.com/en-US/docs/quickstart/index.md): Deploy Ankole, set up enterprise identity and models, connect an IM channel, and complete a real Agent conversation.
- [Adapter configuration guide](https://ankole.agentbull.com/en-US/docs/adapter-configuration/index.md): Find the app type, credentials, permissions, and verification steps for each Ankole identity and chat adapter.

## User guide

- [Environment variables](https://ankole.agentbull.com/en-US/docs/worker-env/index.md): Use the Console to configure the environment variables that command-line tools, MCP servers, and Background Agent Jobs need.
- [Agents](https://ankole.agentbull.com/en-US/docs/agents/index.md): Create an Agent in the Console, then configure its owner, durable behavior, models, capabilities, and environment variables.
- [Signal routing rules](https://ankole.agentbull.com/en-US/docs/signal-bindings/index.md): Connect a chat application to an Agent and select how it handles group messages.
- [Ambient intervention](https://ankole.agentbull.com/en-US/docs/ambient-intervention/index.md): How the Agent decides whether to speak in a "May intervene" group, how its reply attaches to the person who asked, and how channel standing orders tell it when to speak.
- [Brain](https://ankole.agentbull.com/en-US/docs/brain/index.md): Give Agents durable, traceable organizational memory from conversations, files, and web pages, with explicit disclosure boundaries.
- [Workflows](https://ankole.agentbull.com/en-US/docs/workflows/index.md): Split bounded work across parallel subagents and collect one structured result in the original conversation.
- [Background Agent Jobs](https://ankole.agentbull.com/en-US/docs/background-jobs/index.md): Delegate long work to a resumable background Job while the current conversation remains available.
- [Schedules](https://ankole.agentbull.com/en-US/docs/schedules/index.md): Use Cron for recurring work or Checkback for a one-time delayed follow-up.
- [Automation Jobs](https://ankole.agentbull.com/en-US/docs/automation-jobs/index.md): Let a deterministic script consume Cron, Checkback, and Webhook triggers. Mechanical checks finish silently, and the Agent wakes only for judgment.
- [Webhook delegations](https://ankole.agentbull.com/en-US/docs/webhook-delegations/index.md): Let an Agent or deterministic script wait for a low-volume external event without polling.
- [Image generation](https://ankole.agentbull.com/en-US/docs/image-generation/index.md): Select an image model for an Agent and generate or edit images in chat.
- [OCR text recognition](https://ankole.agentbull.com/en-US/docs/ocr/index.md): Let an Agent read scanned PDFs, photos, screenshots, and receipts without a GPU or an external OCR service.
- [File management](https://ankole.agentbull.com/en-US/docs/file-management/index.md): Upload reference material, download Agent artifacts, and manage durable Agent files in the Console.
- [Agent Library](https://ankole.agentbull.com/en-US/docs/skills/index.md): Enable Agent Plugins, Skills, and Control Plane Plugins globally or for one Agent.
- [Web tools](https://ankole.agentbull.com/en-US/docs/web-tools/index.md): Configure web search and page reading for an Agent, and know when to use a browser instead.
- [Skill lessons](https://ankole.agentbull.com/en-US/docs/skill-lessons/index.md): Give each Agent short process cautions without changing the shared Skill.
- [ChatGPT subscription provider](https://ankole.agentbull.com/en-US/docs/chatgpt-subscription-provider/index.md): Connect ChatGPT subscriptions to AIGateway with device login and a shared credential pool.
- [Let an Agent read images](https://ankole.agentbull.com/en-US/docs/vision/index.md): Configure image understanding for an Agent and verify screenshots, photos, and charts from chat.
- [AppConfigure](https://ankole.agentbull.com/en-US/docs/app-configuration/index.md): Manage Ankole AppConfigure runtime settings in the Console and reference the built-in keys.
- [LLM observability](https://ankole.agentbull.com/en-US/docs/llm-observability/index.md): Export optional cross-runtime Agent Turn traces with AIGateway LLM semantics to an OTLP/HTTP receiver.
- [Principals and permission groups](https://ankole.agentbull.com/en-US/docs/principal-and-groups/index.md): Sync people and the organization directory, then assign access with directory, static, or computed groups.
- [Workers](https://ankole.agentbull.com/en-US/docs/worker-management/index.md): Check Agent Computer Worker state, capacity, and heartbeat in the Console, and resolve common failures.
- [Read logs](https://ankole.agentbull.com/en-US/docs/log-reading/index.md): Get Ankole logs from Docker Compose or Kubernetes, then use event names and context fields to locate a failure.

## Developer guide

- [Architecture](https://ankole.agentbull.com/en-US/docs/architecture/index.md): See how the control plane, Agent Computer Workers, Actor Runtime, Brain, and Background Agent Jobs form the Ankole Agent Harness.
- [AIGateway API](https://ankole.agentbull.com/en-US/docs/ai-gateway/index.md): The OpenResponses-compatible AI boundary — HTTP, SSE, and WebSocket endpoints, stateless and stateful calls, and provider routing.
- [SignalsGateway](https://ankole.agentbull.com/en-US/docs/signals-gateway/index.md): The shared-work ingress layer — how chats, webhooks, and provider events become actor events without turning source facts into execution state.
- [Actor Runtime](https://ankole.agentbull.com/en-US/docs/actor-runtime/index.md): How a long-running session lives, wakes, fails, and recovers — the actor key, the OTP failure domains, the activation fence, and the RuntimeFabric live path.
- [Background Agent Jobs](https://ankole.agentbull.com/en-US/docs/background-agent-jobs/index.md): Durable, resumable work that survives worker loss — the job state machine, wait-for-input, owner wakeup, and the boundary with the Actor Runtime.
- [Principal and AuthZ](https://ankole.agentbull.com/en-US/docs/principal-authz/index.md): The permission boundary of an Ankole deployment instance — Principals as accountable subjects, permission grants, group membership, and runtime enforcement rather than prompt convention.
- [Agent Library](https://ankole.agentbull.com/en-US/docs/agent-library/index.md): What an agent can do — skills as filesystem bundles, Agent Plugins as Codex packages, and a default-then-override enablement model resolved per agent.
- [Agent Computer Worker](https://ankole.agentbull.com/en-US/docs/agent-computer-worker/index.md): How the Bun and TypeScript Worker runs model loops, tools, files, terminal state, and streaming output while the control plane fences each turn.
- [Rust Kernel](https://ankole.agentbull.com/en-US/docs/kernel/index.md): The shared native layer — one Rust implementation of authorization, RuntimeFabric transport, and AI data-plane primitives, loaded by both the Elixir control plane and the Bun worker.
- [Control Plane Plugins](https://ankole.agentbull.com/en-US/docs/control-plane-plugins/index.md): The first-party Elixir extension model — discovered and active plugins, subsystem contracts, AppConfigure keys, supervised children, and the next-start enable boundary.
- [Develop Skills and Control Plane Plugins](https://ankole.agentbull.com/en-US/docs/writing-a-skill/index.md): Add a work method for Agents, or add identity, channel, configuration, and supervised services to the control plane.
- [Worker CLI capabilities](https://ankole.agentbull.com/en-US/docs/cli-capabilities/index.md): Ship an Agent capability as a shell command whose --help carries the contract, and place one-sentence pointers where the Agent makes the related decision.
- [Adding a provider](https://ankole.agentbull.com/en-US/docs/adding-a-provider/index.md): How to declare an AIGateway provider — the DSL, the compiled definition, settings, capabilities, the prepare function, and plugin-based registration.
- [Context compression and compaction](https://ankole.agentbull.com/en-US/docs/context-compression-and-caching/index.md): How Ankole keeps long conversations within a model's context — AIGateway automatic history compaction and verbatim user-original retention.
- [The agent loop](https://ankole.agentbull.com/en-US/docs/agent-loop/index.md): The boundary between the control-plane turn lifecycle and the worker-side agent loop — what each side owns, how they communicate, and where the iteration budget and retry live.
- [Prompt assembly](https://ankole.agentbull.com/en-US/docs/prompt-assembly/index.md): How the system prompt an agent sees each turn is built — the control-plane data providers, the two channels that carry it to the worker, and the worker-side assembly that produces the final prompt.
- [Provider runtime](https://ankole.agentbull.com/en-US/docs/provider-runtime/index.md): How AIGateway resolves a selector to a provider, builds a prepared request, and dispatches it through the kernel — the three stages from a model call to a provider response.
- [Tools runtime](https://ankole.agentbull.com/en-US/docs/tools-runtime/index.md): How the Worker schemas and dispatches per-turn tools, including main-turn Workflow tools and the restricted Workflow task catalog.
- [Trajectory and message format](https://ankole.agentbull.com/en-US/docs/trajectory-format/index.md): How Ankole stores and projects conversation messages and background-job trajectories — the two storage shapes, the ChatML canonical form, and the model-visible projection.
- [Code execution](https://ankole.agentbull.com/en-US/docs/code-execution/index.md): How an Ankole Agent runs code in a conversation or as a durable Background Agent Job.
- [Use an MCP-backed Skill](https://ankole.agentbull.com/en-US/docs/using-mcp/index.md): How an enabled Skill routes an Agent or Automation script to an MCP server through mcporter.
- [Todo and clarify](https://ankole.agentbull.com/en-US/docs/todo-and-clarify/index.md): How an Ankole agent plans a complex task and resolves a real ambiguity mid-task — the todo tool (per-session, at most one item in progress) and the clarify tool (one decision question, durably recorded, ends the turn). What the agent uses each for, and what an operator should not expect them to do.
- [Audit trail](https://ankole.agentbull.com/en-US/docs/audit-trail/index.md): How to read Ankole's audit surfaces — the AuthZ grant record, the control-plane structured logs, and what each records about who changed what and when.
- [AIGateway API usage](https://ankole.agentbull.com/en-US/docs/aigateway-api-usage/index.md): How external callers use the AIGateway REST API — the OpenResponses-compatible endpoints, the agent vs admin token, stateless and stateful calls, and worked examples.

## Reference

- [kit CLI reference](https://ankole.agentbull.com/en-US/docs/kit-cli/index.md): The devkit command surface — every `bun run kit` command an operator or contributor runs, what it does, and the scripts that wrap it.
- [MCP server reference](https://ankole.agentbull.com/en-US/docs/mcp/index.md): How Skill-backed MCP dependencies enter Main, Background, and Automation executions.
- [Deployment environment variables](https://ankole.agentbull.com/en-US/docs/environment-variables/index.md): Reference the deployment settings that the control plane and Agent Computer Worker read at process start.
- [Console API reference](https://ankole.agentbull.com/en-US/docs/console-api/index.md): Reference for the /api/v1 REST API that the Console uses, including authentication, resource routes, and authorization actions.
- [FAQ and troubleshooting](https://ankole.agentbull.com/en-US/docs/faq/index.md): Diagnose Ankole deployment, identity, model, Worker, and chat-channel failures from the symptom you can observe.

## Guides

- [Run long research with Deep Research](https://ankole.agentbull.com/en-US/docs/deep-research-job/index.md): Move multi-source research to a Background Agent Job that uses pluggable research methods and delivers a sourced report after independent review.
- [Git integration](https://ankole.agentbull.com/en-US/docs/git-integration/index.md): How an Ankole Agent uses git in a normal conversation or a Background Agent Job.
- [Jupyter data analysis](https://ankole.agentbull.com/en-US/docs/jupyter-data-analysis/index.md): How to set up an agent that runs iterative Python data analysis through a live Jupyter kernel — the jupyter-live-kernel skill, DataFrame inspection, and a worked example.
- [Browser automation](https://ankole.agentbull.com/en-US/docs/browser-automation/index.md): How an Ankole agent drives a real browser session — the browser skill, when to use it instead of web_search/web_fetch, how to enable it, and why the agent must use the preconfigured ankole-browser CLI instead of launching Chromium itself.
- [PDF generation](https://ankole.agentbull.com/en-US/docs/pdf-generation/index.md): How to set up an agent that creates, checks, and edits PDF files — the pdf skill, the tools it uses, and a worked example.
- [Context.dev web data](https://ankole.agentbull.com/en-US/docs/context-dev/index.md): Give an Agent bot-resistant page reading, whole-site crawling, schema-shaped extraction, brand profiles, and scheduled change monitoring through the Context.dev API.
- [Operator tips](https://ankole.agentbull.com/en-US/docs/tips/index.md): Short, tested moves that save time when running Ankole — reading logs, scoping agents, rotating secrets, recovering from a stuck turn, and getting the model profile dials right.
- [Automation blueprints](https://ankole.agentbull.com/en-US/docs/automation-blueprints/index.md): Combine triggers with Agent sessions, automation jobs, background jobs, and signal routing rules, and distinguish them from Workflows.
- [Cost management](https://ankole.agentbull.com/en-US/docs/cost-management/index.md): The levers that control what Ankole spends — model profiles, reasoning effort, web tools, turn budgets, Workflow fanout, and background-job caps.
- [Backup and restore](https://ankole.agentbull.com/en-US/docs/backup-and-restore/index.md): The two things you must back up — PostgreSQL and Agent Home — how to back them up, how to restore them, and why an untested backup is not a backup.
- [Security hardening](https://ankole.agentbull.com/en-US/docs/security-hardening/index.md): The end-to-end shape of hardening an Ankole deployment instance — least authority, secret discipline, SSRF, credential rotation, and minimum ingress.
- [Performance tuning](https://ankole.agentbull.com/en-US/docs/performance-tuning/index.md): The capacity knobs — concurrent turns, database pool, Postgres max connections, worker turn caps, per-agent job slots — and the relationships between them that decide how much a deployment instance can do at once.
- [Disaster recovery](https://ankole.agentbull.com/en-US/docs/disaster-recovery/index.md): The full shape of recovering an Ankole deployment instance from loss — what is recoverable, what is not, the cross-host migration, and the rehearsal that makes a recovery real.
- [Contributing](https://ankole.agentbull.com/en-US/docs/contributing/index.md): The path to a merged Ankole contribution — where the rules live, how to set up, how to run the right checks, and the changelog and PR discipline the project requires.

## Other languages

- [中文](https://ankole.agentbull.com/zh-Hans-CN/llms.txt)
- [日本語](https://ankole.agentbull.com/ja-JP/llms.txt)
- [한국어](https://ankole.agentbull.com/ko-KR/llms.txt)

## Optional

- [Full documentation](https://ankole.agentbull.com/en-US/llms-full.txt): all pages in this language in one Markdown file