Skip to content

Run PULSE locally

There are two ways to run PULSE on your own machine. The Runink TIDE loop runs the whole stack: backend, inference, and the Flutter web app. The direct binary runs only the backend, which is enough to drive and test every non-AI RPC.

Prerequisites

  • Go 1.26 (see grpc/go.mod).
  • Flutter, with Dart 3.12 or newer (see flutter/pubspec.yaml), for the client.
  • The sibling repositories checked out next to pulse/: inference, security, mesh, store, crawler, ui and billing, plus ml, which ui needs. The backend does not build without them, because grpc/go.mod points at them with replace directives. For the TIDE loop below, also a checkout of TIDE (org-runink/tide).
  • buf and the local plugins protoc-gen-go and protoc-gen-go-grpc, to generate the Go protobuf code. The plugins must be on your PATH.
  • grpcurl, to call the API by hand.

The server is pure Go, so nothing here needs cgo.

Option 1: the TIDE loop

From the grpc/ directory of your TIDE checkout (org-runink/tide):

# TIDE's Go module; PULSE_REPO must be an absolute path
PULSE_REPO=/abs/path/to/pulse go run ./cmd/tide dev up pulse

This builds the backend and starts it on a free port. It starts the shared inference server when the model weights are present, then builds and serves the Flutter web app pointed at the backend’s real port. It looks for the mistralrs-server binary in PULSE’s grpc/agents/bin/ and the weights in grpc/agents/models/; when either is missing it says so and starts without the shared inference server.

PULSE_REPO must be an absolute path. The built-in default is relative, and it resolves to nothing from TIDE’s Go module — the symptom is a build log with nothing in it.

Option 2: the backend binary

Build

The generated Go protobuf code is not committed (grpc/api/v1/ is gitignored). Generate it from the repository root first, then build:

buf generate grpc/api/proto --template grpc/buf.gen.yaml -o grpc
cd grpc && go build -o bin/pulse-server . && cd ..

Run it from the repository root, with both the input path and --template, as written. Run from grpc/ it picks up a different configuration and the stubs land in the wrong place.

The Dart stubs under flutter/lib/core/grpc/ are committed, so you only need to regenerate them after changing a .proto. That is a second, separate run — see Developer guide.

Start the server

cd grpc
TIDE_ENVELOPE_KEK="$(openssl rand -base64 32)" \
PULSE_ADMIN_PASSWORD='<choose-a-password>' \
PULSE_JWT_SECRET="$(openssl rand -hex 32)" \
PULSE_GRPC_REFLECTION=true \
  ./bin/pulse-server serve --port 52000 > /tmp/pulse.log 2>&1 &

Four variables matter here:

  • PULSE_JWT_SECRET is required. Without it serve exits with refusing to start: no session signing key configured (PULSE_JWT_SECRET unset). There is no default and no generated key. Any value you generate works locally. It must never be a value that has been committed to a repository: PULSE refuses a key it recognises as published.
  • TIDE_ENVELOPE_KEK is required too. It is the at-rest key that seals tokens in the database, and without it serve exits with Failed to initialize database: at-rest encryption key unavailable, refusing to start. A fresh random key works locally.
  • PULSE_ADMIN_PASSWORD seeds a break-glass admin whose login username is admin unless PULSE_ADMIN_USERNAME says otherwise. Without it the log says skipping admin seed; break-glass login unavailable, no password is invented, and every password login fails. The seeded admin’s password is reset to the injected one on every restart.
  • PULSE_GRPC_REFLECTION=true turns on gRPC server reflection so grpcurl can list services. It is off by default. Never set it on a deployed instance.

With no --port (and no PORT variable), the server picks a free port.

Don’t stop the server with pkill -f 'pulse-server serve'. That pattern also matches the shell running the command, so it kills your own command and looks like a server crash. Kill the process by its PID instead.

Wait for health

until curl -s localhost:52000/health | grep -q '"status":"ok"'; do sleep 2; done
curl -s localhost:52000/health

The response looks like {"status":"ok","model_ready":false,"port":52000}. model_ready stays false until an inference server has loaded its weights. The HTTP status is always 200. PULSE serves every non-AI feature without a model.

Sign in and call an RPC

TOK=$(grpcurl -plaintext -d '{"username":"admin","password":"<your-password>"}' \
      localhost:52000 pulse.v1.IdentityService/Login | jq -r '.accessToken')
grpcurl -plaintext -H "authorization: Bearer $TOK" -d '{}' \
      localhost:52000 pulse.v1.CampaignService/ListCampaigns

The token is in the accessToken field, not token. A bearer token is how command-line and native clients authenticate; the web app never holds one and uses the session cookie instead. See Signing in.

Without a model

A bare machine has no mistralrs-server and no model weights. The server still starts and serves login, every read, and every create or update. AI calls fail with inference server is not running. That is the expected result, not a bug.

Run the Flutter client

cd flutter
flutter run -d chrome     # web
flutter run -d linux      # desktop
flutter run               # a connected Android device

The client reads its backend address from PULSE_BACKEND_URL, a --dart-define. With no define, a native build talks to http://localhost:50051. A define is baked in at compile time, which is why tide dev up rebuilds the app when the backend port changes.

PULSE is an Android and iOS app: the backend serves no web bundle. A production backend needs CORS_ALLOWED_ORIGINS set to pinned origins or it refuses to boot.

Run the tests

cd grpc && TIDE_ENVELOPE_KEK="$(head -c32 /dev/urandom | base64 -w0)" go test ./...
cd flutter && flutter analyze && flutter test