Skip to content

Latest commit

 

History

History
196 lines (150 loc) · 10.6 KB

development.md

File metadata and controls

196 lines (150 loc) · 10.6 KB

Development

Setup

Install Docker, Bun 1.4+ (the tests need it), lsof, openssl, and curl. The Intelligence provisioning below also needs npx (Node); scripts/start.sh uses openssl to mint the generated secrets on a first run.

cp .env.example .env
bun install

Connect CopilotKit Intelligence after .env exists. .env.example leaves its two addresses and its key empty. By default they are an Intelligence on this machine, which the CopilotKit CLI installs and connects (a preview for macOS with Docker Desktop):

npx --yes copilotkit@latest login
npx --yes copilotkit@latest local setup
npx --yes copilotkit@latest local connect --approve-connection

local connect writes INTELLIGENCE_API_URL, INTELLIGENCE_GATEWAY_WS_URL and CPK_INTELLIGENCE_API_KEY to .env; each installation has its own ports. For a managed project instead, set INTELLIGENCE_API_URL=https://api.intelligence.copilotkit.ai and INTELLIGENCE_GATEWAY_WS_URL=wss://realtime.intelligence.copilotkit.ai in .env, then:

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

For fresh managed setup, the helper provisions the selected project's key and creates or reuses its openbot Learning container. It writes INTELLIGENCE_API_KEY and CPK_INTELLIGENCE_LEARNING_CONTAINER_ID to .env only after verifying the container. Existing keys and custom targets are preserved. For fresh self-hosted setup, set INTELLIGENCE_API_URL to the deployment's HTTPS API origin and run only bun scripts/setup-learning.ts. Install Chrome or Edge first: the helper opens an isolated browser window for the deployment's usual sign-in, lets you choose an accessible project, and creates or reuses openbot before minting its runtime key. Local development may use a loopback HTTP origin. Existing key-only setups use authenticated Intelligence administration to create a container and assign it in OpenBot Admin. There is no managed license step. Then add OPENAI_API_KEY, or for Anthropic both ANTHROPIC_API_KEY and BOT_PROVIDER=anthropic.

login opens a browser on this machine. With no browser, such as over SSH, use npx --yes copilotkit@latest login --device, which signs in with a code from a browser on any device. project select asks in the terminal; with no terminal to ask in, name the project: npx --yes copilotkit@latest project select --project <slug or id> --json.

The same CLI sign-in also prepares Composio on the first bash scripts/start.sh; bun run setup:composio runs that step alone, independently of Learning. A failure does not stop the start: OpenBot runs with apps unavailable until a retry succeeds. A supplied COMPOSIO_API_KEY, an explicit Arcade selection, or an Arcade-only key is preserved. The helper saves a stable installation UUID privately before any provisioning request, then the CLI saves this installation's Composio project key in .env. Keep .env.openbot-installation-id with the installation when restarting or retrying; new installations generate their own file. A compatible published CLI and enabled hosted provisioning service must be available before adopting this startup flow. See automatic project setup.

Start the stack:

bash scripts/start.sh

Windows (WSL 2)

On Windows, run the clone inside WSL 2 with Ubuntu. This was checked on Windows Server 2022 with Ubuntu 26.04.

  1. Install WSL 2 and Ubuntu with Microsoft's instructions (wsl --install in an administrator PowerShell), and restart Windows when it asks.

  2. In an Ubuntu terminal, install the tools from Setup. A new Ubuntu 26.04 had none of them, and Bun's installer stops without unzip:

    sudo apt-get update
    sudo apt-get install -y ca-certificates curl git lsof openssl unzip nodejs npm
    curl -fsSL https://bun.sh/install | bash
  3. Install Docker Engine and its Compose plugin inside Ubuntu with Docker's Ubuntu instructions, then let your user run it and open a new Ubuntu terminal:

    sudo usermod -aG docker $USER
  4. Clone into your Ubuntu home directory, for example ~/OpenBot, and follow Setup from there. npx --yes copilotkit@latest login opens the sign-in page in your Windows browser.

  5. Keep an Ubuntu terminal open while you use OpenBot. WSL stops Ubuntu shortly after its last terminal closes, and the app, the API server and Docker stop with it.

  6. Open the app from your Windows browser at http://127.0.0.1:3010. WSL forwards the port, and http://localhost:3010 works too.

Running services

Use bash scripts/start.sh for the full local stack. It starts Docker services, starts the API server, which applies its own migrations as it starts and fires routines itself, starts the app, and verifies health routes.

The API server, the computer and the supervisor run from the published OpenBot images, pulled at the one tag in backend-images.env: main on the main branch, the images built from main, and the release's own version (v1.0.3) in a release's checkout, which the release PR pins. start.sh pulls them on every start, so main is current; offline, or with IMAGE_PULL_POLICY=never, it uses the copies already on the machine. An OPENBOT_BACKEND_TAG in the environment or .env runs another build. The app runs from this checkout, with Vite, so a change to it shows as you save; its /api calls go to the server's container on port 3001. The server's log is docker compose logs server. Run Compose by hand with --env-file backend-images.env --env-file .env, so it pulls the same images.

Use bash scripts/stop.sh to take it down: the app, the API server, the Docker services, and each Bot's computer, which the supervisor makes rather than compose and which therefore outlives docker compose down. Pass --keep-computers to leave those browsers signed in. Nothing is deleted either way.

Use bun run dev only when you want the app on its own, against a server that is already running.

Service Port
app 3010
server 3001
agent-computer 4100
agent-langgraph-agui 4201 host / 4206 container
supervisor 4500 host / 4300 container
PostgreSQL 5432

start.sh hands every selected Docker service, the API server included, to docker compose up -d on every run, so one whose configuration or image changed is recreated and an unchanged one is left as it is. It recreates the server when it generated a secret, leaves an app that already answers as OpenBot alone, and reports when a port is held by another process.

The server sweeps staged attachments itself. A file dropped into the composer is stored before the message is sent, and the server deletes the ones never sent once they are older than 24 hours, inside its own process; neither docker-compose.yml nor start.sh starts anything for it. One person may hold thirty-two unsent files across every channel at once, and the refusal on the next one promises they are cleared within a day, which that sweep keeps true. Removing a file in the composer deletes it outright. deployment.md says the same for a real deployment.

Migrations

The database schema and its migrations come with the server image. The server applies them itself when it starts, every run, and a database that is already current is left as it is. There is no migration step in start.sh, which only checks, once the server is up, that the tables are there. docker-compose.yml still defines a migrate and a worker service for one release, for an OpenBot Desktop app from the release before to read, and nothing starts them; a container of either that an earlier start left is removed.

The API spec

The app talks to the server through one API, described in api/: the REST operations in api/openapi.yaml, bundled from one file per area in api/openapi/, and the WebSocket channels in api/asyncapi.yaml. The app's client is generated from the REST spec into app/src/lib/api/generated and checked in. After changing a file under api/openapi/:

bun run api:lint
bun run api:generate

and commit the area file, api/openapi.yaml and the generated client together. CI fails a pull request whose bundle or client is stale, whose spec fails the lint, or whose change breaks a client of the base branch.

Quality checks

Run these before opening a pull request:

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

CI uses bun run test:ci to verify the expected test count in addition to normal tests. It runs the suite in shards, one runner each, and the tests check passes only when every shard passed and their counts add up to the floor in scripts/test-floor.ts. To run one shard the way CI does, pass it to the same script: bun run test:ci --shard=2/4.

bun run test:smoke is separate and needs a deployment that is up, and a session on it:

bash scripts/start.sh
export OPENBOT_SMOKE_COOKIE='better-auth.session_token=...'
bun run test:smoke

It drives one journey over HTTP against the running stack, so it covers the joins the rest of the suite cannot reach: server to supervisor to computer, the gateway deciding before the browser acts, and the audit row landing. Point it elsewhere with OPENBOT_API_URL. Without a deployment it is skipped by bun run test and says what to start when asked for by name.

The session is not optional and not a convenience. Every route the journey proves is behind requireUser, so without one the three tests that act on a computer answer 401 and the run reports a broken deployment when nothing is broken. Take the cookie from a browser already signed in to the deployment under test, from DevTools under Application, Cookies. It is a credential with that person's reach: it belongs in the environment of the run, not in a file or a pull request comment. Asked for without it, the run stops before the first test and names the variable.

Contribution checklist

  • Keep changes focused.
  • Keep credentials, service-account JSON, customer data, and transcripts out of source control.
  • Put sensitive behavior on the server, not only in the browser.
  • Update configuration, architecture, or the root README when behavior changes.
  • Run the quality checks above and include the results in the pull request.