// Instructions for running the UI against a local Temporal server build instead of the built-in CLI dev server. Use when asked how to start the dev environment, run the UI locally, or connect to a local Temporal repo.
Set up a new git worktree for this repo by copying gitignored files (bin/) and building server assets so pnpm dev works without errors
Test OAuth2 token refresh and session expiry locally. Use when working on auth, tokens, SSO, OIDC, or session management features.
Migrate a Svelte 4 component to Svelte 5 runes syntax. Use when asked to migrate, convert, or upgrade a .svelte file to Svelte 5.
| name | local-temporal |
| description | Instructions for running the UI against a local Temporal server build instead of the built-in CLI dev server. Use when asked how to start the dev environment, run the UI locally, or connect to a local Temporal repo. |
To develop against a local build of the Temporal server, you need two things running in separate terminals.
Navigate to your local clone of the temporalio/temporal repo and start the server:
make start
This builds and starts the server with SQLite in-memory. If you want a specific branch, check it out first:
git checkout <branch-name>
make bins # safe to run even if already built — outputs "Nothing to be done" and exits cleanly
make start
The server runs gRPC on port 7233 and HTTP on 7243.
From this repo, use the local-temporal script instead of the default dev script:
pnpm dev:local-temporal
This loads .env.local-temporal which points the UI at the local server instead of spinning up its own.
pnpm dev?pnpm dev (aliased to pnpm dev:ui-server) starts a bundled Temporal server alongside the UI. pnpm dev:local-temporal skips that and connects to whatever is already running on the configured ports.
This is critical when working on unreleased features. The ui-server (server/) is a separate Go binary that acts as a grpc-gateway — it decodes HTTP/JSON into proto messages and forwards them to the Temporal server over gRPC. Its proto descriptors are baked in at compile time from its own server/go.mod.
If the Temporal server branch uses a newer go.temporal.io/api version than server/go.mod, the ui-server will reject any new HTTP fields as "unknown field" before the request ever reaches the Temporal server.
When switching to a Temporal branch with API changes:
Check what go.temporal.io/api version the Temporal server branch uses:
grep "go.temporal.io/api" ~/code/temporal/go.mod
Update server/go.mod to match:
cd server
go get go.temporal.io/api@<version>
Rebuild the ui-server binary:
go build -o ui-server ./cmd/server
Then restart pnpm dev:local-temporal to pick up the new binary.