Start here

If you are new to the tree, read the product boundaries first, then build and verify the install. The reference below assumes a local source build.

What the gateway owns and what it refuses.

Read first

Build, init, serve, and run doctor.

Source build

The exact support matrix and failure behavior.

Compatibility

CLI reference

Command	What it does
`dreenmind init`	Create config, workspace, database, and vault. Prompts for a passphrase.
`dreenmind serve`	Start the loopback gateway and optional Telegram channel.
`dreenmind status`	Check whether the gateway is ready.
`dreenmind chat`	Open an interactive client session; `/exit` leaves.
`dreenmind sessions`	List sessions.
`dreenmind doctor [--repair]`	Diagnose config, paths, vault, database, and provider shape; rebuild search with `--repair`.
`dreenmind secrets`	Manage vault-backed secret references.
`dreenmind approvals`	List and decide pending approval requests.
`dreenmind version`	Print build version and platform.

All commands accept an explicit config path where applicable. The CLI is an HTTP client for gateway operations; it is not a second database writer.

The API binds to loopback and uses bearer authentication. The CLI is the reference client. The table lists the stable shapes in the current tree.

Endpoint	Purpose
`GET /health`	Liveness and readiness information.
`POST /v1/messages`	Submit a user message and run a turn.
`GET /v1/sessions`	List sessions.
`GET /v1/sessions/{id}`	Read a session and its messages.
`GET /v1/approvals`	List pending approvals.
`POST /v1/approvals/{id}`	Approve or deny a scoped request.

Errors are JSON with a stable shape and sanitized messages. Do not parse provider error text as a contract.

Field	Default	Notes
`provider.base_url`	None	HTTPS for remote; loopback HTTP allowed.
`provider.model`	None	Model identifier passed to the provider.
`provider.api_key_ref`	None	A `secret://` reference, not the key.
`telegram.enabled`	`false`	Optional private-chat channel.
`telegram.token_ref`	None	Vault reference for the bot token.
`tools.workspace_write`	`false`	Opt-in; may require approval.
`tools.workspace_move`	`false`	Opt-in; source and destination checked.
`tools.web_fetch_hosts`	Empty	Exact host allowlist.
`approval.mode`	Sensitive tools	Policy for sensitive operations.
`sandbox.enabled`	`false`	Docker contract; fails closed if unavailable.

Unknown fields are rejected so a typo does not silently disable a boundary. The config file contains references, not plaintext secrets.

Operate the gateway as a local service with one writer. The important routines are diagnosis, backup, and a controlled binary replacement.

Label	Meaning
Implemented	The code path exists in the current tree.
Tested	An automated test exists and passed locally.
Verified	Tested in the environment the claim names.
Partial	Some pieces exist; the missing pieces are named.
Planned	Not implemented; not a delivery promise.
Unverified	Implemented, but the real external service was not exercised.

Gateway: The single process that owns the HTTP API, the turn loop, and the database.
Turn: One user message and the resulting assistant/tool cycle until a final answer or failure.
Receipt: The local record of a turn, tool call, approval, and outcome.
Edge: A provider, channel, tool, or sandbox boundary that connects to the core.
Approval: A scoped, single-use, expiring capability to perform a sensitive action.
Vault: Encrypted local storage for secrets referenced by secret://.
Unverified: Implemented but not tested against the live external service.

Path	Contents
`cmd/dreenmind`	Process entrypoint.
`internal/app`	CLI commands and application wiring.
`internal/gateway`	HTTP API, turn orchestration, approvals.
`internal/agent`	Provider loop and tool-call handling.
`internal/state`	SQLite schema, sessions, messages, search.
`internal/provider`	OpenAI-compatible provider adapter.
`internal/channel`	CLI-facing and Telegram channel code.
`internal/tools`	Workspace and web-fetch tools.
`internal/sandbox`	Docker sandbox contract.
`internal/vault`	Argon2id/AES-GCM secret storage.
`internal/config`	Config schema and paths.
`docs`	Architecture, dependencies, release, and PRD notes.