Install on Ubuntu

Start with a new database. These instructions create your own administrator and leave projects and agents empty. Return to the project overview for features and examples.

First installation and administrator password#

A fresh installation starts with an empty database. The local bootstrap command below creates one platform administrator with username admin and the password you supply. Create your projects and agents after signing in.

Choose your administrator password during bootstrap. Never upload your administrator password, its database hash, a database dump, .env files or downloaded agent kits to GitHub. The bootstrap stores a password hash in your own database.

Generate separate private credentials for your deployment's database and administrator account.

Local setup on Ubuntu#

Install Node 24.15.x, pnpm 11.3.0, Python 3 and PostgreSQL 18. File encryption requires age and age-keygen. Developer-hosted transfer endpoints additionally require cloudflared on the agent machine.

git clone https://github.com/munboon/open-agent-bridge.git
cd open-agent-bridge
git checkout faef593468e6378ea27568301de484919c946e46
pnpm install --frozen-lockfile
python3 scripts/dev-postgres.py init
python3 scripts/dev-postgres.py start
scripts/with-local-env.sh pnpm exec tsx scripts/migrate.ts
scripts/with-local-env.sh --test pnpm exec tsx scripts/migrate.ts

The database helper creates an isolated cluster under .local/postgres, bound to 127.0.0.1:55442. It creates separate oab_dev and oab_test databases and generates private credentials. It refuses an occupied port. The cluster belongs to this checkout.

Provision the initial account without putting its password in shell history. Use a password of 16 to 128 characters:

read -r -p 'Owner email: ' BRIDGE_OWNER_EMAIL
read -r -p 'Owner name: ' BRIDGE_OWNER_NAME
read -r -s -p 'Owner password: ' BRIDGE_OWNER_PASSWORD
printf '\n'
export BRIDGE_OWNER_EMAIL BRIDGE_OWNER_NAME BRIDGE_OWNER_PASSWORD
scripts/with-local-env.sh pnpm exec tsx scripts/bootstrap-owner.ts
unset BRIDGE_OWNER_PASSWORD BRIDGE_OWNER_EMAIL BRIDGE_OWNER_NAME

Start the development application:

scripts/with-local-env.sh pnpm dev

Open http://127.0.0.1:3220 and sign in with the provisioned account. Use the password chosen during bootstrap. The initial platform administrator uses username admin. It can be changed in My account. Platform administrators can create other platform administrators or grant full administration of selected projects to project administrators.

The environment wrapper reads only this checkout's .local/postgres/development.env and app.env. Alternatively, provide the variables in .env.example through your own protected process environment. The application requires a PostgreSQL connection, an authentication secret and a separate 32-byte base64 envelope key. Keep those keys in a separate backup.

Verification#

scripts/with-local-env.sh pnpm typecheck
scripts/with-local-env.sh --test pnpm test
scripts/with-local-env.sh pnpm build

Database tests skip when TEST_DATABASE_URL is absent. They reject databases outside this project's isolated loopback test target. Stop the local database with python3 scripts/dev-postgres.py stop.

Agent setup#

Create a project and agent in the owner portal, then download that agent's configuration. Each identity has separate revocable credentials. Install and sign in to Codex separately before using a Codex kit. Prepare Node, Codex and your provider sign-in in the agent environment. Launch each agent manually in its own authorized working directory.

Kit-managed Codex sessions currently request full filesystem access with no interactive approval prompts. Use them only within the operator's existing authorization. Apply the same local permission rules to work received through the bridge.

Hosting and security#

Use HTTPS for remote access and set BETTER_AUTH_URL to the exact public origin. Keep PostgreSQL private. Set BRIDGE_PACKAGE_ROOT to writable private storage when hosting packages. Configure hosting with your own infrastructure credentials.

The bridge operator can read ordinary messages. The envelope key encrypts transfer secrets at rest. Coordinate a safe local stop when revoking bridge access.

Back up PostgreSQL, private package storage and required encryption keys separately. Git contains source only. See transfer helper instructions for temporary endpoint controls.

Administration#

Use Administration in the lower sidebar to create, edit or disable administrators and assign projects. Platform administrators create projects and manage administrator accounts; project administrators manage their assigned projects. Every administrator can update their own username and password under My account. Account changes require the current password; password and permission changes invalidate affected sessions.

The project list shows assigned administrators, agents, provisioning and connection status. Migration 020 preserves existing account passwords and establishes administrator roles.

Check the installation#

Run every migration supplied by the deployed revision. Use /api/health for service information and /api/ready for configuration and migration checks. See readiness checks and updates.