Skip to main content
Managed mode uses the hosted Sigilum control plane at sigilum.id. Your gateway runs where your agent runs (DigitalOcean, AWS, VPS, local machine, etc.). Provider secrets stay in your gateway.
This is the recommended setup path for production use.

​
Prerequisites

  • A machine where your AI agent runs (local, VPS, cloud instance)
  • Linux, macOS, or WSL2 on Windows
  • Internet access to sigilum.id and api.sigilum.id

​
Installation

1

Sign in and reserve your namespace

  1. Open sigilum.id
  2. Create an account or sign in
  3. Reserve a namespace (e.g., johndee)
Your namespace is your unique identifier in the Sigilum network. Choose carefully—it will be part of your agent identities.
2

Install the Sigilum CLI

Run this command on the machine where your agent runs:
curl -fsSL https://github.com/PaymanAI/sigilum/releases/latest/download/install-curl.sh | bash
Reload your shell configuration:
source ~/.zshrc
Verify installation:
sigilum --help
The installer downloads the latest release binary for your platform (Linux/macOS, AMD64/ARM64) and places it in ~/.sigilum/bin/.
3

Start the local gateway

sigilum gateway start --namespace johndee
What happens here:
  • If identity doesn’t exist, the gateway auto-bootstraps it
  • The gateway starts on http://127.0.0.1:38100
  • No JWT is required for gateway start or pairing
  • Provider secrets are stored locally in your gateway (never sent to Sigilum API)
Verify the gateway is running:
curl -fsS http://127.0.0.1:38100/health
Expected response:
{"status":"ok"}
4

Connect gateway to dashboard

  1. Go to the Sigilum Dashboard
  2. Click Start Pairing
  3. Copy the pairing command shown
  4. Run it in your terminal:
sigilum gateway connect \
  --session-id <session-id> \
  --pair-code <pair-code> \
  --namespace johndee \
  --api-url https://api.sigilum.id
gateway connect ensures the gateway is running and healthy, then starts the pairing bridge in daemon mode.
Check pairing status:
sigilum gateway pair --status
To stop the pairing daemon:
sigilum gateway pair --stop
5

Add provider connections

In the Sigilum Dashboard, navigate to Providers and add your provider credentials:
  • OpenAI: API key for GPT models
  • Linear: API key for issue tracking
  • Anthropic: API key for Claude models
  • Custom providers: Any API you want to proxy through Sigilum
Provider secrets are stored locally in your gateway, not in the Sigilum API. The dashboard UI sends credentials directly to your gateway via the pairing bridge.
6

Verify your setup

Run diagnostics:
sigilum doctor
This checks:
  • Gateway health
  • Pairing bridge status
  • Identity configuration
  • Network connectivity to Sigilum API
Use sigilum doctor --json for machine-readable output or sigilum doctor --fix to auto-remediate common issues.

​
Optional: OpenClaw Integration

If you’re using OpenClaw, you can onboard with a single command: 
sigilum openclaw connect \
  --session-id <session-id> \
  --pair-code <pair-code> \
  --namespace johndee \
  --api-url https://api.sigilum.id
This performs:
  1. sigilum gateway connect (pairs the gateway)
  2. sigilum openclaw install --mode managed --non-interactive (installs hooks)
  3. Immediate OpenClaw agent key bootstrap under ~/.openclaw/.sigilum/keys/
If your gateway is already paired, you can run just the OpenClaw install:
sigilum openclaw install --namespace johndee

​
Verify OpenClaw Integration

sigilum openclaw status
This shows:
  • OpenClaw installation path
  • Sigilum hooks installed
  • Agent key status
  • Gateway connection status

​
Next Steps

Integrate Your Agent

Use the TypeScript, Python, or Go SDK to add Sigilum signing to your AI agent

API Reference

Explore the full Sigilum API for approvals, revocations, and authorization management

CLI Reference

Learn all available CLI commands for gateway management and service configuration

Gateway Configuration

Advanced gateway configuration, admin API, and troubleshooting

​
Common Tasks

​
Check Gateway Health

curl -fsS http://127.0.0.1:38100/health

​
View Gateway Logs

sigilum gateway logs

​
Restart Gateway

sigilum gateway restart --namespace johndee

​
Update CLI and Gateway

curl -fsSL https://github.com/PaymanAI/sigilum/releases/latest/download/install-curl.sh | bash
sigilum gateway restart --namespace johndee

​
Troubleshooting

  1. Check if port 38100 is already in use: 
    lsof -i :38100
  2. Run diagnostics: 
    sigilum doctor --fix
  3. Check gateway logs: 
    sigilum gateway logs
  1. Verify gateway is running: 
    curl -fsS http://127.0.0.1:38100/health
  2. Check pairing status: 
    sigilum gateway pair --status
  3. Generate a new pairing code in the dashboard and try again
  1. Verify credentials are stored in gateway: 
    sigilum gateway providers list
  2. Check gateway logs for auth errors: 
    sigilum gateway logs | grep -i auth
  3. Re-add the provider in the dashboard
  1. Check network connectivity: 
    curl -fsS https://api.sigilum.id/health
  2. Verify firewall rules allow outbound HTTPS
  3. If behind a corporate proxy, configure proxy settings: 
    export HTTPS_PROXY=http://proxy.company.com:8080

​
Architecture

In managed mode:
  • Your AI Agent: Runs on your infrastructure, signs requests with Sigilum SDK
  • Sigilum Gateway: Runs locally alongside your agent, stores provider secrets
  • Provider APIs: OpenAI, Linear, Anthropic, or any custom API
  • Sigilum API: Hosted control plane manages authorization state
  • Dashboard: Web UI for approvals, revocations, and monitoring

​
Security Model

Key principle: Provider secrets never leave your gateway.
  1. Identity: Each agent gets a cryptographically verifiable DID (Decentralized Identifier)
  2. Signing: Agents sign requests with their private key (stored locally)
  3. Verification: Gateway verifies signature and checks approved claims against Sigilum API
  4. Proxy: Gateway adds provider credentials and proxies to upstream API
  5. Audit: All requests logged with full delegation chain

​
What Sigilum API Knows

  • Agent identities (DIDs)
  • Approval/revocation state
  • Request metadata (timestamp, service, endpoint)

​
What Sigilum API Never Sees

  • Provider API keys or secrets
  • Request/response payloads
  • Agent private keys

​
Learn More

Build docs developers (and LLMs) love

Get started for freeTalk to us