# Ankole

> Ankole is the open-source Agent Harness with a Company Brain—an open-source alternative to Claude Tag where AI Agents handle ongoing work right inside your team's existing chat tools.

Ankole documentation for AI Agents. Every link below opens the clean Markdown edition of that page.

To deploy or configure an Ankole instance, start with [Quick start](https://ankole.agentbull.com/en-US/docs/quickstart/index.md)—it walks through every deployment option, identity provider, LLM provider, and chat channel. To troubleshoot a failure, check [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 an Agent's drive in the Console.
- [Agent Library](https://ankole.agentbull.com/en-US/docs/skills/index.md): Manage tenant and per-Agent Agent Plugins and Skills, and site-scoped Control Plane Plugins.
- [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 each Agent's Worker in the Console, see how the control plane manages it, and resolve common failures.
- [Read logs](https://ankole.agentbull.com/en-US/docs/log-reading/index.md): Get Ankole logs from Docker Compose, Kubernetes, or Cloudflare, 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, Sessions, Brain, and Background Agent Jobs form the Ankole Agent Harness.
- [Conversations, signals, and sessions](https://ankole.agentbull.com/en-US/docs/conversations-signals-sessions/index.md): The design choices and costs behind Ankole, with a source-checked comparison of deepseek-harness, pi durable, and qm.
- [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.
- [Signals](https://ankole.agentbull.com/en-US/docs/signals/index.md): Durable events, routing rules, shared conversation facts, and external delivery.
- [Sessions](https://ankole.agentbull.com/en-US/docs/sessions/index.md): Agent execution, shared history reads, writer fences, and recovery.
- [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 Sessions.
- [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 file 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): Environment tools, Codex, persistent Home, and recovery across control-plane replacement.
- [Rust Kernel](https://ankole.agentbull.com/en-US/docs/kernel/index.md): Native primitives and AI transport loaded by the Elixir control plane through Rustler.
- [Control Plane Plugins](https://ankole.agentbull.com/en-US/docs/control-plane-plugins/index.md): First-party Elixir extensions for the control plane, including activation modes, subsystem contracts, transaction hooks, Cohort supervision, and next-start configuration.
- [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 site-scoped adapters, configuration, domain hooks, supervised services, and UI slots 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 control-plane Driver, durable model and tool steps, and the Worker execution boundary.
- [Prompt assembly](https://ankole.agentbull.com/en-US/docs/prompt-assembly/index.md): How the control plane renders main Agent instructions and separates Codex Job context.
- [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): Control-plane tool declarations, dispatch, and Worker environment execution.
- [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): Control-plane task lists, decision questions, and the separate Codex Job input path.
- [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 and OIDC Human tokens, 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/v2 APIs 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.
- [Upgrade from 1.0 to 2.0](https://ankole.agentbull.com/en-US/docs/upgrade-to-2/index.md): Move a 1.x site to 2.0, migrate the database, Workers, Agent Homes and drives, and verify recovery.
- [Cost management](https://ankole.agentbull.com/en-US/docs/cost-management/index.md): The configuration levers that control Ankole token and tool spend across model profiles, reasoning effort, web tools, turn budgets, Workflow fanout, background-job caps, and per-Agent token quotas.
- [Backup and restore](https://ankole.agentbull.com/en-US/docs/backup-and-restore/index.md): Back up PostgreSQL, the file store, persistent Agent Homes, and the deployment secrets. Test them together.
- [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.
- [WorkerProviders and cache disks](https://ankole.agentbull.com/en-US/docs/worker-providers/index.md): Compare Docker, Kubernetes, Cloudflare, Vercel, Lambda, and Function Compute limits, and configure Home and SQLite cache storage.
- [Control-plane drive and object storage](https://ankole.agentbull.com/en-US/docs/drive-storage/index.md): Configure local files, cloud buckets, database tables, SFTP, or WebDAV for Ankole.ObjectStore (Agent drives, Pod file pages, attachments, and compiled Applet bundles), including migration and backup.
- [Performance tuning](https://ankole.agentbull.com/en-US/docs/performance-tuning/index.md): Worker slots, model concurrency, database pools, Job limits, and idle release.
- [Disaster recovery](https://ankole.agentbull.com/en-US/docs/disaster-recovery/index.md): Recovering an Ankole deployment from loss across PostgreSQL, Base shard databases, the file store, Agent Homes, Function Runtime, and deployment secrets.
- [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 combined into a single Markdown file