Website · Documentation · GitHub · Changelog

Tools tier. Maintained, on 0.x: a minor release can break, so pin a version. See product tiers.

Overview

@bpmnkit/proxy is a local Node.js server that bridges the BPMN Kit editor with AI services and your Camunda cluster. It runs on port 3033 and provides:

• AI chat bridge — SSE streaming endpoint for AI-assisted diagram editing; connects to any OpenAI-compatible LLM API
• MCP server — Model Context Protocol server for AI agent integrations (stdio transport)
• Camunda API proxy — transparent HTTP proxy that injects auth from your casen CLI profiles

While the AI is working, /chat emits preview events carrying the diagram as it stands, so a client can render the process being drawn instead of waiting for the model to stop. They come from two places: the diagram the model is writing into a tool call, read out of the tokens themselves, and — once the MCP server has written real state — that state, after each tool call. Previews are advisory; the xml event sent once the stream ends is the authoritative result.

The proxy reads authentication from profiles stored by the @bpmnkit/cli (~/.config/casen/config.json), so you don't need to configure credentials separately.

Installation

npm install -g @bpmnkit/proxy
# or run from the monorepo:
pnpm proxy

Prerequisites

Unlike the rest of BPMN Kit, this package has native dependencies — isolated-vm (the sandbox the AI bridge evaluates code in), better-sqlite3, imapflow and nodemailer. isolated-vm and better-sqlite3 are compiled at install time, so the machine needs a toolchain:

| | | |---|---| | Linux | python3, make, g++ (build-essential) | | macOS | Xcode Command Line Tools — xcode-select --install | | Windows | Visual Studio Build Tools with the C++ workload |

Without them the install fails at node-gyp rebuild with gyp ERR! find Python or spawn node-gyp ENOENT. Nothing else in the workspace needs this — every library package here is dependency-free.

Quick Start

# Start the proxy server (port 3033)
bpmn-ai-server

# Or start the MCP server (stdio)
bpmn-mcp

Endpoints

| Method | Path | Description | |--------|------|-------------| | GET | /status | Health check; returns server version and active profile | | POST | /chat | AI chat — SSE stream; sends token, preview, xml, error and done events | | GET | /profiles | List all configured casen profiles | | ALL | /api/* | Transparent proxy to your Camunda cluster (adds auth header) | | GET | /operate/stream | SSE stream for the @bpmnkit/operate monitoring frontend |

Configuration

The proxy reads from the active casen CLI profile. Set an AI_API_KEY environment variable for the AI bridge:

AI_API_KEY=sk-... bpmn-ai-server

Or use the X-Profile request header to target a specific profile on the /api/* proxy:

curl -H "X-Profile: production" http://localhost:3033/api/v2/process-definitions

Security

The proxy holds your Camunda credentials, reads and writes project files, and starts AI CLIs, so it is locked down by default:

• Loopback only. It listens on 127.0.0.1 and ::1. --host (or BPMNKIT_PROXY_HOST) listens elsewhere and prints a warning.
• Allowed origins only. Browser requests must come from https://bpmnkit.com, https://bpmnkit-studio.pages.dev, the desktop app (tauri://localhost, http(s)://tauri.localhost) or a localhost / 127.0.0.1 / [::1] origin on any port. Any other origin gets 403 and no CORS headers; the allowed origin is reflected, never *. Add origins with --allow-origin or BPMNKIT_PROXY_ALLOWED_ORIGINS (comma-separated).
• Loopback Host only. Requests must name the proxy as localhost, 127.0.0.1 or [::1], which stops DNS rebinding. Add names with --allow-host or BPMNKIT_PROXY_ALLOWED_HOSTS.
• Workspace roots. /fs/* and /element-templates work only inside folders passed with --root / BPMNKIT_PROXY_ROOTS or opened by Studio. The proxy will not open the filesystem root, your home directory or a hidden folder on a client's say-so, and only touches .bpmn, .dmn, .form and .md files. .. and symlinks out of a root are refused.
• AI CLIs without tools. claude, copilot and gemini run with permission checks on, no built-in tools (no shell, file or web access), in an empty temporary folder, and without your own MCP servers, settings or extensions. A /chat diagram edit may call only the proxy's diagram MCP tools, and compose_diagram runs the model's code in an isolated-vm isolate. Request data reaches the model fenced as untrusted input. askText gives other callers, such as casen ask, the same lockdown.

Programs that send no Origin header — the CLI, the MCP server, curl — are served as before.

casen proxy start --allow-origin https://modeler.example.com --root ~/work/processes

Related Packages

| Package | Description | |---------|-------------| | @bpmnkit/core | BPMN/DMN/Form parser, builder, layout engine | | @bpmnkit/canvas | Zero-dependency SVG BPMN viewer | | @bpmnkit/editor | Full-featured interactive BPMN editor | | @bpmnkit/engine | Lightweight BPMN process simulator for tests and demos | | @bpmnkit/feel | FEEL expression language parser & evaluator | | @bpmnkit/plugins | 34 composable canvas plugins | | @bpmnkit/api | Camunda 8 REST API TypeScript client | | @bpmnkit/ascii | Render BPMN diagrams as Unicode ASCII art | | @bpmnkit/markdown | BPMN diagrams in Markdown — remark, markdown-it and README pre-rendering | | @bpmnkit/docspack | BPMN Kit docs as an offline docspack package for AI agents | | @bpmnkit/camunda-docspack | Camunda 8 docs as an offline docspack package for AI agents | | @bpmnkit/ui | Shared design tokens and UI components | | @bpmnkit/profiles | Shared auth, profile storage, and client factories for CLI & proxy | | @bpmnkit/operate | Monitoring & operations frontend for Camunda clusters | | @bpmnkit/connector-gen | Generate connector templates from OpenAPI specs | | @bpmnkit/connectors | Camunda 8 OOTB connector catalog and deterministic template application | | @bpmnkit/cli | Camunda 8 command-line interface (casen) | | @bpmnkit/patterns | Domain process patterns for BPMNKit AIKit | | @bpmnkit/reebe-wasm | WebAssembly BPMN engine for browser simulation | | @bpmnkit/worker-client | Thin Zeebe REST client for standalone workers | | @bpmnkit/user-tasks | Embeddable user task widget for Camunda 8 | | @bpmnkit/cli-sdk | Plugin authoring SDK for the casen CLI | | @bpmnkit/create-casen-plugin | Scaffold a new casen CLI plugin in seconds | | @bpmnkit/casen-report | HTML reports from Camunda 8 incident and SLA data | | @bpmnkit/casen-worker-http | Example HTTP worker plugin — completes jobs with live JSONPlaceholder API data | | @bpmnkit/casen-worker-ai | AI task worker — classify, summarize, extract, and decide using Claude |

License

MIT © BPMN Kit — made by u11g