OpenBot

A template, not a product. OpenBot is meant to be cloned and made your own. There is no hosted version to sign up for, and nothing here is published as a package to depend on: every workspace in this repository is private. You take the repository, replace the example tenant package under examples/ with your own coworkers, channels and skills, and run it. Everything below describes a starting point, not a finished thing somebody operates for you.

Alpha, and under active development. OpenBot is early. Expect rough edges and bugs, and expect things to move. Issues and pull requests are welcome.

Runs on your machine. Everything below is written for a laptop. .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.

Do not want to build it yourself? We will. Our engineers will stand OpenBot up inside your infrastructure, customize it into something that looks like your own product, and hand it back to you to keep changing. Start the conversation.

An agent platform that runs inside your own infrastructure. Docker Compose brings up every part of it, the data sits in your PostgreSQL, and the model is yours to choose: no model ships in the box, and an administrator supplies the credential, which is encrypted at rest and never logged.

Thirteen coworkers ship in the example package, and they are configuration rather than code: General Assistant for everyday work and Knowledge for company questions, a Risk Analyst reached as an endpoint, and ten in examples/fintech/agents/ that each do one job — reading an expense claim against the policy as written, turning a meeting note into the follow-ups actually in it, drafting release notes from what shipped, triaging a ticket, answering a new starter from the handbook, writing a brief that names what it could not find, writing up an interview, handing an on-call shift over, assembling what is known before a renewal, and grouping customer feedback into themes it can cite. Add your own by dropping a file in that directory, by editing agents.yaml, or from /agents in the UI.

Anything a Bot does to a computer, a file, an MCP server or a component goes through one gateway that decides and records it. That is the difference between an agent that can use your tools and an agent you can let near them.

More at copilotkit.ai/openbot.

A Bot is any endpoint speaking AG-UI, the open protocol for agent-to-user interaction, so OpenBot is not tied to a framework and neither are you. Agents built with LangGraph, Mastra, CrewAI, Pydantic AI, Google ADK or written by hand all arrive the same way, and the governance rides the protocol rather than the framework.

• Docker, for PostgreSQL and the shipped Bots.
• Bun 1.3+, for the app and API server.
• A CopilotKit Intelligence project and license. A free plan is available, and Intelligence can be self-hosted.
• A model key. The proof-of-concept Bot uses OpenAI; the LangGraph Bot can use OpenAI, Anthropic, or Google.

Setting up with an AI assistant? Paste prompt.txt into it first. It carries the same steps as below plus the things that are easy to get wrong: which of the ten blank keys in .env.example are actually yours to fill (three), which the start script generates for you, and what each start-up refusal means. Every claim in it is checked against this repository.

1. Create .env:

   cp .env.example .env
   bun install

2. Connect a fresh managed Intelligence project:

   npx --yes copilotkit@latest login
   npx --yes copilotkit@latest project select
   bun scripts/setup-learning.ts

   The helper provisions the selected project's runtime key, creates or reuses its openbot Learning container, then writes both settings to .env. It preserves custom container assignments and refuses to replace an existing OpenBot key. For fresh self-hosted setup, set INTELLIGENCE_API_URL to that deployment's HTTPS API origin and run the helper without the two npx commands. It opens an isolated Chrome or Edge window for your usual sign-in and project choice; install either browser first. Existing key-only setups can assign a container through Admin → Automatic Learning. Managed Intelligence needs no separate licence token.

3. Fill the remaining required values:

   • OPENAI_API_KEY

   Keep the managed Intelligence URLs from .env.example unless you run Intelligence yourself. The example KEY_ENCRYPTION_KEY is public and fine locally; generate your own with:

   openssl rand -base64 32

4. Run:

   bash scripts/start.sh

5. Open http://localhost:3010.

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.

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.

One image carries the app, the API, the browser the Bots drive, and optionally PostgreSQL. Same .env, no Kubernetes.

# The published image. Nothing to clone and nothing to build.
docker run -p 3001:3001 --env-file .env \
  -e EMBEDDED_POSTGRES=on -v openbot-data:/var/lib/postgresql \
  ghcr.io/copilotkit/openbot:latest

# Or the tree you have in front of you.
docker build -t openbot .
docker run -p 3001:3001 --env-file .env \
  -e EMBEDDED_POSTGRES=on -v openbot-data:/var/lib/postgresql openbot

Everything is on 3001 here, the app included, rather than the 3010 the clone uses. latest is the most recent release and a version tag such as :v0.0.9 pins one.

Leave EMBEDDED_POSTGRES off and set DATABASE_URL to point at a database you already run. docs/deployment.md has the minimum sizes, the platform notes, and how it behaves behind more than one replica.

• Open /bot and ask: Open news.ycombinator.com and tell me the top story.
• Ask the Bot to fill out https://httpbin.org/forms/post, then inspect /admin/audit.
• Open /admin/boundaries, add a deny rule or preset, and retry the same browser action.
• Create a coworker from /agents, give it a standing role, and start a channel with it.

• A computer per Bot: the supervisor gives each Bot its own container, its own /workspace volume and its own browser profile. Set COMPUTER_RUNTIME=runsc to run them under gVisor where the host supports it.
• A shell, not just a browser: a Bot can run a command in its workspace, install what it needs, and process a file it saved. Through the same gate as everything else, so a rule can refuse a shell outright or refuse particular commands, and the command is on the record either way. The command inherits PATH, locale, terminal and proxy variables, not the rest of the deployment's environment.
• The gateway is the only way in: it resolves the target from a server-held snapshot, evaluates the policy, writes the audit row, and only then calls the computer. There is no path that acts without the record existing first.
• CEL policy, fail closed: rules can inspect tool.name, intent, bot.id, actor.id, page.url, page.host, element.*, key, command, file.*, mcp.* and initiator.* (what started the run, so a rule can refuse a scheduled routine what it would allow a person). Deny is evaluated before allow, a missing policy permits nothing, and a broken rule refuses rather than opens.
• Watch what it is doing: the screen shows what a Bot is looking at, and the Activity tab beside it shows what it ran, read and saved, with the output. A command line in the transcript opens to the same thing. A saved file shows its path and size, never its contents.
• Take the wheel: a Bot that hits a login wall or a 2FA prompt asks for help. Control is handed over in the same panel and recorded as computer.help_requested, computer.control_taken and computer.control_released. While a person is driving, Bot actions are refused rather than queued.
• Secrets never enter the transcript: the trail records that a secret was requested and how long it was, not what it said.
• Bring your own agent: any AG-UI endpoint is a Bot, on a framework or hand-written. Endpoints are validated with the same target checks used for browser navigation, and an auth header is stored write-only.
• Components instead of prose: compiled React components live in app/src/components/gallery/, sandboxed ones are authored in /admin/playground and published with no deployment. Every call asks the server whether the component exists, is published, and is not withheld from that Bot. Data functions are granted per component.
• Governed MCP: Google Drive and Notion ship in the catalogue, and Composio brokers a few hundred more apps behind one account, each reached as the person asking. The catalogue carries only vendors this deployment stands behind, so adding one is a review of that vendor. Custom servers must pass URL checks; unknown tools and custom-server tools are treated as writes, and a catalogue tool the server advertises but does not name as a write classifies as a read. A Bot is told which connectors exist here and which it holds, so it says it has not been granted one rather than browsing to the vendor's website.
• Skills are instructions, not capabilities: personal skills attach only to Bots their author owns, deployment skills are admin-owned, and both are invoked with / in the composer. A Bot granted the shipped skill-creator skill can write one with you in the conversation, and saves it only when you press the button on the card.
• Sign in with what your company already has: Google, Microsoft or Okta from the environment, or a company's own SAML or OpenID Connect provider registered while the deployment runs and routed by email domain. Any one turns sign-in on; several may be configured at once.
• Decide who gets in: /admin/people lists everybody who has signed in, promotes and demotes them, and removes access, which ends the session they are using and stops the next sign-in. Every change is on the audit trail.
• An audit trail you can read: /admin/audit lists what was permitted, what was refused and what failed, and every refusal carries the rule that caused it.
• Credentials encrypted at rest: stored through /admin/credentials, never returned by an API, and redacted from audit events.
• Loopback by default: computers bind to 127.0.0.1 and require a per-container token, so nothing reaches a logged-in browser by knowing its port. The supervisor binds there too, because it holds the Docker socket and its token is a shared secret rather than a network boundary.
• Durable threads and memory: conversations survive restarts through CopilotKit Intelligence, and each deployment stamps the threads it owns.
• Routines: ask a Bot to do something on a schedule and it does, running as you, in the channel you asked in. A 15-minute floor and a cap of 20 enabled routines keep a sentence from scheduling more than a person meant, and ten failures in a row switch a routine off rather than burn model spend forever. Needs a worker process; see docs/routines.md.

Any AG-UI endpoint can be a Bot.

From /agents, create a coworker with:

• name, title, and role description;
• private or public visibility;
• optional AG-UI endpoint;
• optional write-only authorization header.

The server validates agent endpoints with the same target checks used for browser navigation, at registration and again on every redirect the endpoint answers with. If no custom endpoint is set, product-created coworkers use MANAGED_AGENT_AG_UI_URL when it is configured, and are refused when it is not.

A private address is refused unless it is listed in AGENT_ENDPOINT_ALLOWED_HOSTS:

AGENT_ENDPOINT_ALLOWED_HOSTS=agents.internal,10.0.0.42:9000

A host on its own covers any port on that host; a host with a port pins that port. Matching is exact: no wildcards, no suffixes. An entry written as a URL, or containing *, stops startup and names that entry.

The list covers agent endpoints only. Browsing is unaffected, the addresses holding a deployment's own cloud credentials are refused whatever is listed, and listing an address permits registering an agent there rather than granting that agent anything.

Tenant package agents are declared in agents.yaml as either:

• built-in, with a system prompt; or
• remote-ag-ui, with an endpoint.

See docs/configuration.md and docs/coworkers.md.

.env.example is the source template. The API server refuses to start without:

• DATABASE_URL
• KEY_ENCRYPTION_KEY
• INTELLIGENCE_API_URL
• INTELLIGENCE_GATEWAY_WS_URL
• INTELLIGENCE_API_KEY

COPILOTKIT_LICENSE_TOKEN is optional. A self-hosted Intelligence with its own licence can still set it and it is forwarded to the runtime; managed Intelligence does not issue one and startup no longer asks for it.

Settings worth knowing:

Full reference: docs/configuration.md.

The server gateway is the product/API path for Bot browser and file tool calls. It resolves the target, evaluates policy, writes an audit row, and then calls agent-computer. The computer also exposes lower-level token-protected service endpoints; keep them private and do not use them to bypass the gateway.

More detail: docs/architecture.md.

.env.example ships OPENBOT_SINGLE_USER=true, which is one administrator and no sign-in: how a fresh clone reaches the product without registering an OAuth client first. Delete that line and configure any one of Google, Microsoft or Okta before anybody else can reach the deployment. With neither, it refuses to start rather than admitting everybody as an administrator. Configure more than one provider and the sign-in screen offers each of them.

These four are needed whichever you pick:

BETTER_AUTH_URL=http://localhost:3001        # where OAuth callbacks come back to
BETTER_AUTH_SECRET=                          # openssl rand -base64 32
TRUSTED_ORIGINS=http://localhost:3010        # where the app is served from
INITIAL_ADMIN_EMAILS=you@example.com         # comma separated

Then the provider. Register the redirect URI shown beside it.

# Google — http://localhost:3001/api/auth/callback/google
GOOGLE_OAUTH_CLIENT_ID=
GOOGLE_OAUTH_CLIENT_SECRET=

# Microsoft — http://localhost:3001/api/auth/callback/microsoft
MICROSOFT_OAUTH_CLIENT_ID=
MICROSOFT_OAUTH_CLIENT_SECRET=
MICROSOFT_OAUTH_TENANT_ID=common             # your directory GUID for staff only

# Okta — http://localhost:3001/api/auth/callback/okta
OKTA_OAUTH_CLIENT_ID=
OKTA_OAUTH_CLIENT_SECRET=
OKTA_OAUTH_ISSUER=https://example.okta.com/oauth2/default

Restart. Accounts, sessions and roles are stored in the same PostgreSQL database as everything else.

A company's own SAML or OpenID Connect provider is registered while the deployment runs, under Admin → Identity providers, and routed by email domain. An OIDC registration needs every host in the provider's discovery document listed in TRUSTED_ORIGINS, not only the issuer.

• INITIAL_ADMIN_EMAILS is required, because nothing else grants the administrator role and no screen can promote somebody afterwards. It is re-read on every sign-in, so editing it takes effect the next time that person signs in.
• MICROSOFT_OAUTH_TENANT_ID defaults to common, which admits personal Microsoft accounts as well as work ones. On a multi-tenant app registration Entra may send no email claim at all, so OpenBot falls back to upn and then preferred_username. If none of the three arrives the sign-in is refused and the reason is logged: add email as an optional claim, or use your directory GUID here.
• A half-configured provider is refused at start-up rather than at somebody's first attempt to sign in: a client id with no secret, a secret shorter than 32 characters, or an Okta issuer with no credentials behind it.
• SAML and OIDC are registered while the deployment runs rather than configured here. Sign in as an administrator and go to Admin → Identity providers with the metadata your identity team gave you. People then sign in by typing their email address, and the domain decides which provider they are sent to.
• Put TLS in front of any deployment. A page served over plain http:// on anything but localhost is not a secure context, and sign-in cookies want Secure.

For an employee desktop, provision an OpenBot authority using the Google, Microsoft or Okta settings above (your Kubernetes OpenBot can serve this role). Set Organization OpenBot URL in the desktop connection screen, or OPENBOT_ORGANIZATION_AUTH_URL=https://openbot.company.example in its public configuration. Use an HTTPS origin; HTTP is accepted only on loopback for local tests. Provider client secrets stay on that authority. Template and white-label deployments can supply the same setting without changing their Intelligence endpoint.

This optional URL is separate from INTELLIGENCE_API_URL, INTELLIGENCE_GATEWAY_WS_URL and INTELLIGENCE_API_KEY. Local, managed and customer-hosted Intelligence all retain their project credential. A Google ID token is not an Intelligence project key. Leave the organization URL empty for a standalone desktop.

Desktop sign-in uses the system browser and Better Auth's single-use PKCE exchange. The authority verifies the employee and current role; organization mode never substitutes dev@openbot.local. Employees do not need project-key administration privileges. Installation happens once: reopening or refreshing an expired organization, Intelligence or model connection preserves the installed runtime and data and opens the relevant connection screen.

• agent-computer drives a browser holding real logins. docker-compose.yml binds it to loopback; leave it there.
• Store credentials through /admin/credentials, which encrypts them. Do not put credential values in tenant YAML or in committed files.
• AGENT_COMPUTER_ALLOW_PRIVATE_HOSTS lets a Bot reach services on this machine. It ships commented out in .env.example, is for a laptop only, and a deployment running with NODE_ENV=production refuses to start while it is set.
• To reach an agent on your own network from a deployment, list its address in AGENT_ENDPOINT_ALLOWED_HOSTS instead. That permits the one address, where the switch above permits the network.

bun run format:check
bun run lint
bun run typecheck
bun run test
bun run build

After changing the Drizzle schema:

bun run --filter server db:generate
bun run --filter server db:migrate

Use bash scripts/start.sh for the whole stack and bash scripts/stop.sh to take it down. Use bun run dev only when you want the app and server without the Docker Bots and computers.

• copilotkit.ai/openbot
• docs/README.md
• docs/architecture.md
• docs/configuration.md
• docs/development.md
• docs/coworkers.md
• docs/deployment.md
• docs/releasing.md

• Open an issue or coordinate before starting substantial work.
• Keep changes focused and update docs when setup, configuration, architecture, or user behavior changes.
• Keep secrets, service-account JSON, customer data, and local transcripts out of the repository.
• Run the checks in Development before opening a pull request.

MIT © CopilotKit