First Run

There are two ways to get started: write a minimal config by hand and start the agent, or start with an empty config and finish setup in the web dashboard’s guided wizard.

Configuration

Copy the example file:

mkdir -p ~/.denkeeper
cp denkeeper.toml.example ~/.denkeeper/denkeeper.toml

Edit the file and fill in at minimum:

[telegram]
token = "YOUR_TELEGRAM_BOT_TOKEN"
allowed_users = [YOUR_TELEGRAM_USER_ID]

[llm]
default_provider = "openrouter"
default_model = "anthropic/claude-sonnet-4-20250514"

[llm.openrouter]
api_key = "YOUR_OPENROUTER_API_KEY"

Get a Telegram bot token

1. Open Telegram and message @BotFather
2. Send /newbot and follow the prompts
3. Copy the token into your config

Find your Telegram user ID

Message @userinfobot on Telegram. It replies with your numeric user ID.

Start the agent

denkeeper serve

Send a message to your bot in Telegram. You should see a response within a few seconds.

Web dashboard setup

The API and web dashboard are enabled by default. On first run, the web dashboard offers a streamlined setup flow.

When Denkeeper starts with no API keys and no password configured, it generates a one-time setup PIN and logs it to the console:

INFO FIRST-RUN SETUP PIN pin=482937
INFO Enter this PIN in the web dashboard to create your admin account.

Open the dashboard in your browser (default: http://localhost:8080) and you’ll see two options:

1. Create Account (recommended) — enter the PIN from the logs and choose a password. This creates a password-based login for the dashboard and logs you in immediately.
2. Create API Key — creates a scoped API key for programmatic access. Useful for automation or headless setups.

The PIN is single-use and cleared after successful account creation. It is never exposed via any API endpoint — only in the server logs.

See the Web Dashboard guide for what each page does.

Once you’re logged in, the dashboard’s setup wizard takes over as the guided path: if your config declares no [[agents]], Denkeeper deliberately starts with no agent so the wizard can walk you through creating the first one — provider, model, permission tier, and persona — writing the result back to your TOML file. An onboarding checklist tracks the remaining milestones.

Logs

By default, Denkeeper logs to stderr at info level:

# Increase verbosity
denkeeper serve  # then edit denkeeper.toml: [log] level = "debug"

When running as a systemd service:

journalctl -u denkeeper -f

Next: Configuration reference for the full list of options.