docs/CONFIGURATION.md

Configuration Reference

Complete guide to all Sovereign Engine configuration options.

EngineConfig Dataclass

The EngineConfig controls all engine behavior. Pass it to SovereignEngine():

from pathlib import Path
from src.sovereign import EngineConfig, SovereignEngine

config = EngineConfig(
    allowed_roots=[Path("/safe/paths")],
    ledger_path=Path("./sovereign.worm"),
    continuity_dir=Path.home() / ".sovereign" / "continuity",
    max_steps=15,
    enable_shadow=True,
    enable_ipc=True,
    agent_id="sovereign_main"
)
engine = SovereignEngine(config)

Configuration Options

Option	Type	Default	Description
allowed_roots	list[Path]	[Path.cwd()]	Filesystem roots the engine can access. PathJail blocks all others.
ledger_path	Path	./sovereign.worm	Binary WORM ledger file for cryptographic audit trail.
continuity_dir	Path	~/.sovereign/continuity	Directory for all four continuity backends. Auto-created.
max_steps	int	15	Max reasoning steps in ReActAgent loop before timeout.
enable_shadow	bool	True	Enable ShadowAgent for non-blocking observation.
enable_ipc	bool	True	Enable native IPC multiplexer (O(1) tool dispatch).
agent_id	str	"sovereign_main"	Unique agent identifier (for multi-agent coordination).

Environment Variables

Override config via environment variables (prefixed with SOVEREIGN_):

export SOVEREIGN_ALLOWED_ROOTS="/home/user/projects:/tmp"
export SOVEREIGN_MAX_STEPS=25
export SOVEREIGN_ENABLE_SHADOW=false
export SOVEREIGN_AGENT_ID="batch_processor_1"

python your_script.py

Supported environment variables:

Variable	Type	Maps To
SOVEREIGN_ALLOWED_ROOTS	CSV paths	allowed_roots (split on : or ;)
SOVEREIGN_LEDGER_PATH	path	ledger_path
SOVEREIGN_CONTINUITY_DIR	path	continuity_dir
SOVEREIGN_MAX_STEPS	int	max_steps
SOVEREIGN_ENABLE_SHADOW	bool	enable_shadow (true/false/1/0)
SOVEREIGN_ENABLE_IPC	bool	enable_ipc
SOVEREIGN_AGENT_ID	str	agent_id

Example:

import os
from src.sovereign import SovereignEngine

# Environment variables take precedence
if "SOVEREIGN_MAX_STEPS" in os.environ:
    max_steps = int(os.environ["SOVEREIGN_MAX_STEPS"])
else:
    max_steps = 15

ReActAgent Config

The ReAct reasoning agent has its own config:

from src.agents.react import ReActConfig, ReActAgent

react_config = ReActConfig(
    max_steps=20,
    timeout_ms=60000,
    model_provider="bedrock",  # bedrock, openrouter, ollama, anthropic
    temperature=0.7,
    top_p=0.9,
)

agent = ReActAgent(
    agent_id="code_agent",
    config=react_config,
    registry=tool_registry,
    ledger=worm_ledger,
)

Option	Type	Default	Description
max_steps	int	15	Max thinking/action loops.
timeout_ms	int	30000	Total execution timeout.
model_provider	str	"bedrock"	LLM backend: bedrock, openrouter, ollama, anthropic.
temperature	float	0.7	Sampling temperature (0.0-1.0).
top_p	float	0.9	Nucleus sampling parameter.

Continuity Directory Structure

The engine uses 4 paradigms for state recovery. Structure:

~/.sovereign/continuity/
├── env_state.bin                # Paradigm 1: Env bitmask (for hot-restart)
├── seed.bin                     # Paradigm 2: Seed for deterministic replay
├── agent_id_seed.bin            # Paradigm 2 per-agent seed
├── inode/
│   ├── flags.db                 # Paradigm 3: File handles mapped to boolean gates
│   ├── agent_id.lock
│   └── agent_id.state
├── shm/
│   └── block_0.bin              # Paradigm 4: Shared memory block (4KB)
└── checkpoints/
    ├── checkpoint_001.ckpt      # Full state snapshot with signature
    ├── checkpoint_002.ckpt
    └── manifest.json

Paradigm 1: Env State — 64-bit bitmask in os.environ["SOVEREIGN_STATE"]:

• Fastest (RAM)
• Lost on process exit
• Use for: hot-restart via os.execv()

Paradigm 2: Seed Chain — Blake2b seed derivation:

• Deterministic replay
• Store operation log in binary
• Use for: replay testing, timeline forking

Paradigm 3: Inode State — Zero-byte files as gates:

• Kernel-durable
• Fast stat() reads
• Use for: boolean flags, pause/resume

Paradigm 4: Shared Memory — ctypes mmap block:

• Cross-process coordination
• 4KB block
• Use for: multi-agent sync, realtime state

PathJail Configuration

Restrict filesystem access to approved roots:

from src.core.path_jail import PathJail
from pathlib import Path

jail = PathJail(roots=[
    Path("/home/user/projects"),
    Path("/tmp/scratch"),
    Path.home() / "Downloads"
])

# This is OK
jail.check("/home/user/projects/code.py")  # ✓

# This is BLOCKED
jail.check("/etc/passwd")                   # ✗ PathJailError
jail.check("/root/.ssh/id_rsa")             # ✗ PathJailError

Pass to engine:

config = EngineConfig(
    allowed_roots=[
        Path("/home/user/projects"),
        Path("/tmp/scratch"),
    ]
)
engine = SovereignEngine(config)

Model Provider Configuration

Choose which LLM backend to use. Defaults to AWS Bedrock (all models via unified API).

Bedrock (Recommended)

from src.sovereign import EngineConfig
from src.runtime.providers.bedrock import BedrockProvider

config = EngineConfig()
provider = BedrockProvider(
    region="us-west-2",
    model="anthropic.claude-3-opus-20240229-v1:0",
)

# Engine automatically uses it
engine = SovereignEngine(config)

Requires ~/.aws/credentials:

[default]
aws_access_key_id = YOUR_KEY
aws_secret_access_key = YOUR_SECRET
region = us-west-2

OpenRouter (Open-source + proprietary models)

from src.runtime.providers.openrouter import OpenRouterProvider

provider = OpenRouterProvider(api_key="sk-or-...")
# Uses OpenRouter API for Mistral, Llama, Qwen, etc.

Requires OPENROUTER_API_KEY environment variable.

Ollama (Local models)

from src.runtime.providers.ollama import OllamaProvider

provider = OllamaProvider(base_url="http://localhost:11434")
# Connect to local Ollama instance (ollama serve)

Run locally first:

ollama run mistral
# or
ollama run llama2

Anthropic API (Direct)

from src.runtime.providers.anthropic import AnthropicProvider

provider = AnthropicProvider(api_key="sk-ant-...")

Example Configurations

Development Mode

Minimal logging, fast iteration:

from src.sovereign import EngineConfig
from pathlib import Path
import logging

logging.basicConfig(level=logging.DEBUG)

config = EngineConfig(
    allowed_roots=[Path.cwd()],
    ledger_path=Path("/tmp/dev.worm"),
    continuity_dir=Path("/tmp/continuity"),
    max_steps=10,  # Fast iteration
    enable_shadow=False,
)

Production Mode

Full logging, durability, multi-agent:

config = EngineConfig(
    allowed_roots=[
        Path("/var/app/data"),
        Path("/var/app/cache"),
    ],
    ledger_path=Path("/var/lib/sovereign/ledger.worm"),
    continuity_dir=Path("/var/lib/sovereign/continuity"),
    max_steps=25,  # More thinking
    enable_shadow=True,  # Async observation
    enable_ipc=True,  # Native IPC
    agent_id="prod_reactor_1",
)

With Bedrock:

from src.runtime.providers.bedrock import BedrockProvider

provider = BedrockProvider(
    region="us-east-1",
    model="anthropic.claude-3-sonnet-20240229-v1:0",
    timeout_ms=120000,
)

CI Testing Mode

Fast, deterministic, no external calls:

config = EngineConfig(
    allowed_roots=[Path("/tmp/ci_test")],
    ledger_path=Path("/tmp/ci.worm"),
    continuity_dir=Path("/tmp/ci_continuity"),
    max_steps=5,
    enable_shadow=False,
    enable_ipc=False,  # Use pure Python
    agent_id=f"ci_test_{os.getenv('CI_BUILD_ID')}",
)

Use mock provider for testing:

from src.runtime.providers.multi import MultiProvider

# Fallback chain: try each in order
provider = MultiProvider([
    MockProvider(),      # Return fixed responses
    OllamaProvider(),   # Fall back to local if available
])

Logging Configuration

Control verbosity via Python logging:

import logging

# Engine logs
logging.getLogger("sovereign.engine").setLevel(logging.INFO)

# Routing pipeline
logging.getLogger("sovereign.routing").setLevel(logging.DEBUG)

# Tool registry
logging.getLogger("sovereign.tools").setLevel(logging.WARNING)

# Everything
logging.basicConfig(
    level=logging.DEBUG,
    format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)

Dynamic Configuration Updates

Update config without restarting:

engine = SovereignEngine(config)

# Update max_steps
engine.config.max_steps = 25

# Restart agent with new config
from src.agents.react import ReActConfig
engine.agent.config.max_steps = 25

# Add a new allowed root
engine.config.allowed_roots.append(Path("/new/path"))
engine.path_jail = PathJail(roots=engine.config.allowed_roots)

Configuration Validation

Validate config before starting engine:

from src.sovereign import EngineConfig
from pathlib import Path

config = EngineConfig(
    allowed_roots=[Path("/tmp/test")],
)

# Check roots exist
for root in config.allowed_roots:
    if not root.exists():
        root.mkdir(parents=True, exist_ok=True)

# Check continuity dir writable
try:
    config.continuity_dir.mkdir(parents=True, exist_ok=True)
    (config.continuity_dir / ".test").touch()
    (config.continuity_dir / ".test").unlink()
except PermissionError:
    raise RuntimeError(f"Cannot write to {config.continuity_dir}")