Deployment Modes

Sigilum supports three deployment modes to fit different operational and security requirements. Each mode offers different tradeoffs between convenience, control, and infrastructure management.

Deployment Modes Comparison

Mode	Control Plane	Gateway	Use Case	Provider Secrets
Managed	Hosted at api.sigilum.id	Customer-side (local/VM/VPC)	Recommended. Production use with hosted control plane	Local in your gateway
Enterprise	Self-hosted (your infrastructure)	Self-hosted (your infrastructure)	Full on-prem or private network deployment	Local in your gateway
OSS-Local	Local (open-source API)	Local (same machine)	Development, testing, and evaluation	Local in your gateway

In all deployment modes, provider credentials remain local in your gateway. The control plane never sees or stores your API keys, tokens, or secrets.

Managed Mode

Recommended for production use. Managed mode uses Sigilum’s hosted control plane while keeping the gateway (and your secrets) on your infrastructure.

Architecture

Characteristics

Control Plane (Hosted by Sigilum):

User authentication and namespace management
Authorization request approval workflow
Service registration and API key management
Webhook delivery and notifications
Blockchain audit log writes
DID resolution and verification endpoints

Data Plane (Your Infrastructure):

Gateway runs on your VM, VPS, or local machine
All provider credentials stored locally
Request signature verification
Approved claims cache
Provider credential injection
Request proxying to upstream APIs

Setup

Sign up and reserve namespace: Visit sigilum.id and create an account.

Install CLI and start gateway:

curl -fsSL https://github.com/PaymanAI/sigilum/releases/latest/download/install-curl.sh | bash
source ~/.zshrc
sigilum gateway start --namespace your-namespace

Connect gateway to dashboard: In the dashboard, click Start Pairing and run:

sigilum gateway connect \
  --session-id <session-id> \
  --pair-code <pair-code> \
  --namespace your-namespace \
  --api-url https://api.sigilum.id

Add providers: Use the dashboard to configure provider connections. Secrets are encrypted and stored locally.
Configure agent: Point your agent to http://127.0.0.1:38100 for proxied requests.

Gateway Pairing

Managed mode uses a pairing bridge to connect your local gateway to the hosted dashboard: Pairing Commands:

# Check pairing status
sigilum gateway pair --status

# Stop pairing bridge
sigilum gateway pair --stop

The pairing bridge runs as a daemon process that maintains a persistent WebSocket connection to the API. It relays admin commands from the dashboard to your local gateway without exposing the gateway’s admin API to the internet.

Benefits

Zero Infrastructure

No need to deploy, maintain, or scale the control plane

Automatic Updates

Control plane updates and improvements without manual intervention

Managed Availability

SLA-backed uptime for control plane services

Secrets Stay Local

Provider credentials never leave your infrastructure

When to Use

Production applications - Proven, hosted control plane
Fast onboarding - Get started in minutes
Focus on agent logic - Let Sigilum handle infrastructure
SaaS/cloud deployments - VPS, VM, or container-based agents

The gateway must be able to make HTTPS requests to api.sigilum.id. Ensure your firewall allows outbound HTTPS (port 443) from the gateway.

Enterprise Mode

Full self-hosted deployment for on-premises or private networks. Enterprise mode runs both control plane and data plane on your infrastructure.

Architecture

Characteristics

Control Plane (Your Infrastructure):

Deploy Sigilum API (Cloudflare Workers or adapter-compatible runtime)
Host dashboard (static site or behind reverse proxy)
Manage database (D1, PostgreSQL, or compatible)
Optional: Run blockchain node or use public network

Data Plane (Your Infrastructure):

Deploy one or more gateways
Configure network policies and firewalls
Manage gateway secrets and encryption keys
Control all data flows

Setup

Deploy control plane:

# Clone repository
git clone https://github.com/PaymanAI/sigilum.git
cd sigilum

# Configure API
cd apps/api
cp .dev.vars.example .dev.vars
# Edit .dev.vars with your configuration

# Deploy to your infrastructure
pnpm --filter @sigilum/api build
pnpm --filter @sigilum/api deploy

Deploy dashboard: Build and deploy the dashboard to your static hosting or CDN.

Configure gateway:

# Set API URL to your private control plane
export SIGILUM_REGISTRY_URL="https://your-api.internal"
export SIGILUM_SERVICE_API_KEY="<your-service-key>"
export GATEWAY_MASTER_KEY="<your-master-key>"

# Start gateway
sigilum gateway start --namespace your-namespace

Configure networking: Ensure gateways can reach your control plane API:
- Internal DNS or service discovery
- VPN or private network connectivity
- mTLS or VPC peering (optional)

Required Infrastructure

Component	Requirements
API Runtime	Cloudflare Workers, Node.js server, or adapter-compatible runtime
Database	D1, PostgreSQL, MySQL, or compatible SQL database
Dashboard	Static hosting (S3, Cloudflare Pages, Netlify) or web server
Gateway	VM, container, or bare metal with Go runtime
Blockchain (optional)	Ethereum-compatible node or public RPC endpoint

Benefits

Complete Control

Full ownership of data, infrastructure, and deployment

Private Network

Keep all traffic within your network perimeter

Custom Policies

Implement organization-specific compliance and security policies

Air-Gapped Option

Deploy without internet connectivity (blockchain optional)

When to Use

Regulated industries - Healthcare, finance, government
Data sovereignty - Keep all data in specific regions/jurisdictions
Private networks - Air-gapped or restricted network environments
Custom compliance - Organization-specific audit or security requirements

Enterprise mode requires infrastructure expertise to deploy, maintain, and scale the control plane. Consider managed mode if infrastructure management is not a priority.

OSS-Local Mode

Local development and testing with open-source components. OSS-Local mode runs the entire stack locally on a single machine.

Architecture

Characteristics

All Components Local:

API runs on http://127.0.0.1:8787 (Wrangler dev server)
Gateway runs on http://127.0.0.1:38100
SQLite database in .wrangler/state/
BadgerDB secrets store in .local/gateway-data/
No dashboard required (optional)

Setup

Clone and install:

git clone https://github.com/PaymanAI/sigilum.git
cd sigilum
corepack enable && corepack prepare [email protected] --activate
pnpm install
pnpm --dir sdks/sdk-ts build

Start the local stack:
```
./sigilum up
```
This starts:
- API on http://127.0.0.1:8787
- Gateway on http://127.0.0.1:38100

Verify health:

curl -sf http://127.0.0.1:8787/health
curl -sf http://127.0.0.1:38100/health

Register services:

export OPENAI_API_KEY="sk-..."
./sigilum service add \
  --service-slug openai \
  --service-name "OpenAI" \
  --mode gateway \
  --upstream-base-url https://api.openai.com \
  --auth-mode bearer \
  --upstream-secret-env OPENAI_API_KEY

Run tests:
```
./sigilum e2e-tests
```

Local Data Paths

Path	Contents
`./.sigilum-workspace`	Workspace identities and bootstrap keys
`./.local/gateway-data`	Gateway BadgerDB data store
`./.local/bin`	Prebuilt gateway binaries
`./apps/api/.wrangler/state/`	API D1 SQLite database files

CLI Helpers

The ./sigilum wrapper script provides local stack management:

./sigilum up                    # Start API + gateway
./sigilum down                  # Stop all services
./sigilum service add           # Register a service
./sigilum service list          # List services
./sigilum e2e-tests            # Run end-to-end tests
./sigilum doctor               # Check local stack health
./sigilum doctor --fix         # Auto-fix common issues
./sigilum auth refresh         # Issue local owner JWT

Benefits

Fast Iteration

Immediate feedback loop for development and testing

No Cloud Dependencies

Develop offline or without external services

Complete Transparency

Inspect all components, data, and flows locally

Open Source

Full access to all source code and implementation

When to Use

Development - Build and test agent integrations locally
Testing - Automated tests, CI/CD pipelines
Evaluation - Understand Sigilum architecture and behavior
Contribution - Develop features or fixes for Sigilum
Learning - Study the implementation and protocols

OSS-Local mode is not intended for production use. The local API lacks durability, scalability, and security hardening required for production workloads.

Low-Memory Environments

If running in constrained environments (e.g., 4GB Docker containers):

# Pre-build gateway binaries to reduce memory pressure
mkdir -p ./.local/bin
(cd apps/gateway/service && go build -o ../../../.local/bin/sigilum-gateway ./cmd/sigilum-gateway)
(cd apps/gateway/service && go build -o ../../../.local/bin/sigilum-gateway-cli ./cmd/sigilum-gateway-cli)

# Then start normally
./sigilum up

Or force go run mode:

GATEWAY_BUILD_BINARIES=false ./sigilum up

OpenClaw Integration

Sigilum provides streamlined integration with OpenClaw for each deployment mode.

Managed Mode

sigilum openclaw connect \
  --session-id <session-id> \
  --pair-code <pair-code> \
  --namespace your-namespace \
  --api-url https://api.sigilum.id

This performs:

Gateway connection and pairing
OpenClaw hook installation
Agent key bootstrap

Enterprise Mode

sigilum openclaw install \
  --mode managed \
  --namespace your-namespace \
  --api-url https://your-api.internal

Configure with your private API URL.

OSS-Local Mode

./sigilum openclaw install \
  --mode oss-local \
  --namespace your-namespace \
  --api-url http://127.0.0.1:8787

Auto-issues local namespace owner JWT for testing.

Choosing a Deployment Mode

Decision Matrix

Requirement	Managed	Enterprise	OSS-Local
Production readiness	✅	✅	❌
Minimal infrastructure	✅	❌	✅
Private network only	❌	✅	✅
Air-gapped deployment	❌	✅	✅
Fast setup	✅	❌	✅
Automatic updates	✅	❌	N/A
Full source access	✅	✅	✅
Custom compliance	⚠️	✅	N/A
Development/testing	⚠️	⚠️	✅

Recommendation: Start with Managed Mode for production and OSS-Local Mode for development. Migrate to Enterprise Mode only if you have specific on-premises or compliance requirements.

Migration Between Modes

Managed → Enterprise

Export identities and configurations
Deploy private control plane
Reconfigure gateways to point to private API
Import identities and service registrations

OSS-Local → Managed/Enterprise

Export local identities
Register namespace in production
Import agent keys
Resubmit authorization claims

Agent identities (key pairs) are portable across deployment modes. The same agent keys can be used in any mode by updating the API URL configuration.

Next Steps

Managed Quickstart

Get started with managed mode in minutes

Self-Hosted Guide

Set up OSS-Local mode for development

Gateway Configuration

Configure gateway settings for your deployment

Architecture

Learn about control plane and data plane separation

Get Started

Core Concepts

Components

SDKs

Integrations