Build it, initialize it, verify it.

Before you build

The source tree builds and its tests pass locally. The commands here are for a checked-out tree on a machine you control.

If someone offers you a DreenMind build, treat it as unverified.

Requirements

Build from source

From the repository root, build the command. The binary name is dreenmind.

cd dreenmind
go build -o dreenmind ./cmd/dreenmind
./dreenmind version

Set-Location dreenmind
go build -o dreenmind.exe .\cmd\dreenmind
.\dreenmind.exe version

The version command prints the build version and platform.

First run

Initialization creates the config, workspace, database, and encrypted vault. It asks for a vault passphrase. The minimum length is 12 characters; there is no recovery phrase.

./dreenmind init

On Linux the default config is under ~/.config/dreenmind/config.json. If an existing legacy config is present, the gateway can read it, but new state uses the DreenMind directory. Use --config to point at a different file.

Start the gateway

Run the gateway in one terminal. It binds to loopback and stays in the foreground.

./dreenmind serve

./dreenmind status
./dreenmind chat
# type /exit to leave the chat

status checks readiness. chat uses the local HTTP API, so the gateway must be running. If the gateway is not ready, the client fails instead of pretending to queue work.

Configure a provider

The provider must be OpenAI-compatible and support tool calling. Remote endpoints must use HTTPS. Loopback HTTP is allowed for local models. A local endpoint that does not require auth may use an empty key reference.

{
  "provider": {
    "base_url": "https://api.example.com/v1",
    "model": "example-model",
    "api_key_ref": "secret://provider/api-key"
  }
}

Store the key with the CLI’s secret command, not in the JSON file. The exact secret command is listed in the CLI reference. A live provider call is a separate verification step.

Telegram, private chats only

The Telegram adapter is optional and disabled by default. It uses long polling, ignores group chats, and requires pairing before a private chat is accepted.

1. Create a bot with BotFather and keep the token out of source control.
2. Store the token in the vault as a secret:// reference.
3. Enable the channel in config and restart serve.
4. Request a pairing code from the CLI. Codes are short-lived and limited to three active codes.
5. Send the code from the private chat you want to pair.

Pairing attempts are limited, and duplicate updates are suppressed for seven days. Approvals are not available as Telegram buttons; use the CLI or HTTP API.

Tool defaults

Verify the install

Run the same checks the repository uses. These are local checks.

go test ./...
go vet ./...
go build ./...
./dreenmind doctor
./dreenmind doctor --repair

doctor checks configuration, paths, vault access, database integrity, and provider shape. --repair rebuilds the message search index when it is safe to do so. It is not a data-recovery tool.

Update and roll back

There is no automatic updater. For a source build, stop the gateway, keep a copy of the database and vault, replace the binary, and run doctor before serving again.

1. Stop serve and confirm the process exited.
2. Back up the config, database, and vault as a set.
3. Replace the binary with the build you intend to run.
4. Run doctor, then serve, then status.
5. If startup fails, restore the previous binary and backup.

Draft release artifacts may include checksums.

Do not expose the gateway