Run the Demo
The demo shows OpenBox on top of CopilotKit, with CopilotKit on top of LangGraph. It is a Next.js app with a local LangGraph TypeScript agent. CopilotKit handles the chat runtime and generative UI. OpenBox governs prompts, tool inputs, tool outputs, assistant output, and approval decisions.
CopilotKit can connect to multiple backend agent frameworks. This demo uses LangGraph, with OpenBox layered above CopilotKit and the current LangGraph bridge instrumenting the backend graph so both sides share one governed session.
Reference repository:
Prerequisites
- Node.js
22+ - npm
- access to the
OpenBox-AI/openbox-x-copilotkitrepository - an OpenAI-compatible model endpoint
- an OpenBox Core URL and agent runtime key
- an OpenBox agent DID and private key when the registered agent requires signing
Clone The Repository
git clone https://github.com/OpenBox-AI/openbox-x-copilotkit
cd openbox-x-copilotkit
Install Dependencies
cp .env.example .env
npm install
The demo currently installs openbox-sdk from the OpenBox GitHub organization. You do not need to clone the SDK as a sibling repository for the demo path.
Prepare An OpenBox Agent
Use the OpenBox setup flow before running live demo traffic:
- Register or open an OpenBox agent.
- Generate an agent runtime key for the demo.
- Copy the agent DID and private key unless Require signing is disabled.
- Configure the demo controls in Authorize: guardrails, policies, and behavior rules.
New OpenBox agents require signing by default. Use the DID and private key from agent registration unless you intentionally disable signing in the agent settings.
The demo does not require CopilotKit to author OpenBox rules. CopilotKit sends prompts, tool activity, assistant output, and approval decisions through the OpenBox integration, and OpenBox evaluates the controls configured on the registered agent.
For a predictable demo matrix, create guardrails, policies, and behavior rules in Authorize, then use the suggestion chips below to see how your controls behave.
Configure Environment
Required values:
| Variable | Purpose |
|---|---|
OPENAI_BASE_URL | OpenAI-compatible chat provider base URL |
OPENAI_MODEL | chat model used by the LangGraph backend |
OPENAI_API_KEY | model provider API key |
OPENBOX_ENABLED | set to true to enable OpenBox governance |
OPENBOX_CORE_URL | OpenBox Core base URL |
OPENBOX_API_KEY | OpenBox agent runtime key, obx_live_* or obx_test_* |
OPENBOX_AGENT_DID | agent DID, required when signing is enabled |
OPENBOX_AGENT_PRIVATE_KEY | base64 raw Ed25519 private key, required when signing is enabled |
Optional and maintainer values:
| Variable | Purpose |
|---|---|
AGENT_URL | local or deployed LangGraph backend URL, defaults to http://localhost:8123 |
APP_URL | local app URL used by verification scripts |
LANGSMITH_API_KEY | LangSmith key when using a LangGraph deployment that requires it |
OPENBOX_API_URL | server-side OpenBox platform/backend URL for the demo approval-decision route |
OPENBOX_BACKEND_API_KEY | server-side org/backend key for the demo approval-decision route |
OPENBOX_AGENT_ID | OpenBox platform agent ID for readiness checks and maintainer setup |
OPENBOX_BACKEND_API_KEY is not sent to the browser and is not required for normal runtime governance. It is only used by this demo path that posts CopilotKit-rendered approve/reject decisions back to OpenBox.
Run Locally
npm run dev
Default services:
| Service | URL |
|---|---|
| LangGraph agent | http://localhost:8123 |
| Next.js app | the port printed by Next.js |
Open the URL printed by Next.js.
Test The Demo Manually
Use the demo suggestion chips or enter a natural business request:
| Suggestion | Expected path when demo controls are seeded |
|---|---|
Review Work Queue | allowed result |
Prepare Exception Report | output redaction or constrained result |
Draft Customer Update | final-output governance with redaction or constraint |
Prepare Vendor Handoff | interactive choice, then OpenBox governance |
Draft Billing Escalation | manual edit, then OpenBox governance |
Issue Service Credit | human approval |
Send Exception IDs | block |
Update Vendor Bank | halt |
If you skipped npm run openbox:admin:setup, the same chips still test the integration, but the exact verdicts come from the guardrails, policies, and behavior rules you configured in OpenBox.
After each run, check both surfaces:
- In the CopilotKit UI, confirm the OpenBox decision card and any released business result.
- In the OpenBox Dashboard, open the registered agent and confirm the new session, governance events, guardrail/policy evaluations, approval records, or halted state.
Verify The Local Build
Fast local checks:
npm run build
npx tsc --noEmit
cd agent && npx tsc --noEmit
Maintainer Verification
Maintainer checks that call live OpenBox services:
npm run openbox:admin:setup
npm run openbox:verify
npm run openbox:e2e
npm run openbox:admin:setup requires OPENBOX_API_URL, OPENBOX_BACKEND_API_KEY, and OPENBOX_AGENT_ID. It mutates the configured OpenBox agent. Use it only when you intend to refresh the demo's OpenBox-side guardrails, behavior rules, goal-alignment config, and policy setup. If you already configured your own controls in Authorize, skip that setup script.
npm install installs the Playwright dependency used by npm run openbox:e2e. The e2e script can start the local agent and app automatically. If you already started them yourself, set APP_URL and AGENT_URL in .env so Playwright targets the running services.