Skip to content

Local engine

The Python engine is the shared local runtime behind the desktop, web/mobile, terminal, browser, and coding clients. It composes a Starlette/Uvicorn API, agent graphs, SQLite persistence, encrypted configuration, tool registries, account brokering, retrieval, telemetry, and an optional subconscious worker.

Runtime and tray

subconscious start binds to 127.0.0.1 by default, selects an available production port, generates a random bearer token, and atomically writes runtime.json with the host, port, token, process ID, version, and optional node ID. --dev uses port 55681 and the known development token; --detached starts a background process; --no-tray is headless; --lan binds all IPv4 interfaces.

The tray displays local/LAN addresses, mode, version, and connected clients; copies a join command containing the bearer token; links to help; and stops the engine. Desktop/browser/web actions are currently placeholders—launch source clients directly.

CLI

  • subconscious config init|validate|show|set manages versioned YAML. Unknown keys are rejected, environment placeholders are supported, and secrets are masked unless --show-secrets is explicit.
  • subconscious start accepts config, development, port, LAN, node ID, data-directory, detached, and tray options.
  • subconscious chat performs one non-interactive turn from an argument or stdin, targets a workspace or thread, optionally enables workspace tools, and can append a notification.
  • subconscious desktop|tui|web|extension are reserved stubs, not working launch commands.

Agent and model features

Foreground and subconscious workflows are graph-defined. The optional background worker runs the subconscious graph on configurable interval/jitter, while client turns use the conscious graph. Built-in and configured tools can be selected per workspace/thread and routed through approval-aware execution.

Supported model paths are deterministic echo, Amazon Bedrock Converse, OpenAI, and OpenAI-compatible endpoints identified as openai-compatible, openrouter, ollama, lmstudio, vllm, or local. Every compatible provider except OpenAI needs a base URL. Other labels visible in the Flutter editor are not direct engine provider identifiers yet.

API documentation

Only GET /api/v1/health is public. All other engine endpoints require the runtime bearer token. Use the dedicated documentation for exact contracts:

POST /api/v1/agui remains a placeholder and is documented as unsupported.

Storage and retrieval

The main async SQLite database stores application entities; telemetry uses a separate database; model/tool/account secrets use the OS keyring or encrypted vault. Every indexed workspace root receives .subconscious/sidecar.db with documents, line-aware chunks, vectors, graph nodes/edges, and metadata.

Indexing skips VCS, build, cache, environment, and vendor directories; never follows symlinks; hashes files for changed-only work; prunes deleted documents; caps text at 500,000 characters; and rejects binary-like content. Sensitive names such as environment files, credentials, API/private keys, service accounts, and key stores are recorded as metadata-only placeholders—their content is not indexed.

Search supports keyword, vector, and reciprocal-rank-fused hybrid retrieval through the API. Lower-level graph retrieval also exists internally. Enabled roots are checked daily when due and can be reindexed manually. Semantic search uses the pinned sentence-transformers/all-MiniLM-L6-v2 model, which may need initial acquisition before it can run offline.

Security model

Protect the runtime file and joining token

Possession of the token grants engine API access. A copied join command also contains it. Production tokens are random; the development token is intentionally predictable and must not be exposed to untrusted networks.

All /api/v1 traffic except health uses constant-time bearer verification. WebSocket clients may provide the token in the query string for compatibility. CORS accepts loopback HTTP(S) origins and valid Chromium extension origins. Workspace API and retrieval roots must be existing absolute non-symlink directories.

The engine does not terminate TLS. --lan expands exposure and currently serves plain HTTP/WebSocket, so restrict it to a trusted local network and firewall scope. Workspace APIs remain root-scoped, but approval-gated generic filesystem model tools can intentionally access paths allowed by the operating system outside workspace roots.