Quickstart: Self-Hosted / Local Development

OSS-Local mode runs the open-source Sigilum API and gateway locally—no hosted services required. Use this for local development, testing, or fully self-hosted deployments.

Prerequisites

Node.js

Version 20 or higher

pnpm

Version 10.29.3 (installed via Corepack)

Go

Version 1.23 or higher

Python

Version 3.11+ (optional, for Python SDK tests)

Installation

Clone the repository

git clone https://github.com/PaymanAI/sigilum.git
cd sigilum

Bootstrap dependencies

Enable Corepack and install dependencies:

corepack enable && corepack prepare [email protected] --activate
pnpm install
pnpm --dir sdks/sdk-ts build

This installs all monorepo dependencies and builds the TypeScript SDK, which is required for the API and other packages.

Start the local stack

./sigilum up

This starts:

Sigilum API on http://127.0.0.1:8787
Sigilum Gateway on http://127.0.0.1:38100

By default, gateway binaries are prebuilt to ./.local/bin/ to reduce memory pressure. Set GATEWAY_BUILD_BINARIES=false to force go run mode for fast iteration.

Verify the stack is running

Check API health:

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

Check gateway health:

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

Both should return {"status":"ok"}

Low-Memory Environments

If you’re running in a constrained environment (e.g., 4 GB Docker container, OpenClaw instance), you may hit OOM errors on first run.

To avoid this, build gateway binaries separately before starting the stack:

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)
./sigilum up

Configuration

Set Source Home for Global CLI

If you installed the sigilum CLI globally but want to use local API workflows:

export SIGILUM_SOURCE_HOME="$(pwd)"

Add this to your .zshrc or .bashrc to make it permanent.

Working with Services

Register a Native Service

Native services are Sigilum-aware—they verify signatures directly:

./sigilum service add \
  --service-slug my-native-service \
  --service-name "My Native Service" \
  --mode native

Register a Gateway-Routed Service

Gateway-routed services use the gateway as a proxy (for existing APIs like OpenAI, Linear, etc.):

export LINEAR_TOKEN="lin_api_..."
./sigilum service add \
  --service-slug linear \
  --service-name "Linear" \
  --mode gateway \
  --upstream-base-url https://api.linear.app \
  --auth-mode bearer \
  --upstream-secret-env LINEAR_TOKEN

List Services

./sigilum service list --namespace johndee

OpenClaw Integration

Install Sigilum hooks and agent key bootstrap for OpenClaw:

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

In oss-local mode, the installer:

Auto-issues a local namespace-owner JWT
Prints the dashboard URL
Prints the passkey setup URL for attaching a passkey to the seeded namespace

Verify OpenClaw Status

./sigilum openclaw status

Testing

Run End-to-End Tests

./sigilum e2e-tests

This:

Boots demo services
Seeds test authorization state
Runs the agent simulator to verify:
- Signed approved requests succeed
- Unsigned requests are rejected
- Signed unapproved requests fail

Run Diagnostics

./sigilum doctor

Local Data Paths

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

Don’t commit these directories. They contain local identities, keys, and database state. They’re already in .gitignore.

Managing the Stack

Stop the Stack

./sigilum down

Restart Services

./sigilum down
./sigilum up

View Logs

tail -f ./apps/api/.wrangler/logs/wrangler.log

Authentication Management

Issue/Refresh Local Owner JWT

./sigilum auth refresh --mode oss-local --namespace johndee

Show Stored Token

./sigilum auth show --namespace johndee

In oss-local mode, owner JWTs are issued locally with no passkey requirement. This is for development only—never use this mode in production.

Development Workflows

Fast Iteration on Gateway

For rapid gateway development, use go run mode:

export GATEWAY_BUILD_BINARIES=false
./sigilum down
./sigilum up

Changes to gateway code will be reflected immediately (no rebuild needed).

Fast Iteration on API

The API runs via Wrangler in dev mode—changes are hot-reloaded automatically. Edit files in apps/api/src/ and refresh your browser.

Testing SDK Changes

After modifying the TypeScript SDK:

pnpm --dir sdks/sdk-ts build
./sigilum down
./sigilum up

Running SDK Tests

pnpm --dir sdks/sdk-ts test

Architecture

In OSS-local mode: Everything runs locally:

Sigilum API: Cloudflare Workers via Wrangler with local D1 SQLite
Sigilum Gateway: Go binary with BadgerDB for local storage
Your Agent: Test agent or SDK integration tests
CLI: ./sigilum wrapper script for local workflows

Next Steps

Explore the API

Learn the REST API for approvals, revocations, and authorization management

Build with SDKs

Integrate Sigilum signing into your agents with TypeScript, Python, or Go

CLI Reference

Complete command reference for the sigilum CLI

Protocol Specs

DID method specification and SDK signing profile

Troubleshooting

Port already in use

If port 8787 or 38100 is already in use:

# Find process using port 8787
lsof -i :8787

# Find process using port 38100
lsof -i :38100

# Kill the process (replace PID)
kill -9 <PID>

Build failures

Ensure you’re using the correct Node.js version:
```
node --version  # Should be >= 20
```

Clean and reinstall:

rm -rf node_modules pnpm-lock.yaml
pnpm install
pnpm --dir sdks/sdk-ts build

Check Go version:
```
go version  # Should be >= 1.23
```

OOM errors

If you see out-of-memory errors:

Build gateway binaries separately (see “Low-Memory Environments” above)

Reduce concurrent processes:

export NODE_OPTIONS="--max-old-space-size=4096"

Close other applications to free up RAM

Gateway won't start

Check if BadgerDB is locked:
```
rm -rf ./.local/gateway-data/LOCK
```

Rebuild gateway:

cd apps/gateway/service
go build -o ../../../.local/bin/sigilum-gateway ./cmd/sigilum-gateway

Check logs:
```
./sigilum gateway logs
```

API database errors

Reset the local D1 database:

rm -rf ./apps/api/.wrangler/state/
./sigilum down
./sigilum up

This deletes all local authorization state. You’ll need to re-register services and re-approve agents.

Repository Structure

├── apps/
│   ├── api/          # Sigilum API (Cloudflare Workers)
│   └── gateway/      # Sigilum Gateway (Go)
├── config/           # Shared TypeScript config (@sigilum/config)
├── contracts/        # Smart contracts (Foundry)
├── docs/             # Project documentation
├── openclaw/         # OpenClaw integration (hooks, skills, installer)
├── releases/         # Release artifacts and metadata
└── sdks/             # Language SDKs (TS, Python, Go; Java placeholder)

Key Files

./sigilum: Main CLI wrapper for local workflows
apps/api/wrangler.toml: Wrangler configuration for local API
apps/gateway/service/: Go source for gateway
sdks/sdk-ts/: TypeScript SDK (built to dist/)
./.sigilum-workspace/: Local identities and keys (git-ignored)
./.local/gateway-data/: Gateway database (git-ignored)

Learn More

API Reference: Full REST API documentation
Gateway Reference: Gateway configuration and admin API
Protocol Specs: DID method and signing profile
Contributing: How to contribute to Sigilum
Manifesto: Why Sigilum exists

Get Started

Core Concepts

Components

SDKs

Integrations

​Prerequisites

Node.js

pnpm

Go

Python

​Installation

​Low-Memory Environments

​Configuration

​Set Source Home for Global CLI

​Working with Services

​Register a Native Service

​Register a Gateway-Routed Service

​List Services

​OpenClaw Integration

​Verify OpenClaw Status

​Testing

​Run End-to-End Tests

​Run Diagnostics

​Local Data Paths

​Managing the Stack

​Stop the Stack

​Restart Services

​View Logs

​Authentication Management

​Issue/Refresh Local Owner JWT

​Show Stored Token

​Development Workflows

​Fast Iteration on Gateway

​Fast Iteration on API

​Testing SDK Changes

​Running SDK Tests

​Architecture

​Next Steps

Explore the API

Build with SDKs

CLI Reference

Protocol Specs

​Troubleshooting

​Repository Structure

​Key Files

​Learn More

Build docs developers (and LLMs) love

Prerequisites

Installation

Low-Memory Environments

Configuration

Set Source Home for Global CLI

Working with Services

Register a Native Service

Register a Gateway-Routed Service

List Services

OpenClaw Integration

Verify OpenClaw Status

Testing

Run End-to-End Tests

Run Diagnostics

Local Data Paths

Managing the Stack

Stop the Stack

Restart Services

View Logs

Authentication Management

Issue/Refresh Local Owner JWT

Show Stored Token

Development Workflows

Fast Iteration on Gateway

Fast Iteration on API

Testing SDK Changes

Running SDK Tests

Architecture

Next Steps

Troubleshooting

Repository Structure

Key Files

Learn More