Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/PaymanAI/sigilum/llms.txt

Use this file to discover all available pages before exploring further.

The sigilum gateway commands manage the local Sigilum gateway process, which enforces request signing, authorization checks, and proxies requests to upstream providers.

​
gateway start

Start the Sigilum gateway service.

​
Usage

sigilum gateway start [options]

​
Options

OptionDefaultDescription
--namespace <value>Auto-detectedTarget namespace
--home <path>~/.sigilum-workspaceGateway Sigilum home directory
--api-url <url>https://api.sigilum.idSigilum API base URL
--addr <addr>:38100Listen address
-h, --help-Show help

​
Namespace Resolution

The namespace is resolved in this order:
  1. --namespace flag
  2. SIGILUM_NAMESPACE environment variable
  3. GATEWAY_SIGILUM_NAMESPACE environment variable
  4. ~/.sigilum/config.env file (SIGILUM_NAMESPACE or GATEWAY_SIGILUM_NAMESPACE)
  5. Interactive prompt (if terminal is available)

​
Identity Auto-Bootstrap

On first start, the gateway automatically:
  1. Creates a master key file at <home>/gateway-master-key (mode 0600)
  2. Initializes Sigilum identity at <home>/identities/<namespace>/identity.json
  3. Registers the identity with the API

​
Examples

Start gateway with auto-detected namespace: 
sigilum gateway start
Output: 
[i] sigilum 1.0.0 (gateway)
Starting Sigilum gateway.
  namespace: johndee
  api:       https://api.sigilum.id
  addr:      :38100
  home:      /home/user/.sigilum-workspace

Sigilum gateway running on :38100
Start gateway with explicit namespace: 
sigilum gateway start --namespace johndee
Start gateway for local development: 
sigilum gateway start \
  --namespace johndee \
  --api-url http://127.0.0.1:8787 \
  --addr :38100
Start gateway with custom home directory: 
sigilum gateway start \
  --namespace johndee \
  --home /var/sigilum/workspace

​
Environment Variables

The command recognizes these environment variables:
  • SIGILUM_NAMESPACE - Default namespace
  • GATEWAY_SIGILUM_NAMESPACE - Gateway-specific namespace
  • GATEWAY_SIGILUM_HOME - Gateway home directory
  • SIGILUM_API_URL - API base URL
  • SIGILUM_REGISTRY_URL - Alternative API URL variable
  • GATEWAY_ADDR - Listen address
  • GATEWAY_MASTER_KEY - Pre-generated master key

​
Master Key

The gateway generates and stores a master encryption key at <home>/gateway-master-key on first start. This key encrypts sensitive data stored by the gateway. To use a pre-generated master key: 
GATEWAY_MASTER_KEY=<hex-key> sigilum gateway start --namespace johndee
Or set it globally: 
sigilum --gateway-master-key <hex-key> gateway start --namespace johndee

​
gateway connect

One-command managed onboarding that ensures gateway health (auto-starts if needed) and starts the pairing bridge in daemon mode.

​
Usage

sigilum gateway connect \
  --session-id <id> \
  --pair-code <code> \
  --namespace <namespace> \
  [options]

​
Required Options

OptionDescription
--session-id <id>Dashboard pairing session ID
--pair-code <code>Dashboard pairing code
--namespace <namespace>Target namespace

​
Optional Options

OptionDefaultDescription
--api-url <url>https://api.sigilum.idSigilum API base URL
--gateway-admin-url <url>http://127.0.0.1:38100Local gateway admin URL
--reconnect-ms <ms>2000WebSocket reconnect delay
--connect-timeout-ms <ms>5000Connection timeout
--gateway-start-timeout-seconds <n>-Wait for gateway health timeout
--lifecycle-mode <mode>autoDaemon lifecycle: auto, stable, compat

​
Examples

Connect gateway to managed dashboard: 
sigilum gateway connect \
  --session-id abc123def456 \
  --pair-code XY7Z9W \
  --namespace johndee \
  --api-url https://api.sigilum.id
Output: 
[i] sigilum 1.0.0 (gateway)
[ok] Gateway is running at http://127.0.0.1:38100
[ok] Starting pairing bridge in daemon mode...
Gateway pair bridge started in background.
  pid:      12345
  pid_file: /home/user/.sigilum/run/gateway-pair-bridge.pid
  log_file: /home/user/.sigilum/run/gateway-pair-bridge.log
Connect with custom gateway URL: 
sigilum gateway connect \
  --session-id abc123 \
  --pair-code XY7Z9W \
  --namespace johndee \
  --gateway-admin-url http://192.168.1.10:38100

​
Lifecycle Modes

  • auto (default): Use systemd user service on Linux if available, otherwise fallback to compat mode
  • stable: Require systemd user service (Linux only)
  • compat: Use nohup or setsid for background process

​
gateway pair

Start the local WebSocket bridge used by dashboard pairing mode. This command establishes a persistent connection between your local gateway and the dashboard.

​
Usage

# Foreground mode (default)
sigilum gateway pair \
  --session-id <id> \
  --pair-code <code> \
  --namespace <namespace>

# Daemon mode
sigilum gateway pair --daemon \
  --session-id <id> \
  --pair-code <code> \
  --namespace <namespace>

# Status and control
sigilum gateway pair --status
sigilum gateway pair --stop

​
Required Options

OptionDescription
--session-id <id>Dashboard pairing session ID
--pair-code <code>Dashboard pairing code (6 characters)
--namespace <namespace>Target namespace

​
Optional Options

OptionDefaultDescription
--api-url <url>Auto-detectedSigilum API base URL
--gateway-admin-url <url>http://127.0.0.1:38100Local gateway admin endpoint
--reconnect-ms <ms>2000WebSocket reconnect delay
--connect-timeout-ms <ms>5000HTTP/WebSocket timeout
--heartbeat-ms <ms>-WebSocket heartbeat interval
--relay-timeout-ms <ms>-Relay command timeout

​
Daemon Options

OptionDescription
--daemonRun bridge in background
--foregroundForce foreground mode (default)
--lifecycle-mode <mode>Lifecycle mode: auto, stable, compat
--log-file <path>Daemon log file
--pid-file <path>Daemon pid file
--statusPrint daemon status
--stopStop daemon process

​
Examples

Start pairing bridge in foreground: 
sigilum gateway pair \
  --session-id abc123def456 \
  --pair-code XY7Z9W \
  --namespace johndee
Output: 
[i] sigilum 1.0.0 (gateway)
[ok] Connecting to pairing session...
[ok] WebSocket connected
[ok] Pairing bridge ready
Keep this process running while dashboard setup is active.
Start in daemon mode: 
sigilum gateway pair --daemon \
  --session-id abc123def456 \
  --pair-code XY7Z9W \
  --namespace johndee
Output: 
[i] sigilum 1.0.0 (gateway)
Gateway pair bridge started in background.
  pid:      12345
  pid_file: /home/user/.sigilum/run/gateway-pair-bridge.pid
  log_file: /home/user/.sigilum/run/gateway-pair-bridge.log
Check daemon status: 
sigilum gateway pair --status
Output: 
Gateway pair bridge is running (pid=12345).
  pid_file: /home/user/.sigilum/run/gateway-pair-bridge.pid
  log_file: /home/user/.sigilum/run/gateway-pair-bridge.log
Stop daemon: 
sigilum gateway pair --stop
Output: 
Stopped gateway pair bridge (pid=12345).

​
Systemd Integration (Linux)

On Linux systems with systemd user service support, the daemon mode automatically creates and manages a systemd unit at ~/.config/systemd/user/sigilum-gateway-pair.service. View systemd logs: 
journalctl --user -u sigilum-gateway-pair.service -n 200 --no-pager
Manual systemd control: 
systemctl --user status sigilum-gateway-pair
systemctl --user restart sigilum-gateway-pair
systemctl --user stop sigilum-gateway-pair

​
Pairing Workflow

  1. Start your gateway with sigilum gateway start --namespace johndee
  2. In the dashboard, click “Start Pairing” to generate a session ID and pair code
  3. Run the connect command shown in the dashboard
  4. The bridge establishes a WebSocket connection and relays dashboard commands to your local gateway
  5. Complete provider setup in the dashboard
  6. The bridge automatically exits when pairing is complete

​
Important Notes

  • The --api-url must point to the Sigilum API service, not the dashboard app
    • Managed default: https://api.sigilum.id
    • Local OSS default: http://127.0.0.1:8787
  • Local gateway admin must be running on --gateway-admin-url for pairing relay to work
  • Namespace-owner JWT is not required for gateway pairing
  • Pairing sessions expire after a period of inactivity

​
Environment Variables

All gateway commands recognize these environment variables:
VariableDescription
SIGILUM_NAMESPACEDefault namespace
GATEWAY_SIGILUM_NAMESPACEGateway-specific namespace
GATEWAY_SIGILUM_HOMEGateway home directory
SIGILUM_API_URLAPI base URL
SIGILUM_REGISTRY_URLAlternative API URL
GATEWAY_ADDRGateway listen address
GATEWAY_ADMIN_URLGateway admin endpoint URL
GATEWAY_MASTER_KEYGateway master encryption key
GATEWAY_DATA_DIRGateway data directory

​
Troubleshooting

​
Gateway won’t start

Check if the port is already in use: 
lsof -i :38100
Use a different port: 
sigilum gateway start --namespace johndee --addr :38101

​
Pairing fails to connect

Verify gateway is running: 
curl http://127.0.0.1:38100/health
Check pairing bridge logs: 
tail -f ~/.sigilum/run/gateway-pair-bridge.log

​
Session expired error

Pairing sessions expire after inactivity. Start a new pairing session in the dashboard and use the new session ID and pair code.

​
Next Steps

OpenClaw Commands

Integrate with OpenClaw agents

Service Management

Add and configure services