OpenBot/prompt.txt at main · CopilotKit/OpenBot · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
You are helping somebody set up OpenBot on their own machine.

Read this whole file before running anything. Every claim in it was checked against the code in
this repository; if something here disagrees with what you see, trust the repository and say so.

ASK THIS BEFORE YOU DO ANYTHING ELSE

There are two ways to have OpenBot and they are different jobs. Ask which one they want:

  A. They want to run it. One container, one command, nothing cloned and nothing built. The image
     carries the app, the API, Chromium, and its own PostgreSQL if asked.
  B. They want to make it theirs. The clone, run from source, with the Bots, channels and skills as
     configuration they edit. That is the rest of this file.

"I want to try OpenBot" is A. Go to B only if they mean to change something: their own Bots, their
own channels, their own skills, or the code. Somebody who wanted A and was walked through B has
installed a toolchain and a container engine to see a screen that one command would have shown them.

A. A LOCAL COPY, FROM THE PUBLISHED IMAGE

  docker run -p 3001:3001 --env-file .env \
    -e EMBEDDED_POSTGRES=on -v openbot-data:/var/lib/postgresql \
    ghcr.io/copilotkit/openbot:latest

One port. The app is on 3001 as well, so open http://localhost:3001, not 3010. `latest` is the most
recent release; a version tag such as `:v0.0.9` pins one.

The `.env` still carries the same values as B: INTELLIGENCE_API_KEY, a model key, a real
KEY_ENCRYPTION_KEY, and either an identity provider or OPENBOT_SINGLE_USER=true. Start from
`.env.example` in this repository, or write the handful by hand. `EMBEDDED_POSTGRES=on` runs
PostgreSQL inside the container, creates the database and the `vector` extension the first time, and
applies the migrations on every start, so there is nothing to provision and no password to manage.
Point DATABASE_URL at a database you already run instead, and leave EMBEDDED_POSTGRES off, if you
would rather. That database needs the `vector` extension enabled; the managed ones support it and
none of them enable it for you.

Mount the volume at `/var/lib/postgresql`, the parent, not `/var/lib/postgresql/data`. `initdb` will
not initialise into a directory that holds anything, and an ext4 volume arrives holding
`lost+found`, so mounting the data directory itself leaves the cluster uncreated and the container
serving nothing.

WHAT THIS IMAGE DOES NOT CARRY: `agent-langgraph` and `agent-bot`, the two framework Bots, are
separate images that `docker-compose.yml` starts. Leave MANAGED_AGENT_AG_UI_URL unset and the
shipped Risk Analyst coworker is omitted rather than registered against a host that is not there. If
their `.env` still has the laptop default `http://localhost:4201/ag-ui`, unset it. Somebody who
wants those Bots wants B.

docs/deployment.md is the whole of this path, including the managed-database version, the sizing and
the platform notes.

B. MAKE IT THEIRS, FROM THE CLONE

OpenBot is a template to clone and make your own, not a product with a hosted version. It runs on
the person's machine: their PostgreSQL, their model credential, their Bots.

WHAT THEY NEED BEFORE STARTING
- Bun 1.3.14. The repository pins it (`packageManager` in package.json).
- Docker, running. `scripts/start.sh` brings up PostgreSQL with `docker compose`.
- Node, for `npx`, to fetch the CopilotKit credentials below.
- A CopilotKit account. Free is enough.
- A model credential. `OPENAI_API_KEY` is the default; any OpenAI-compatible base URL works via
  `OPENAI_BASE_URL`.

THE ONLY TWO VALUES A PERSON HAS TO SUPPLY
`.env.example` ships ten empty keys, which makes this look bigger than it is. `scripts/start.sh`
fills most of them itself: it defaults COMPUTER_TOKEN and WORKER_SHARED_SECRET, and generates
AGENT_TOOL_TOKEN and writes it back into `.env`. What it cannot invent is:

  1. INTELLIGENCE_API_KEY        the `cpk-...` runtime key
  2. OPENAI_API_KEY              the model credential

Everything else in `.env.example` is either already correct or generated. Do not talk the person
through the other eight.

THE STEPS

  cp .env.example .env

  npx --yes copilotkit@latest login           # opens a browser
  npx --yes copilotkit@latest project select  # prints the cpk-... runtime key

There is no licence step. `copilotkit license` still exists for a self-hosted Intelligence, and
COPILOTKIT_LICENSE_TOKEN is honoured when set, but managed Intelligence needs only the cpk- key.

Put the `cpk-...` key in `.env` as INTELLIGENCE_API_KEY. Put their model key in OPENAI_API_KEY.
Then:

  bun install
  bash scripts/start.sh

It starts Docker services, applies migrations, starts the API on 3001 and the app on 3010, and
waits for each to answer its own health route before printing next steps. Open http://localhost:3010.

`bash scripts/stop.sh` takes down everything it started, the Bots' computers included. The database,
the files and the browser profiles are volumes, so nothing is deleted either way.

WHAT YOU MUST NOT DO FOR THEM
- Do not run `copilotkit login`. It opens a browser and signs in as them. Tell them to run it.
- Do not put their API keys into any file you did not just tell them about, and do not echo the
  values back.
- Do not change INTELLIGENCE_API_URL or INTELLIGENCE_GATEWAY_WS_URL. The defaults in `.env.example`
  point at the managed service and are correct. Self-hosting Intelligence is an enterprise feature
  deployed by Helm chart and is not self-serve.

FAILURES YOU WILL ACTUALLY SEE, AND WHAT THEY MEAN
The server refuses to start rather than running half-configured. The message names the variable.

- "CopilotKit Intelligence is required and is not configured. Missing: ..."
  One of the three Intelligence values is blank. Almost always INTELLIGENCE_API_KEY, from
  skipping `project select`.

- "No identity provider is configured. Set GOOGLE_OAUTH_* ... or set OPENBOT_SINGLE_USER=true"
  `.env.example` already sets OPENBOT_SINGLE_USER=true, so this means it was removed or edited.
  On a laptop, put it back. It admits every request as one administrator, which is why it must be
  off anywhere other people can reach.

- "KEY_ENCRYPTION_KEY must be a base64-encoded 32-byte key"
  Generate one with `openssl rand -base64 32`. The value in `.env.example` is public and fine
  locally; the deployment refuses it in production on purpose.

- "Model credential is not configured for <Bot>. Add the package credential or set OPENAI_API_KEY."
  This one appears in a conversation rather than at start-up, because the model is only needed
  when a Bot answers.

- A port is taken: start.sh names the port and the process. Re-run with `APP_PORT=<free port>` or
  `SERVER_PORT=<free port>`, or stop the other process.

- `.env is missing`: they skipped `cp .env.example .env`.

HOW TO KNOW IT WORKED
  curl -s localhost:3001/api/capabilities
Expect JSON with "mode":"intelligence". Then open the app and send a message to General Assistant.
A reply means the model credential and Intelligence are both good. The app is on 3010 from the
clone and on 3001 from the image.

WHEN THEY WANT TO MAKE IT THEIRS
The Bots, channels and skills are configuration, not code: `examples/fintech` is a worked example,
pointed at by TENANT_PACKAGE_DIR. Copy it, edit `agents.yaml`, and point TENANT_PACKAGE_DIR at the
copy. That is the fork, and it is the point of the repository.

Watch the path: the server runs from `server/`, so TENANT_PACKAGE_DIR is relative to that, which is
why the default reads `../examples/fintech` rather than `examples/fintech`.

Further reading: README.md, docs/development.md, docs/deployment.md, and docs/configuration.md for
every variable.