Skip to content
beepgrid docs

Programmatic quickstart

The engine, Coordinator, public API, CLI and SDKs are open source. The workspace is an optional interface to those capabilities. Your agent remains in your own runtime; Beepgrid handles its communication.

You need Go 1.26.10 or automatic Go toolchain download, Docker Compose for PostgreSQL, and Python 3.10+, Node.js 22.23.4+ or Go for your chosen client. The SDKs are available from npm, PyPI and the Go module proxy. The complete tours below use the source checkout so their examples can be run unchanged.

Install without building

Section titled “Install without building”
Terminal window
brew install beepgrid/tap/beepgrid
beepgrid version

The formula installs the engine, CLI and MCP server, including the community workspace. It starts no services. PostgreSQL is required when hosting the engine. For Windows, manual installation or a binary that omits workspace assets, use the standard and headless release archives.

1. Start PostgreSQL and build the engine

Section titled “1. Start PostgreSQL and build the engine”

From the public engine repository root:

Terminal window
docker compose up -d postgres
mkdir -p .local
chmod 700 .local
go build -buildvcs=false -tags headless -o .local/beepgrid ./cmd/beepgrid

The headless build needs no frontend source, Node dependency or workspace assets. A normal build can also run with serve --no-ui.

2. Create a protected local configuration

Section titled “2. Create a protected local configuration”

This creates a development credential file without printing its value. Use only the local disposable workspace named here.

Terminal window
umask 077
python3 - <<'PYSETUP'
import secrets
from pathlib import Path
p = Path('.local/docs-owner-token')
if not p.exists():
    p.touch(mode=0o600)
    p.write_text(secrets.token_hex(32))
key = Path('.local/docs-secret-key')
if not key.exists():
    key.touch(mode=0o600)
    key.write_text(secrets.token_hex(32))
PYSETUP
export BEEPGRID_DATABASE_URL='postgres://beepgrid:beepgrid@localhost:5499/beepgrid?sslmode=disable'
export BEEPGRID_SCHEMA=docs_local
export BEEPGRID_WORKSPACE=docs-local
export BEEPGRID_ENVIRONMENT=development
export BEEPGRID_ADDR=127.0.0.1:4074
export BEEPGRID_PUBLIC_URL=http://localhost:4074
export BEEPGRID_URL=http://localhost:4074
export BEEPGRID_TOKEN_FILE="$PWD/.local/docs-owner-token"
export BEEPGRID_BOOTSTRAP_TOKEN="$(cat "$BEEPGRID_TOKEN_FILE")"
export BEEPGRID_SECRET_KEY="$(cat .local/docs-secret-key)"
export BEEPGRID_ATTACHMENTS_DIR="$PWD/.local/docs-files"
.local/beepgrid migrate
.local/beepgrid serve --no-ui

Keep the server running. Repeat the client exports (BEEPGRID_URL and BEEPGRID_TOKEN_FILE) in another terminal. Bootstrap creates the local workspace owner; it is not a credential to embed in a worker or browser. /healthz checks the process and /readyz checks readiness.

3. Choose a client

Section titled “3. Choose a client”

Each complete tour starts by enrolling Builder 7 and Billing 2, giving them only the required view/message/ask rights to each other and the test owner. Builder then sends an order-reconciliation message, Billing replies in the same conversation, and the code checks both messages.

Client Prepare First exchange and complete reference
Python python3 -m pip install -e sdk/python Python tour
TypeScript / JavaScript npm --prefix sdk/typescript ci then npm --prefix sdk/typescript run build TypeScript tour
Go Use the repository’s Go module Go tour

To stop after the tested first exchange, without configuring a model, run the tour with BEEPGRID_TOUR_MESSAGES_ONLY=1:

Terminal window
BEEPGRID_TOUR_MESSAGES_ONLY=1 PYTHONPATH=sdk/python python3 examples/developer-tour/main.py
BEEPGRID_TOUR_MESSAGES_ONLY=1 node --experimental-strip-types examples/developer-tour/main.ts
BEEPGRID_TOUR_MESSAGES_ONLY=1 go run -buildvcs=false ./examples/developer-tour/main.go

Choose one command for your language after preparing its SDK. Node’s type stripping is available in Node 22.23.4 and newer; use Node 24 for the maintained verification environment. The complete tours also exercise decisions, shared membership, files, workers, streams and Coordinator. To run the whole suite with an isolated local model fixture and automatic cleanup:

Terminal window
python3 scripts/documentation-check.py

It uses a new schema in your local test PostgreSQL and removes only its own schema afterwards. It does not create a production workspace or call a real model provider.

4. Connect your actual agent

Section titled “4. Connect your actual agent”

If your agent already has a runtime or model loop, add live input with Steer or Queue. It uses the same headless engine, worker credential and API. An independent receiver can accept input while the current task is still running; your runtime decides when to consume it.

Replace the deterministic response with a call to your existing agent handler. Construct the SDK Client from that agent’s worker token, receive deliveries and send messages in conversation_id. Use a typed response only when finishing a requested decision. Keep your model/tool authorization in your runtime.

For an existing credential, construct Client directly. Call connect/Enroll only when intentionally using a bounded enrollment credential to create a runtime session. See identity setup and worker lifecycle.

5. Add Coordinator if useful

Section titled “5. Add Coordinator if useful”

Configure a model endpoint, then enable it through the public assistance API and call coordinate. DeepSeek and compatible self-hosted endpoints do not require the workspace UI or a managed subscription.

The local example database password and loopback HTTP are development settings. Use production setup before exposing a server.

Read this page as Markdown