Self-host OpenBot AI coworkers on a VPS
Self-host OpenBot with a supervisor so each AI coworker gets its own container and browser. How the gateway decides every action, and what that costs in RAM.
What you get when you self-host OpenBot AI coworkers
You self-host OpenBot AI coworkers by running one gateway server on hardware you control, plus a supervisor that gives each bot a container of its own. That per-bot container only exists when COMPUTER_SUPERVISOR_URL is set. Without it, every bot shares the one computer at AGENT_COMPUTER_URL. With the supervisor in place, each bot container carries its own Chromium browser and its own workspace volume, with a browser profile that persists between sessions. Every action a bot takes on a computer, a file, an MCP (model context protocol) server or a UI component passes through that gateway, which checks it against a policy before it happens and records it after. If the agent loop that gateway wraps is still unfamiliar territory, the staged path in learning AI agents from scratch has you write a small one yourself before you hand a bot a browser and your logins.
OpenBot is published by CopilotKit under the MIT license at github.com/CopilotKit/openbot. The first tagged release, v0.0.1, was published on 17 August 2026, and v0.2.0 followed on 12 October 2026. As of 10 November 2026 the latest is v1.0.0, published on 9 November 2026, three days after v0.3.0, and the README on main no longer carries a beta notice. Treat it as a serious design with early edges. The deployment below pins v0.2.0, and every step in it describes that release. v0.3.0 changed approvals, browser sharing and the Helm chart defaults, so read the v0.3.0 and v1.0.0 release notes before you start from a newer tag. Current main gives each person a container and gives a bot marked Isolated a container of its own.
The interesting part of that architecture is also the expensive part. A browser for every agent is the memory cost most people forget to plan for, so sizing comes before the install here.
How the gateway decides every action
The API server on port 3001 is the governed path to a bot's computer. The computer also exposes lower-level service endpoints protected by tokens. The project says to keep them private and never use them to bypass the gateway, so the gateway stays the only path only while those endpoints are unreachable. Before a browser action runs, the gateway resolves the target from a page snapshot, evaluates CEL (common expression language) policy rules against the context, writes an audit row holding the decision, and only then calls the container. If execution fails after that, it writes a second row. The docs state the boundary plainly: the computer does not decide policy, the server gateway is the action boundary. That split has a name outside OpenBot, because the loop, the tool definitions, the permission checks and the session state are together the harness wrapped around a model, and this gateway is the permission half of one.
Policy evaluation fails closed, and deny rules are evaluated before allow rules. The failure direction matters more than the rule syntax. A missing or empty policy permits nothing, and a broken rule fails toward blocking whether it is a deny rule or an allow rule, so a mistake in your policy costs you a stuck bot rather than a bot loose on your accounts. The policy OpenBot ships with is a different matter. Its startup default is deny: [] with allow: ["true"], which permits every action until AGENT_COMPUTER_POLICY or a saved administrator policy replaces it, so write your own policy before a bot touches anything real. That layer governs what a bot does and not what it reads, so a page carrying instructions aimed at the agent remains a separate problem, which is the same prompt injection surface you take on when you hand an agent results from your own SearXNG instance.
The audit trail lives in PostgreSQL, so it survives a restart. Control handovers are recorded as computer.help_requested, computer.control_taken and computer.control_released, which is how you see a bot ask for a human and how you see the human give control back. Secrets are recorded as character counts, never as values. File reads, writes and listings show up in the Activity tab, where a saved file appears as its path and size and never its contents. That view is held in the browser and is not the audit record. If you want the same control boundary without a browser behind it, gating AI agent actions behind approvals covers that narrower case.
What one bot costs in RAM and disk
The project publishes measured figures for a single Bot on arm64. Those are the sizing numbers the deployment docs print, and they describe one bot on one architecture, so read them as a starting point rather than a capacity plan.
The data behind this chart
[
{
"label": "Measured, one Bot",
"memory_gb": 0.55,
"disk_gb": 1.4,
"vcpu": 0.06
},
{
"label": "Documented minimum",
"memory_gb": 2,
"disk_gb": 4,
"vcpu": 1
},
{
"label": "Documented recommended",
"memory_gb": 4,
"disk_gb": 8,
"vcpu": 2
}
]Peak memory was measured at 0.55 GB for one Bot, while the documented minimum is 2 GB and the recommendation is 4 GB. The gap between the measurement and the minimum is room for Chromium to grow under load, because a browser's memory use tracks the pages it has open and not the process at rest. The docs put each extra page open at the same time at roughly 100 to 200 MB. Idle CPU is close to nothing, at 0.06 of a core at the top of the measured range, so CPU is not what you are buying. The image is 1.4 GB, against a recommended volume of 8 GB, and the difference is room for /workspace, where the bot keeps its files. The image carries only the Chromium family of browsers. Playwright's Firefox and WebKit are kept out of it.
None of that tells you what several bots cost together, and the project publishes no figure for that. A documented minimum is the number a project is comfortable printing rather than one anyone watched under load, which is also why choosing between PhotoPrism and Immich comes down to their measured RAM floors instead of their published ones. Measure your own. Start one bot, give it a real task with a page open, and watch the container while it works.
docker stats --no-stream
free -mTake the MEM USAGE column for the bot's container as your per-bot figure, add the gateway and PostgreSQL on top, then multiply the per-bot figure by the number of bots you expect to exist at the same time. An idle bot keeps its browser until the idle timeout closes it, 30 minutes by default, so include idle browsers in the multiplier. The arithmetic is the same one used for sizing RAM and CPU for a coding agent VPS, and the browser side of it is covered in running a headless browser for agents on a VPS.
One Chromium detail affects small plans. OpenBot launches Chromium with --disable-dev-shm-usage, so the browser writes to /tmp instead of /dev/shm. That avoids the crash you get on hosts with a small /dev/shm, and it moves the pressure onto your root filesystem, which is one more reason the recommended disk is larger than the image.
How do you self-host OpenBot on a VPS?
You need Docker, Bun 1.3 or newer, a CopilotKit Intelligence project and license, and access to a model, either an API key or a supported provider sign-in in its place. The v0.2.0 README asks for Bun 1.3+ for the app and API server; current main raises that to 1.4+, so read the README of the tag you clone. A provider's own sign-in has been able to stand in for an API key since v0.0.15. The development docs also expect lsof, openssl and curl on the box, plus npx from Node for provisioning Intelligence. Clone a tagged release rather than main, because main on a project this young changes without warning. If you already run a v0.1.x install, read the v0.2.0 release notes before you move to it: the upgrade copies stored Composio connections into a new table, and rolling back to v0.1.2 afterwards hides any account connected after the upgrade.
git clone --branch v0.2.0 https://github.com/CopilotKit/openbot.git
cd openbot
cp .env.example .env
bun installProvision the Intelligence project. The first two commands sign you in and select the project. The helper script then provisions that project's runtime key, creates or reuses its openbot Learning container, and writes both settings into your environment file.
npx --yes copilotkit@latest login
npx --yes copilotkit@latest project select
bun scripts/setup-learning.tsGenerate the key that encrypts stored credentials, and put the output in .env as KEY_ENCRYPTION_KEY. Add your OPENAI_API_KEY in the same file. The proof-of-concept Bot uses OpenAI. For the LangGraph Bot you can set BOT_PROVIDER to anthropic or google and add the matching key. To use a model sign-in instead of a key, the v0.2.0 .env.example takes CLAUDE_CODE_OAUTH_TOKEN, the token from claude setup-token, and CHATGPT_AUTH_FILE, the file a signed-in ChatGPT plan writes. The API server reads them for its built-in agents, and compose passes them to the Bot harness you picked.
openssl rand -base64 32While .env is open, look at the computer settings. .env.example leaves COMPUTER_SUPERVISOR_URL and SUPERVISOR_TOKEN empty and points AGENT_COMPUTER_URL at the one shared computer on port 4100. The compose file includes the supervisor, and scripts/start.sh enables per-bot computers by default by supplying COMPUTER_SUPERVISOR_URL and SUPERVISOR_TOKEN to the server. If you launch the server yourself, set both values; without a supervisor URL, every bot shares that one browser and its logins.
Then start.
bash scripts/start.shscripts/start.sh brings up the Docker services, runs the database migrations, starts the server, the routine worker and the app, and checks their health. When it finishes, the app answers on port 3010 and the API on port 3001. The script reports port conflicts and leaves an already-running matching service alone, so running it twice is safe.
Check it from the server itself before you expose anything.
curl -sS -o /dev/null -w '%{http_code}\n' http://127.0.0.1:3010
ss -ltnp | grep -E ':(3010|3001|4100|4500|5432)'A 200 from the first command means the app is serving. The second command shows which addresses those ports are bound to, and that is the answer that matters on a VPS. A line reading 127.0.0.1:3001 is private to the box. A line reading 0.0.0.0:3001 means anyone who can route to the server can reach it.
The single container image
The deployment docs also ship a single image holding the app, the API and Chromium, served on port 3001. It is published as ghcr.io/copilotkit/openbot with version tags, or you can build it from your clone.
docker build -t openbot .
docker run -p 127.0.0.1:3001:3001 --env-file .env \
-e EMBEDDED_POSTGRES=on -v openbot-data:/var/lib/postgresql openbotEMBEDDED_POSTGRES=on runs PostgreSQL inside the container and applies migrations at startup. The named volume keeps the audit history across a redeploy, and without it every rebuild throws that history away. Mount it at the parent directory, /var/lib/postgresql, and not at the data directory itself. The docs warn that mounting the data directory can leave the cluster uninitialized, and the app then answers with a 502. If you point DATABASE_URL at a managed database instead, the vector extension has to be enabled on it. Managed services such as RDS, Cloud SQL and Azure Database support the extension, and none of them enable it for you. The migrations also expect the role that runs them to own the extension, so if the extension was created under a different role they stop with must be owner of extension vector.
Run migrations as a release step when the database is external.
docker run --rm --env-file .env --entrypoint sh openbot \
-c "cd /app/server && bun scripts/migrate.ts"Use scripts/migrate.ts and not drizzle-kit migrate, because the drizzle-kit CLI is a development dependency that is not in the production image. Keep --entrypoint sh, because without it the API starts before the migrations run.
That image deliberately leaves the browser port unpublished. It also leaves out the supervisor, because the supervisor needs the Docker socket, which serverless platforms do not offer. Without the supervisor, every bot shares one browser and therefore one set of logins, which removes the isolation that made per-bot containers worth running. This single-container path is the one that never gives a bot a container of its own. If separate logins per bot is why you are here, run the compose stack with COMPUTER_SUPERVISOR_URL and SUPERVISOR_TOKEN set, on a host where you accept the trade. A process that can talk to the Docker socket can start a privileged container, so it is root on the host in practice. That is a good reason to keep OpenBot on a machine of its own, in the same spirit as giving coding agents a disposable VM.
Why OPENBOT_SINGLE_USER is a laptop setting
.env.example ships with OPENBOT_SINGLE_USER=true. That setting admits every request as one fixed administrator and skips sign-in entirely. On a laptop it is a convenience, because the only client that can reach the port is you. On a VPS it means anyone who reaches port 3010 is that administrator, on a system that stores encrypted credentials and drives a browser already signed into your accounts.
The server now guards part of this. If OPENBOT_SINGLE_USER=true is set and an OPENBOT_PUBLIC_URL, OPENBOT_APP_URL or TRUSTED_ORIGINS entry is publicly routed, the server refuses to start and names the address. A private address starts with a warning. That check reads the URLs in your configuration, not the interfaces Docker publishes on, so the default localhost values pass it even when a port is open to the internet. Binding is still your job.
There are two honest ways to run it. Keep OPENBOT_SINGLE_USER=true, bind every port to 127.0.0.1, and reach the app over an SSH tunnel or a private network interface only.
ssh -N -L 3010:127.0.0.1:3010 -L 3001:127.0.0.1:3001 you@your-vpsThe app is then at http://localhost:3010 in your own browser. Chrome and Firefox treat that address as a secure context and keep Secure sign-in cookies set over it. Safari is the exception: it also reports localhost as a secure context, but as of 10 November 2026 it still refuses to store a Secure cookie set over plain http://localhost, a WebKit bug that remains open, so open the tunnel in Chrome or Firefox, or put TLS in front. The live screen itself does not need a secure context: the deployment docs say the app does not depend on any of the browser APIs that plain http:// takes away. The other way is to turn single-user mode off and configure a real identity provider. Google, Microsoft Entra, Okta, SAML and OIDC are supported. Google, Entra and Okta are set in the environment, while SAML and OIDC providers are registered under Admin, Identity providers, once the deployment is running. Any provider also needs BETTER_AUTH_SECRET at 32 characters or more, BETTER_AUTH_URL set to the public API base URL for OAuth callbacks, and INITIAL_ADMIN_EMAILS. TRUSTED_ORIGINS is not on that required list, but it holds the app origins the API accepts, plus every host in a registered OIDC provider's discovery document, and OPENBOT_APP_URL defaults to its first entry, so set it to your public app origin. Provider credentials must be complete, because a half-configured provider stops startup instead of falling back to open access. If the reason you are adding accounts is that each person on the team wants an agent of their own rather than a browser of their own, OneCLI is built around that shape from the start, with one sandboxed agent per person and the model keys held in a single gateway.
If the app is reachable on a public name, put TLS (transport layer security) in front of it. A page served over plain http:// on anything but localhost is not a secure context, so cookies marked Secure are not stored and sign-in fails in a way that looks like a bug in OpenBot.
Firewall the lower-level ports
OpenBot's own security note says the lower-level service endpoints are protected by tokens, that you should keep them private, and that you should not use them to bypass the gateway. Tokens are the second protection. The first is that the port cannot be reached at all.
The agent-computer listens on 4100 and requires COMPUTER_TOKEN. The bot endpoints listen on 4200 and 4201, and the agent harness listens on 4202. The supervisor listens on 4500 on the host and 4300 inside its container, and the compose file binds it to 127.0.0.1:4500. PostgreSQL listens on 5432. None of those belong on a public interface, and on a single-user deployment neither do the app and the API.
sudo ufw default deny incoming
sudo ufw default allow outgoing
sudo ufw allow 22/tcp
sudo ufw enable
sudo ufw status verboseThere is a trap here that catches people who assume the firewall is enough. Publishing a container port with -p 3001:3001 makes Docker install a DNAT rule, so that traffic is handled in the FORWARD path and never passes through the INPUT chain that ufw's default deny governs. The port stays open while ufw status still prints Status: active. Bind the published port to loopback in the mapping itself, as -p 127.0.0.1:3001:3001, or set the host address in your compose file. Verify with ss -ltnp, not with ufw status. Nothing about that trap is specific to OpenBot, so run the same check against every other container you have published on the box, including whatever is serving a Jellyfin library rebuilt as a 90s video store.
OpenBot can run offline with self-hosted Intelligence
State this before you plan the deployment. OpenBot depends on a CopilotKit Intelligence project, which holds durable threads and conversation memory on the hosted service or your own infrastructure. The pinned v0.2.0 server validates INTELLIGENCE_API_URL, INTELLIGENCE_GATEWAY_WS_URL and INTELLIGENCE_API_KEY at startup. It checks the three as a set and refuses to start if any is missing. COPILOTKIT_LICENSE_TOKEN is optional, and only a self-hosted Intelligence with its own license uses it. As of 10 November 2026, free hosted Intelligence includes 1,000 interactions per organization each month, but since v0.1.0 OpenBot shows a self-hosting banner unless the deployment has a paid Intelligence plan or sets OPENBOT_SELF_HOST_BANNER=false. Intelligence is itself self-hostable, so a fully local deployment is possible with more work than the quickstart shows. Offline production deployment requires Annual; self-hosted pay as you go must connect to report usage for billing. The free Developer Edition supports local non-production evaluation with a renewable 30-day license; installation and renewal need internet access. The local Intelligence CLI writes its key as CPK_INTELLIGENCE_API_KEY, while the pinned v0.2.0 release reads only INTELLIGENCE_API_KEY, so copy the value across for this release. Current main accepts the CLI key directly and gives it precedence.
The model is the second dependency. Nothing ships in the box. BOT_PROVIDER accepts openai, anthropic or google for the LangGraph Bot, and OPENAI_BASE_URL points the OpenAI path at any compatible endpoint, which is where running Ollama on a VPS to self-host an LLM fits if you want the tokens to stay on your own hardware. Browser control asks a lot of a model, so test a local model on a real task before you commit to it.
Scaling past one replica
The gateway resolves element references against a page snapshot. That snapshot now lives in PostgreSQL, so a second replica can act on a snapshot the first one took. The official Helm chart runs two API replicas by default and keeps everything a replica has to survive in PostgreSQL. It also disables the embedded computer and refuses to install one alongside more than one replica. A browser inside the API pod would hold one bot's logins, and scaling the API would multiply them. The single image is the case to watch, because each replica carries its own browser, so a bot's logins stay on whichever instance served them. On one VPS every bot's browser still runs on the same host, so you grow it by making the box bigger. Isolation between bots still comes from the per-bot containers, in the same way self-hosted agent sandboxes keep one agent's mistakes away from the others.
Failure modes and what you will see
Startup exits immediately after you fill in .env. The server validates configuration before it serves anything. Each of these stops startup rather than degrading quietly: a partial Intelligence block, a missing KEY_ENCRYPTION_KEY, an OAuth provider with a client ID and no secret, or single-user mode alongside a public URL. Read the first error, fix that one field, start again.
Migrations fail on a managed database. There are two likely causes. The vector extension may not be enabled and the migrating role cannot create it, so the migration hits a column type PostgreSQL does not know. Or the extension was created under another role, and the migration stops with must be owner of extension vector. Create the extension as the role that runs the migrations, then rerun the migration step.
The app loads but sign-in never sticks. You are serving over plain http:// on a public address, which is not a secure context, so the Secure cookie is discarded. Put TLS in front, or use the SSH tunnel so the browser sees localhost. Over the tunnel, use Chrome or Firefox, because Safari still drops Secure cookies set over plain http://localhost.
Bots share logins you expected to be separate. The supervisor is not in use, so there is no per-bot computer and every bot uses the shared browser at AGENT_COMPUTER_URL. Confirm COMPUTER_SUPERVISOR_URL is set and that the supervisor can reach the Docker socket.
A bot stops and asks for help. That is the design working. The audit trail records computer.help_requested, you take control on the live screen, and the handover is recorded on both sides.
FAQ
Is OPENBOT_SINGLE_USER safe to leave on for a VPS deployment?
Only when the gateway cannot be reached from the internet. OPENBOT_SINGLE_USER=true admits every request as one fixed administrator with no sign-in, so anyone who can open the port owns the deployment, its stored credentials and its signed-in browser. In this mode the server refuses to start when a configured public URL or trusted origin is publicly routed, but that check cannot see how your ports are published. It is acceptable when every port is bound to 127.0.0.1 and you reach the app through an SSH tunnel or a private network interface. On a public interface, turn it off and configure Google, Microsoft Entra, Okta or OIDC together with BETTER_AUTH_SECRET, BETTER_AUTH_URL and INITIAL_ADMIN_EMAILS, and set TRUSTED_ORIGINS to your public app origin.
How much RAM does one OpenBot bot need?
The project's published figures for a single Bot on arm64 put peak memory at 0.55 GB, with 2 GB as the documented minimum and 4 GB recommended. There is no published figure for several bots at once, because each one holds a Chromium of its own. Run one bot on a real task, read that container's memory in docker stats, add the gateway and the database, then multiply by the number of bots you expect to exist at the same time.
Do I need a CopilotKit account to self-host OpenBot?
Yes. OpenBot depends on a CopilotKit Intelligence project for durable threads and memory, and the pinned v0.2.0 server refuses to start unless the Intelligence API URL, the gateway WebSocket URL and the API key are all set. A free hosted plan is available as of 10 November 2026, and offline production deployment is supported with self-hosted Intelligence on Annual and a local model. You also bring your own model access, a model API key or a supported provider sign-in in its place, because no model ships with OpenBot.
Why does each bot get its own browser instead of sharing one?
Because a browser profile is an identity. A shared browser means shared cookies and shared sessions, so one bot signed into an account is every bot signed into that account. Per-bot containers give each coworker its own profile and its own logins, but only when COMPUTER_SUPERVISOR_URL points the server at the supervisor. Without it, every bot shares one browser. The cost is memory, since a Chromium per bot is the largest single item in the sizing.
Which OpenBot ports should be open on the firewall?
None of the lower-level ones. The agent-computer on 4100, the bot endpoints on 4200 and 4201, the agent harness on 4202, the supervisor on 4500 and PostgreSQL on 5432 all stay private. The project protects them with tokens and asks that you keep them unreachable anyway. Publish only what a person needs to open, and remember that a container port published with -p 3001:3001 is reachable regardless of a ufw default-deny rule, because Docker's DNAT rule puts that traffic in the FORWARD path instead of INPUT.