temporal-server

Temporal workflow server packaged as an npm module. Downloads the official Temporal CLI binary which includes a development server with SQLite persistence and built-in Web UI. No Docker, no external databases.

Install

npm install temporal-server

The postinstall script downloads the Temporal CLI binary (~60MB). Skip with TEMPORAL_SERVER_SKIP_BINARY_DOWNLOAD=1.

Supported Platforms

OS	Architecture
Linux	amd64, arm64
macOS	amd64, arm64
Windows	amd64, arm64
WSL	amd64, arm64

WSL is auto-detected. Set TEMPORAL_BINARY_PLATFORM=windows to force the Windows binary.

Usage

CLI

temporal start       # Start server in background
temporal start -f    # Start in foreground
temporal stop        # Stop server
temporal restart     # Restart
temporal status      # Check if running (all 4 ports)
temporal api         # Start server in foreground
temporal clean       # Stop + remove bin/, data/, node_modules/

npm scripts

npm start          # Start server
npm stop           # Stop
npm run restart    # Restart
npm run status     # Check status (gRPC, HTTP, UI, Metrics)
npm run api        # Start in foreground
npm run clean      # Full cleanup

Ports

Service	Default	URL
gRPC	7233	localhost:7233
HTTP API	8233	http://localhost:8233
Web UI	8080	http://localhost:8080
Metrics	9090	http://localhost:9090

Configuration

Settings are loaded from configs/server.json and can be overridden via environment variables. Environment variables take precedence over the config file.

Environment Variables

Variable	Default	Description
TEMPORAL_IP	127.0.0.1	Bind address
TEMPORAL_PORT	7233	gRPC port
TEMPORAL_HTTP_PORT	8233	HTTP API port
TEMPORAL_UI_PORT	8080	Web UI port
TEMPORAL_METRICS_PORT	9090	Metrics port
TEMPORAL_DB_PATH	data/temporal.db	SQLite database path (relative to package root)
TEMPORAL_LOG_LEVEL	warn	Log level (debug, info, warn, error)
TEMPORAL_SERVER_SKIP_BINARY_DOWNLOAD	-	Set to 1 to skip binary download during install
TEMPORAL_BINARY_PLATFORM	auto	Force platform for binary download (windows, linux, darwin)

Config File

configs/server.json:

{
  "ip": "127.0.0.1",
  "port": 7233,
  "httpPort": 8233,
  "uiPort": 8080,
  "metricsPort": 9090,
  "dbPath": "data/temporal.db",
  "namespaces": ["default"],
  "logLevel": "warn",
  "sqlitePragma": ["journal_mode=wal", "busy_timeout=5000"]
}

SQLite Pragmas

The sqlitePragma array passes --sqlite-pragma flags to the Temporal CLI. The defaults enable:

• journal_mode=wal -- Write-Ahead Logging for concurrent read/write access. Without this, SQLite uses DELETE journal mode which allows only one writer at a time, causing context canceled errors when Temporal's internal system workflows contend for write access.
• busy_timeout=5000 -- Wait up to 5 seconds for a write lock instead of failing immediately with SQLITE_BUSY.

Data persists in data/temporal.db (created automatically on first start).

Testing

Requires the temporalio Python package (pip install temporalio).

npm start
python test_temporal.py
npm stop

Tests HTTP API, Web UI, metrics endpoint, and executes a sample workflow.

How It Works

Under the hood, npm start runs:

temporal server start-dev \
  --db-filename data/temporal.db \
  --port 7233 --http-port 8233 --ui-port 8080 --metrics-port 9090 \
  --namespace default \
  --sqlite-pragma journal_mode=wal --sqlite-pragma busy_timeout=5000

The official Temporal CLI handles everything in a single process: gRPC frontend, HTTP API, Web UI, and metrics.

Use as a Dependency

{
  "dependencies": {
    "temporal-server": "^0.0.10"
  },
  "scripts": {
    "temporal:start": "temporal start",
    "temporal:stop": "temporal stop",
    "temporal:status": "temporal status"
  }
}

Override ports via environment variables in your .env or launch script:

TEMPORAL_PORT=17233 TEMPORAL_UI_PORT=18080 temporal start

Connect your Temporal client to localhost:7233 (or your configured port).

License

MIT