Skip to main content
The temporal-server start command starts one or more Temporal Server services.

​
Synopsis

temporal-server start [flags]

​
Description

Starts Temporal Server with the specified services. By default, starts all four core services:
  • frontend: Public-facing API service
  • history: Workflow execution orchestration
  • matching: Task queue management and distribution
  • worker: System workflows (archival, replication, etc.)
Optionally, you can also run:
  • internal-frontend: Internal API service for admin operations

​
Options

​
—service, —svc

Specifies which service(s) to start. Can be specified multiple times.
  • Type: String (repeatable)
  • Default: frontend, history, matching, worker
  • Valid values: frontend, history, matching, worker, internal-frontend
# Start all services (default)
temporal-server start

# Start only frontend and history
temporal-server start --service frontend --service history

# Start with internal-frontend for admin operations
temporal-server start --service frontend --service history --service matching --service worker --service internal-frontend

​
—config-file

Path to the configuration file.
  • Type: String (file path)
  • Default: None (uses embedded configuration)
  • Environment variable: TEMPORAL_SERVER_CONFIG_FILE_PATH
temporal-server start --config-file /etc/temporal/config.yaml
Note: Cannot be used with --config, --env, --zone, or --root.

​
—allow-no-auth

Allows the server to start without an authorizer configured.
  • Type: Boolean
  • Default: false
  • Environment variable: TEMPORAL_ALLOW_NO_AUTH
temporal-server start --allow-no-auth
Warning: Only use in development environments. Production deployments should always use proper authorization.

​
Deprecated Options

The following options are deprecated. Use --config-file instead.

​
—root, -r

Root directory of execution environment.
  • Type: String
  • Default: .
  • Environment variable: TEMPORAL_ROOT
  • Deprecated: Use --config-file

​
—config, -c

Config directory path relative to root.
  • Type: String
  • Default: config
  • Environment variable: TEMPORAL_CONFIG_DIR
  • Deprecated: Use --config-file

​
—env, -e

Runtime environment.
  • Type: String
  • Default: development
  • Environment variable: TEMPORAL_ENVIRONMENT
  • Deprecated: Use --config-file

​
—zone, —az

Availability zone.
  • Type: String
  • Default: None
  • Environment variable: TEMPORAL_AVAILABILITY_ZONE
  • Deprecated: Use --config-file

​
—services, -s

Comma-separated list of services (legacy format).
  • Type: String
  • Deprecated: Use --service flag multiple times instead
# Old format (deprecated)
temporal-server start --services frontend,history,matching

# New format (recommended)
temporal-server start --service frontend --service history --service matching

​
Examples

​
Start with Default Configuration

Uses embedded development configuration: 
temporal-server start

​
Start with Custom Configuration

temporal-server start --config-file /etc/temporal/production.yaml

​
Start Specific Services

Run only frontend and history on separate hosts: 
# On host 1
temporal-server start \
  --config-file /etc/temporal/config.yaml \
  --service frontend \
  --service history

# On host 2  
temporal-server start \
  --config-file /etc/temporal/config.yaml \
  --service matching \
  --service worker

​
Development Mode

Start with no authentication for local development: 
temporal-server start --allow-no-auth

​
Using Environment Variables

export TEMPORAL_SERVER_CONFIG_FILE_PATH=/etc/temporal/config.yaml
export TEMPORAL_ALLOW_NO_AUTH=false
temporal-server start

​
Docker Deployment

FROM temporalio/server:latest

COPY config.yaml /etc/temporal/config.yaml

CMD ["temporal-server", "start", "--config-file", "/etc/temporal/config.yaml"]

​
Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: temporal-frontend
spec:
  replicas: 3
  selector:
    matchLabels:
      app: temporal-frontend
  template:
    metadata:
      labels:
        app: temporal-frontend
    spec:
      containers:
      - name: temporal
        image: temporalio/server:latest
        args:
        - "start"
        - "--service"
        - "frontend"
        - "--config-file"
        - "/etc/temporal/config.yaml"
        ports:
        - containerPort: 7233
          name: grpc
        - containerPort: 7243
          name: http
        volumeMounts:
        - name: config
          mountPath: /etc/temporal
      volumes:
      - name: config
        configMap:
          name: temporal-config

​
Service Roles

​
Frontend Service

  • Handles client API requests
  • Performs authentication and authorization
  • Routes requests to internal services
  • Exposes both gRPC (port 7233) and HTTP (port 7243) endpoints

​
History Service

  • Manages workflow execution state
  • Persists workflow history
  • Coordinates workflow task execution
  • Handles workflow signals, queries, and updates

​
Matching Service

  • Manages task queues
  • Distributes tasks to workers
  • Handles task queue partitioning
  • Manages worker versioning

​
Worker Service

  • Executes system workflows
  • Handles archival of closed workflows
  • Manages cross-cluster replication
  • Processes background tasks

​
Internal-Frontend Service (Optional)

  • Provides internal APIs for system workers
  • Separates internal traffic from external clients
  • Recommended for production with authorization

​
Startup Process

  1. Configuration Loading: Loads config from file or embedded defaults
  2. Dynamic Config: Initializes dynamic configuration client
  3. Authorization: Sets up authorizer, claim mapper, and audience mapper
  4. Service Initialization: Starts requested services
  5. Health Checks: Services report healthy once initialized
  6. Ready to Serve: Server begins accepting requests

​
Shutdown Behavior

The server handles graceful shutdown on signals:
  • SIGTERM: Graceful shutdown with drain period
  • SIGINT (Ctrl+C): Immediate shutdown
During graceful shutdown:
  1. Stops accepting new requests
  2. Drains in-flight requests
  3. Closes database connections
  4. Exits cleanly

​
Exit Codes

  • 0: Successful shutdown
  • 1: Configuration error or startup failure
  • 2: Invalid command-line arguments

​
Troubleshooting

​
Service Won’t Start

  1. Check configuration file syntax: 
    temporal-server validate-dynamic-config config/dynamicconfig.yaml
  2. Verify database connectivity: 
    # Test PostgreSQL connection
psql -h localhost -U temporal -d temporal
  3. Check port availability: 
    netstat -tuln | grep 7233
  4. Review server logs for errors

​
Authorization Errors

  1. Verify authorizer configuration in config file
  2. Check JWT key provider settings
  3. Ensure --allow-no-auth is set for development
  4. Review authorization logs

​
Database Connection Issues

  1. Verify database credentials
  2. Check network connectivity
  3. Ensure database schema is initialized: 
    temporal-sql-tool --plugin postgres setup-schema -v 0.0

​
Performance Issues

  1. Check resource limits (CPU, memory)
  2. Monitor database performance
  3. Review dynamic config settings
  4. Check for network latency

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us