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,uiandbilling, plusml, whichuineeds. The backend does not build without them, becausegrpc/go.modpoints at them withreplacedirectives. For the TIDE loop below, also a checkout of TIDE (org-runink/tide). bufand the local pluginsprotoc-gen-goandprotoc-gen-go-grpc, to generate the Go protobuf code. The plugins must be on yourPATH.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 pulseThis 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_SECRETis required. Without itserveexits withrefusing 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_KEKis required too. It is the at-rest key that seals tokens in the database, and without itserveexits withFailed to initialize database: at-rest encryption key unavailable, refusing to start. A fresh random key works locally.PULSE_ADMIN_PASSWORDseeds a break-glass admin whose login username isadminunlessPULSE_ADMIN_USERNAMEsays otherwise. Without it the log saysskipping 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=trueturns on gRPC server reflection sogrpcurlcan 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.
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/healthThe 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/ListCampaignsThe 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 deviceThe 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