CopilotKit OpenBot: self-hosted AI coworkers with a browser, files and an audit trail

The access problem OpenBot is built around

Most agent demos stop at the interesting part. The agent can browse, run a command, read a file, and nobody has written down what it was allowed to do or what it did. OpenBot is aimed at that gap. The README frames the difference as "the difference between an agent that can use your tools and an agent you can let near them," and that sentence is the whole product thesis.

The intended user is an engineer or platform team running agents inside their own infrastructure, not a person looking for a hosted assistant. The README is explicit that OpenBot is "a template, not a product": there is no hosted version to sign up for, and every workspace in the repository is private. You clone it, replace the example tenant package under examples/ with your own coworkers, channels and skills, and run it. Three coworkers ship in the example package and they are configuration rather than code: General Assistant, Knowledge and Risk Analyst. You add more by editing agents.yaml or through /agents in the UI.

That positioning has a cost worth naming early. Because it is a template, there is no upgrade path where someone else handles a breaking change for you. The version in package.json is 0.0.11, the README carries an alpha badge, and the release history shows v0.0.6, v0.0.7 and v0.0.8 landing within three days of each other in early September 2026. The last push to main was on 2026-09-10. Treat the shape of the configuration as something you own.

One gateway between a Bot and everything it touches

The architecture is described in the README's diagram caption. You talk to the server, the server sends the turn to a Bot over AG-UI, and every tool call the Bot makes comes back through the gateway. The gateway resolves the target, decides it against your policy, records an audit row, and only then acts. If the policy refuses, it refuses and names the rule. Allowed browser and file actions reach that Bot's own computer, one container each with its own Chromium, logins and workspace, built by the supervisor. Decisions land in PostgreSQL; threads live in CopilotKit Intelligence.

The ordering matters more than the component list. Decide, record, then act. An audit row exists for refusals as well as executions, which is what makes the trail useful when you are trying to reconstruct why an agent did not do something.

Because a Bot is any endpoint speaking AG-UI, the governance rides the protocol rather than the framework. The README names LangGraph, Mastra, CrewAI, Pydantic AI, Google ADK and hand-written agents as all arriving the same way, and the repository layout backs that up with directories such as agent-langgraph, agent-mastra, agent-crewai, agent-pydantic-ai and agent-adk sitting alongside agent-computer and supervisor. If you already have an agent, the integration surface is the protocol, not a rewrite.

Installing OpenBot and getting to a first running Bot

The requirements are Docker for PostgreSQL and the shipped Bots, Bun 1.3 or newer for the app and API server, a CopilotKit Intelligence project and license, and a model key. The proof-of-concept Bot uses OpenAI; the LangGraph Bot can use OpenAI, Anthropic or Google. The README notes a free Intelligence plan and that Intelligence can be self-hosted.

Start by copying the environment file. The README gives the rest of the setup in five steps.

cp .env.example .env

Next, get the Intelligence credentials. The README states that the cpk-... runtime key from project select is the only Intelligence credential you need, because managed Intelligence derives entitlement from the project key.

npx --yes copilotkit@latest login
npx --yes copilotkit@latest project select

Put that key in .env as INTELLIGENCE_API_KEY and fill in OPENAI_API_KEY. The README says to keep the managed Intelligence URLs from .env.example unless you run Intelligence yourself. The example KEY_ENCRYPTION_KEY is public and fine locally, and the README gives this command to generate your own:

openssl rand -base64 32

Then install and run. The README says scripts/start.sh starts Docker services, applies migrations, starts the API server on port 3001, starts the app on port 3010, and checks that the services answer their own health routes before printing next steps.

bun install
bash scripts/start.sh

Open http://localhost:3010. The README notes that .env.example carries OPENBOT_SINGLE_USER=true, which admits every request as one administrator so a fresh clone reaches the product without registering an OAuth client first. Sign-in turns that off and is required before anybody else can reach the deployment. To stop, scripts/stop.sh takes the same things down, including each Bot's computer, which compose does not own. Nothing is deleted: the database, the Bots' files and their browser profiles are volumes.

If you would rather paste the setup into an AI assistant, the README points at prompt.txt, which carries the same steps plus which of the ten blank keys in .env.example are actually yours to fill (three), which the start script generates, and what each start-up refusal means.

Why the compose file keeps PostgreSQL off the Bots' network

The docker-compose.yml comments are unusually candid, and they describe a limitation you should understand before you extend the deployment. The postgres service is deliberately kept off the network the Bots are on. The reasoning given in the file is that with no networks: anywhere, Compose puts every service on one network with DNS by service name, so agent-computer could open postgres:5432, and the credentials are three lines below in the same file. That would put the audit trail, the policy store and the agent tables reachable from the one container whose whole job is to run what a Bot asks for. The comment cites agent-computer/src/shell.ts: isolation is the container's job, a shell can reach whatever the container can reach.

The ports are published on loopback for the same reason. The file notes that published on every interface, PostgreSQL is reachable from the Bot's computer at the container's default gateway, which is the host. The comment says this was proven from inside agent-computer, where the gateway on :5432 answered and began authenticating as openbot on openbot with the password in the file.

This is a real constraint on how you deploy. A single-host laptop setup is what the README is written for. The Dockerfile comments add a second one: the supervisor exists to give each Bot its own container, which needs a Docker socket, which no serverless container platform permits. Without it, every Bot shares the browser, exactly as they do on a laptop with no supervisor configured, and the file labels per-Bot isolation as A6, meaning unfinished.

The audit trail is append-only, and retention is the only lever

The .env.example comments describe the retention behaviour precisely. AUDIT_RETENTION_DAYS controls how many days of audit trail to keep. Unset keeps everything, which the file calls the safe default and the one to leave alone until somebody has decided otherwise. The reason given is that the trail is append-only and nothing else can remove a row, so this variable is the only way it ever shrinks.

That is a design choice with an operational consequence. You cannot prune selectively, and you cannot delete a mistaken row. If you need a shorter retention window for policy reasons, you set the number before you accumulate data, not after. The same file warns that production refuses to start with the public example KEY_ENCRYPTION_KEY, which is a sensible refusal but also a failure mode worth expecting on a first production attempt.

There is a second configuration trap documented in the same file. The server accepts either PORT or SERVER_PORT, preferring PORT when both are present and refusing to start if they disagree. The comment explains that scripts/start.sh and the app's Vite proxy read SERVER_PORT and APP_PORT, and that docs/configuration.md documents SERVER_PORT as the setting. Only PORT shipped historically, so moving the server by editing one line left the script still looking at 3001. It found whatever else was there, accepted the first 200 as proof, and failed several stages later parsing that stranger's HTML as JSON. Setting both to the same value remains valid. An empty value counts as unset, so PORT= with SERVER_PORT set moves the server too.

OpenBot compared with a hosted agent platform

The obvious alternative is a hosted agent platform where the vendor runs the browser, holds the credentials and shows you a log. That approach removes the Docker socket problem, the loopback publishing question and the network segmentation work entirely, because none of it is yours. What you give up is the ability to read the decision path. With OpenBot, the gateway that decides and records is code in the repository you cloned, and you can change what it does.

A closer comparison is an agent framework such as LangGraph or Mastra on its own. Those give you the agent loop and the tool-calling machinery, and OpenBot depends on exactly that kind of endpoint over AG-UI. What a bare framework does not give you is the per-Bot computer with its own Chromium, logins and workspace, and it does not give you the gateway that resolves, decides and records before acting. If your agents only call APIs you control and you already log those calls, a framework plus your existing logging is less machinery. OpenBot earns its place when the agent drives a browser and a shell, where the actions are hard to enumerate in advance.

One thing OpenBot is not is an RPA tool. The repository is TypeScript, the agents speak AG-UI, and the coworkers are configuration entries in agents.yaml. If you want recorded desktop click sequences, that is a different category of software.

Licence, maintenance and what an upgrade costs you

The licence is MIT, declared in package.json and in the LICENSE file at the repository root. MIT is permissive: you can modify, redistribute and use it commercially, provided the copyright notice and permission notice are preserved. This is not legal advice, and if you plan to redistribute a modified OpenBot inside a product, have someone qualified read the LICENSE file rather than a summary of it.

One licence-adjacent fact matters more than the MIT terms. CopilotKit Intelligence is a separate dependency with its own licence, and the README says a free plan is available and that Intelligence can be self-hosted. Threads live in Intelligence, so your deployment has a second component with its own terms and its own availability. Read those separately.

On maintenance: the last push to main was on 2026-09-10, and the repository is not archived. The README describes the project as alpha and under active development, and warns to expect rough edges and bugs. Because the workspaces are private and nothing is published as a package, upgrading is not a version bump. You pull the repository and reconcile your tenant package under examples/ with whatever changed. The Dockerfile comments give a concrete example of that cost: the Playwright version in the image must stay matched to agent-computer/package.json, and the file says to bump both or neither. Renovate is configured in the repository, which suggests dependency updates are automated upstream, but that does not merge your local edits for you.

Editorial conclusion

Adopt OpenBot if you want to read the governance path before you trust an agent with a browser and a shell, and you are willing to work inside a repository rather than call an API. Do not adopt it as a dependency: package.json is private and the README says nothing here is published as a package. Before handing it real access, verify the gateway's decision path in your own tenant package, confirm that KEY_ENCRYPTION_KEY is not the public example value so production starts, and decide whether AUDIT_RETENTION_DAYS stays unset, because the trail is append-only and that variable is the only way it shrinks.

Frequently asked questions

Official sources

1. CopilotKit/OpenBot on GitHub
2. License: MIT
3. Project website
4. README
5. Releases