Runtime Topologies

Configuration And Hosting

Understand every sulcus.ini setting, environment variable, configuration lookup path, v3.1 CLI command, and deployment topology from 100% offline workstations to Docker Private VPC and Air-Gap appliances.

Embedded Postgres 17Complete CLI SuiteDocker VPC ReadyCloudflare R2 Distro
Deployment Modes

Three Runtime Topologies

The sulcus client binary runs 100% locally on your workstation at zero cost. Multi-user fleet governance runs on Sulcus Cloud or self-hosted Docker Enterprise Appliances.

Mode One

Offline Workstation

The free-forever sulcus binary embeds PostgreSQL 17 (~/.sulcus/local bound to loopback 127.0.0.1:4201 with SQL property graph traversal), runs local CPU cartridge inference and AST v2 indexing, and serves the 5-tab Local Memory Panel on 127.0.0.1:4203/panel. Set SULCUS_TELEMETRY=off with a pre-warmed PG17 and ~/.sulcus/models/fastembed ONNX cache for strict air-gapped laptops.
Mode Two

Sulcus Cloud SaaS

Point sulcus login at https://api.sulcus.ca for Enterprise OIDC SSO, TLS-encrypted HLC CRDT delta sync, external PostgreSQL 17 + Apache AGE Cypher graphs, Two-Gate Namespace ACLs, Persistent Linked Namespaces, live Agent Bus coordination, and Sulcus Studio.
Mode Three

Private VPC Enclave

For regulated organizations requiring strict data residency in self-hosted Docker clusters or air-gapped enclaves, Digital Forge ships Ed25519-signed Sulcus Enterprise Server appliances via Cloudflare R2 (backed by external PostgreSQL 17 + Apache AGE, connected_onprem OIDC SSO, or offline airgapped seat licensing).

Localhost Database Guardrail

The workstation sulcus binary is a local sidecar and MCP proxy, not a multi-tenant server. Config::validate_database_url strictly enforces that database_url and SULCUS_DATABASE_URL target 127.0.0.1 or localhost (rejecting SQLite and remote Postgres hosts). To share memory across machines, connect workstations to the Sulcus API via server_url.
Configuration Loader

Runtime Configuration Keys

Sulcus resolves sulcus.ini in strict priority order: (1) $SULCUS_CONFIG or sulcus --config <path>, (2) $XDG_CONFIG_HOME/sulcus/sulcus.ini, (3) ~/.config/sulcus/sulcus.ini, (4) platform config_dir/sulcus/sulcus.ini, (5) ~/.sulcus/sulcus.ini, and (6) /etc/sulcus/sulcus.ini. Environment variables override file values.

iniWorkstation Config File
# ~/.config/sulcus/sulcus.ini (written with 0600 permissions by sulcus login)
[sulcus]
# Remote Sulcus API endpoint (Sulcus Cloud or your Docker Private VPC / Air-Gap appliance)
server_url = "https://api.sulcus.ca"
server_api_key = "sk-..."

# Default workspace namespace when not overridden by repo slug or X-Namespace
namespace = "default"

# Optional external LOCAL PostgreSQL DSN (MUST target 127.0.0.1 or localhost; omit to use embedded PG17 on 127.0.0.1:4201)
# database_url = "postgres://postgres:postgres@127.0.0.1:5432/sulcus"

# Local daemon thermodynamic loop settings (sulcus daemon / sulcus serve / sulcus stdio)
therm_interval_ms = 1000
active_limit = 20
decay = 0.85
prune_threshold = 0.05

# Local capacity & automatic cold-node eviction
max_total_nodes = 10000
auto_purge = true
auto_purge_threshold = 0.05

# Automatic Caveman + AST v2 payload compaction on store_memory
payload_compaction = true

# Background CRDT delta sync interval when sulcus-sync is active
sync_interval_secs = 300
INI KeyDefault ValueEnvironment VariableRuntime Behavior
server_url (server)NoneSULCUS_SERVER_URL / SULCUS_BASE_URLTarget Sulcus API URL for login, mcp-proxy, hook, namespace, doctor, train --push, and IDE plugins.
server_api_key (api_key)NoneSULCUS_API_KEY / SULCUS_SERVER_API_KEYBearer credential (workstation CLI also checks SULCUS_TOKEN and macOS Keychain sulcus-cli).
namespace (agent_namespace)"default"SULCUS_NAMESPACEDefault namespace used by mcp-proxy, CLI commands, local store_memory, and harness hooks.
database_urlEmbedded PG17 (127.0.0.1:4201)SULCUS_DATABASE_URLLocal Postgres DSN. Strictly validated to 127.0.0.1 or localhost (SQLite and remote hosts rejected).
therm_interval_ms1000SULCUS_TICK_MSBackground thermodynamic tick interval (ms) for sulcus daemon, sulcus serve, and sulcus stdio.
active_limit20SULCUS_ACTIVE_LIMITMaximum nodes held in the hot active working-memory index.
decay0.85NonePer-tick decay factor passed to the local thermodynamic background loop.
prune_threshold0.05NoneHeat floor below which cold unpinned nodes drop out of the local active index.
max_total_nodes (max_nodes)10000 (0 = unlimited)SULCUS_MAX_TOTAL_NODESHard cap on local stored nodes before capacity eviction triggers.
auto_purgetrueNoneWhen at max_total_nodes, evicts coldest unpinned nodes below auto_purge_threshold.
auto_purge_threshold0.05SULCUS_AUTO_PURGE_THRESHOLDHeat ceiling for capacity-driven auto_purge eviction.
payload_compactiontrueSULCUS_PAYLOAD_COMPACTIONCompacts JSON, stack traces, git diffs, and code payloads via Caveman + Tree-sitter AST v2.
sync_interval_secs300SULCUS_SYNC_INTERVAL_MSCadence for TLS-encrypted HLC CRDT delta sync to Sulcus Cloud or Enterprise Server (paired with local AES-256-GCM vault primitives).
telemetryenabled (anonymous)SULCUS_TELEMETRY=offSet SULCUS_TELEMETRY=off (or pass --no-telemetry) for strict zero-egress workstation execution.

Daemon Environment Overrides

SULCUS_DATA_DIR sets the embedded PostgreSQL 17 cluster path (default ~/.sulcus/local). SULCUS_DB_PORT overrides the embedded Postgres port (default 4201). SULCUS_MCP_ADDR and SULCUS_MCP_PORT configure the local HTTP Control Panel and MCP listener for sulcus daemon and sulcus serve (default 127.0.0.1:4203).
Command Suite

Workstation CLI Reference

Workstation commands (login, connect, hook, mcp-proxy, search, index, symbol, namespace, model, learn, doctor, update) execute in under 15ms without starting Postgres. Engine commands automatically boot embedded PostgreSQL 17 when SULCUS_DATABASE_URL is unset.

bashSulcus CLI Commands
# Workstation, Hooks & Code Intelligence (<15ms startup, zero local Postgres boot required)
sulcus login [https://sulcus.internal.corp] [--keychain] [--api-key sk-...]
sulcus connect [auto|all|agy|claude-code|cursor|gemini|codex|vscode|junie|windsurf|cline|opencode|zed] [--link <ns>] [--global]
sulcus hook [<harness>] <Event>                  # Events: SessionStart, PreInvocation, PreToolUse, PostToolUse, PostInvocation, Stop
sulcus mcp-proxy [--server <url>] [--namespace <ns>]
sulcus search "<query>" [-n <ns>] [-k 8] [--json] # Fast-path VCR memory search (<15ms, zero local Postgres boot)
sulcus index [path]                              # Build/query BLAKE3 Merkle + Tree-sitter AST v2 workspace atlas
sulcus symbol <query> [--refs]                   # Locate symbols, spans, Caveman docs & cross-file references
sulcus namespace <list|link|unlink> [args]       # Manage persistent cross-repo linked namespaces
sulcus model <list|status|use|import|reset>      # Manage Bert/NomicBert safetensors, classifier, and Edge SLM cartridges
sulcus learn [candidates|reconcile]              # Inspect or reconcile /learn rule & skill promotion candidates
sulcus doctor [--fix] [--json]                   # End-to-end diagnostics and automatic self-repair
sulcus update [status|check|apply|rollback]      # Ed25519-verified binary self-update from Cloudflare R2

# Zero-Egress Workstation Mode (disables anonymous startup/telemetry pings)
SULCUS_TELEMETRY=off sulcus daemon start         # Or pass --no-telemetry

# Background Daemon & Local Client Engine (embedded PostgreSQL 17 on 127.0.0.1:4201)
sulcus daemon <start|stop|restart|status|logs>   # Manage background HTTP + MCP engine on 127.0.0.1:4203
sulcus serve                                     # Run foreground HTTP Local Memory Panel + Streamable MCP on :4203
sulcus stdio                                     # Run standalone embedded MCP over stdin/stdout
sulcus init | sulcus reinit [--force-external]   # Initialize or reset local PostgreSQL 17 schema
sulcus skill <ingest|list|fault|stub>            # Manage Dynamic Skills VMMU procedures & gateway stubs
sulcus ingest <folder> [--namespace <ns>]        # One-shot universal folder/PDF/Markdown/code ingestion
sulcus watch <folder> [--namespace <ns>]         # Proactive BLAKE3-debounced Folder Lens watcher
sulcus train <status|run|classifier|settings|test|export>
sulcus list-hot [20] | sulcus metrics            # Inspect hottest local nodes and WAL operation counts
Engineering Dispatches

Architecture Release Notes

Receive technical deep dives on thermodynamic context engineering, System 1 VCR cartridge updates, SulcusBench evaluations, and signed v3.1 engine releases directly from Digital Forge Studios.