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.
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.
Offline Workstation
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.Sulcus Cloud SaaS
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.Private VPC Enclave
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
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.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.
# ~/.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 Key | Default Value | Environment Variable | Runtime Behavior |
|---|---|---|---|
| server_url (server) | None | SULCUS_SERVER_URL / SULCUS_BASE_URL | Target Sulcus API URL for login, mcp-proxy, hook, namespace, doctor, train --push, and IDE plugins. |
| server_api_key (api_key) | None | SULCUS_API_KEY / SULCUS_SERVER_API_KEY | Bearer credential (workstation CLI also checks SULCUS_TOKEN and macOS Keychain sulcus-cli). |
| namespace (agent_namespace) | "default" | SULCUS_NAMESPACE | Default namespace used by mcp-proxy, CLI commands, local store_memory, and harness hooks. |
| database_url | Embedded PG17 (127.0.0.1:4201) | SULCUS_DATABASE_URL | Local Postgres DSN. Strictly validated to 127.0.0.1 or localhost (SQLite and remote hosts rejected). |
| therm_interval_ms | 1000 | SULCUS_TICK_MS | Background thermodynamic tick interval (ms) for sulcus daemon, sulcus serve, and sulcus stdio. |
| active_limit | 20 | SULCUS_ACTIVE_LIMIT | Maximum nodes held in the hot active working-memory index. |
| decay | 0.85 | None | Per-tick decay factor passed to the local thermodynamic background loop. |
| prune_threshold | 0.05 | None | Heat floor below which cold unpinned nodes drop out of the local active index. |
| max_total_nodes (max_nodes) | 10000 (0 = unlimited) | SULCUS_MAX_TOTAL_NODES | Hard cap on local stored nodes before capacity eviction triggers. |
| auto_purge | true | None | When at max_total_nodes, evicts coldest unpinned nodes below auto_purge_threshold. |
| auto_purge_threshold | 0.05 | SULCUS_AUTO_PURGE_THRESHOLD | Heat ceiling for capacity-driven auto_purge eviction. |
| payload_compaction | true | SULCUS_PAYLOAD_COMPACTION | Compacts JSON, stack traces, git diffs, and code payloads via Caveman + Tree-sitter AST v2. |
| sync_interval_secs | 300 | SULCUS_SYNC_INTERVAL_MS | Cadence for TLS-encrypted HLC CRDT delta sync to Sulcus Cloud or Enterprise Server (paired with local AES-256-GCM vault primitives). |
| telemetry | enabled (anonymous) | SULCUS_TELEMETRY=off | Set 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).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.
# 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