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