Run Ballet locally

One command builds and runs the whole system on your machine:

make run

Then open http://localhost:8080 — there is no sign-in: you are the local user, a platform admin, and Ballet only listens on localhost. Press Ctrl-C to stop everything.

For several users, run BALLET_AUTH=oidc make run: it starts the development Keycloak and you sign in as alice / alice (platform admin of the development realm, see Configure OIDC Authentication).

What it does

make run is make bundle followed by scripts/run.sh.

make bundle

Installs the web dependencies if needed (bun), builds the web UI, copies it into core/internal/transport/webui/dist and builds every service into bin/. Core is built with the bindata build tag, which embeds the web UI in the binary — one bin/core serves the API and the UI, like a release build. Without the tag (make build, go run, tests) Core embeds nothing.

scripts/run.sh

Starts, in order, waiting for each to answer:

  1. with BALLET_AUTH=oidc, the development Keycloak on :8180 (unless an OIDC issuer answers there already; the first start downloads it and needs Java 21+);

  2. Core on :8080 (API, realtime, web UI), which writes the other services’ tokens;

  3. Knowledge on :8081;

  4. the LLM gateway on :8082;

  5. an agent named local with capacity 2: sessions run as processes on this machine (Agents). Set BALLET_AGENT_SESSION_USER to run them as another OS user (the script must then run as root).

Every service’s output is shown prefixed with its name and written to .run/logs/<service>.log. If a service exits, the script stops the others.

State

Databases, keys and service tokens live in .run/data (git-ignored) and survive restarts. Delete .run/ to start from scratch. Keycloak keeps its data in memory: it re-imports the realm on every start.

Options

Environment variables of scripts/run.sh:

BALLET_FAKE_LLM=1

Also run a fake Anthropic API on :9900 and route the gateway to it (BALLET_GATEWAY_ANTHROPIC_URL): agent sessions and the planner run without a real API key (store any key, e.g. sk-fake, as the project’s Anthropic credential).

BALLET_RUN_DIR

Directory for state and logs instead of .run.

BALLET_AUTH=oidc

Sign in through the development Keycloak (multiple users) instead of running without authentication.

Any BALLET_* configuration variable (Configuration) still applies to its service, e.g. BALLET_CORE_OIDC_ISSUER_URL for another identity provider (it must answer; Keycloak is then not started; implies authentication).

Working on the UI

make run serves the built UI; it does not reload on changes. For UI work run the Vite dev server against it (Web UI Development):

cd web && bun run dev     # http://localhost:5173, proxies to Core on :8080