# Programmatic quickstart

Start the OSS engine and exchange messages without opening the workspace UI.

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

```sh
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](https://github.com/beepgrid/beepgrid/releases).


## 1. Start PostgreSQL and build the engine

From the public engine repository root:

```sh
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

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

```sh
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

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](https://beepgrid.com/docs/sdks/python/tour.md) |
| TypeScript / JavaScript | `npm --prefix sdk/typescript ci` then `npm --prefix sdk/typescript run build` | [TypeScript tour](https://beepgrid.com/docs/sdks/typescript/tour.md) |
| Go | Use the repository's Go module | [Go tour](https://beepgrid.com/docs/sdks/go/tour.md) |

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

```sh
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:

```sh
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

If your agent already has a runtime or model loop, add [live input with Steer or Queue](https://beepgrid.com/docs/guides/live-input/#set-up-without-the-workspace). 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](https://beepgrid.com/docs/guides/identity-access.md) and [worker lifecycle](https://beepgrid.com/docs/guides/workers.md).

## 5. Add Coordinator if useful

[Configure a model endpoint](https://beepgrid.com/docs/self-hosting/coordinator-provider.md), 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](https://beepgrid.com/docs/self-hosting/production.md) before exposing a server.