> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ollim.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Self-host ollim-bot

> Fork the repo, configure your instance, and deploy ollim-bot as a personal assistant.

ollim-bot is single-user by design. There is no multi-tenancy, no shared hosting, no
user accounts. If you want your own instance, you fork the repo, configure it for
yourself, and run it. This guide covers the full process.

## Prerequisites

* [uv](https://docs.astral.sh/uv/) — `curl -LsSf https://astral.sh/uv/install.sh | sh` (automatically installs the required Python version)
* A [Claude](https://claude.ai) subscription (Pro or Max) — the bot authenticates via the bundled Agent SDK CLI at startup. If you plan to use a [local or alternative model provider](/self-hosting/model-providers), you don't need a Claude subscription.
* A Discord account (the bot runs entirely in DMs — no server required)
* Git installed (the data directory is a git repo)

## Installation

Follow the [quickstart guide](/getting-started/quickstart) to get the bot running,
then [set up Google integration](/getting-started/google-integration) for Tasks, Calendar, and Gmail.
The steps below cover self-hosting-specific setup.

<Steps>
  <Step title="Fork the repository">
    Fork the repo on GitHub, then clone your fork:

    ```bash theme={null}
    git clone https://github.com/<your-username>/ollim-bot.git
    cd ollim-bot
    uv sync
    uv tool install --editable .
    ```

    `uv sync` installs dependencies. `uv tool install` makes `ollim-bot`
    and `claude-history` available as global commands. `claude-history` is
    a CLI tool used by [subagents](/extending/subagents) to review Claude
    Code session transcripts.

    Working from a fork lets you customize the system prompt, subagent prompts,
    and integrations while still pulling upstream changes.
  </Step>

  <Step title="Create a Discord bot">
    Create a Discord application at the [Discord Developer Portal](https://discord.com/developers/applications).
    You need the bot token and the Message Content privileged intent.

    See the [quickstart](/getting-started/quickstart#create-a-discord-bot) for the full walkthrough.
  </Step>

  <Step title="Set up Google OAuth (optional)">
    Google Tasks, Calendar, and Gmail integration requires OAuth credentials
    from Google Cloud Console. Download the credentials JSON and save it to
    `~/.ollim-bot/state/credentials.json`, then run `/google-auth` in Discord
    to connect your account.

    See [Google integration setup](/getting-started/google-integration) for the full walkthrough.
  </Step>

  <Step title="Run the bot">
    ```bash theme={null}
    ollim-bot
    ```

    On startup, ollim-bot validates environment variables and checks Claude
    authentication via `is_authenticated()`. If not logged in, the bot
    extracts an OAuth URL from the bundled CLI and DMs it to you using the
    Discord REST API — this happens before the bot fully connects, so
    you receive the link even on a headless server with no browser.
    Click the link to sign in with your Anthropic account. The bot
    blocks until authentication completes, then continues startup.

    Once authenticated, the bot checks for duplicate instances, connects to
    Discord, starts the scheduler, and sends you a startup DM.

    <Tip>
      If you're using an alternative provider (Ollama, vLLM, etc.), set
      `ANTHROPIC_AUTH_TOKEN` in your `.env` — the Agent SDK uses this token
      instead of Claude OAuth, so no Anthropic account is needed. See
      [Model providers](/self-hosting/model-providers) for provider-specific
      `.env` configuration.
    </Tip>

    <Note>
      ollim-bot enforces single-instance via a PID file. On startup, it checks whether
      the recorded PID is still alive, so stale PID files from crashes are handled
      automatically.
    </Note>
  </Step>
</Steps>

## What to customize

ollim-bot is designed to be personalized. The main customization points:

### Names and identity

Set `OLLIM_USER_NAME` and `OLLIM_BOT_NAME` in `.env`. These are woven into the
system prompt and all bot messages. The bot addresses you by `OLLIM_USER_NAME`
and refers to itself by `OLLIM_BOT_NAME`.

### System prompt

The system prompt is built in `src/ollim_bot/prompts.py`. It includes tool
instructions, scheduling context, and behavioral guidelines. Edit this file
to change the bot's personality, communication style, or default behaviors.

### Subagent prompts

Subagent specs live in `src/ollim_bot/subagents/` as markdown files with
YAML frontmatter. ollim-bot ships with five subagents:

| Subagent                  | Purpose                                                       |
| ------------------------- | ------------------------------------------------------------- |
| `ollim-bot-guide`         | Docs-first setup and usage help                               |
| `gmail-reader`            | Read-only email triage                                        |
| `history-reviewer`        | Reviews session history for context                           |
| `responsiveness-reviewer` | Evaluates the bot's own proactive behavior                    |
| `user-proxy`              | Answers "what would the user prefer?" during background forks |

Place override files in `~/.ollim-bot/.claude/agents/` to modify these
prompts — `install_agents()` skips files that already exist, so your
customizations persist across bot updates. Create additional spec files
in `src/ollim_bot/subagents/` to add new bundled subagents.

### Model providers

By default, ollim-bot uses your Claude subscription via Claude Code OAuth.
You can also use alternative model subscriptions (from \$3/month), pay-per-token
providers, or self-hosted models. See [Model providers](/self-hosting/model-providers)
for all options.

### Integrations

To add a new Google service: add the OAuth scope to `google/auth.py`, create a
new module in `google/`, and add tool instructions to the system prompt. See
[Adding integrations](/development/adding-integrations) for the full pattern.

### Routines and reminders

Routines and reminders are markdown files in `~/.ollim-bot/routines/` and
`~/.ollim-bot/reminders/`. The agent creates and manages these files directly,
but you can also create them manually or via the CLI:

```bash theme={null}
ollim-bot routine add --cron "0 9 * * 1-5" -m "Morning briefing"
ollim-bot reminder add --delay 30 -m "Take a break"
```

## Data directory

All persistent data lives in `~/.ollim-bot/`, managed as a git repository.
See [Data directory](/configuration/data-directory) for the full layout.

<Tip>
  Back up `~/.ollim-bot/` to preserve your routines, reminders, session history,
  and Google credentials. Since it is a git repo, you can push it to a private
  remote for backup.
</Tip>

## Docker deployment

The repo ships a `Dockerfile`, `docker-compose.yml`, and `docker-entrypoint.sh`
for containerized deployment. The compose file bundles ollim-bot with a local
[Ollama](https://ollama.com) server, so a single `docker compose up` gives you
a self-contained stack with no Anthropic account required for inference.

<Steps>
  <Step title="Configure .env">
    Create a `.env` file in the repo root. At minimum you need `DISCORD_TOKEN`,
    `OLLIM_USER_NAME`, and `OLLIM_BOT_NAME`. To use the bundled Ollama service,
    point the bot at the `ollama` service hostname and set any non-empty
    `ANTHROPIC_AUTH_TOKEN`:

    ```bash title=".env" theme={null}
    DISCORD_TOKEN=your-discord-bot-token
    OLLIM_USER_NAME=YourName
    OLLIM_BOT_NAME=Ollim
    ANTHROPIC_BASE_URL=http://ollama:11434
    ANTHROPIC_AUTH_TOKEN=ollama
    ANTHROPIC_MODEL=qwen3.5:2b
    ANTHROPIC_SMALL_FAST_MODEL=qwen3.5:2b
    ```

    Setting `ANTHROPIC_AUTH_TOKEN` tells ollim-bot to skip the Claude OAuth
    check at startup — necessary inside containers where the bundled CLI can't
    prompt for login. See [Model providers](/self-hosting/model-providers) for
    other backend options.
  </Step>

  <Step title="Start the stack">
    ```bash theme={null}
    docker compose up -d
    ```

    The entrypoint (`docker-entrypoint.sh`) checks whether `ANTHROPIC_MODEL` is
    already present on the Ollama server and pulls it automatically if not —
    the first start may take several minutes while the model downloads. Compose
    waits for Ollama's healthcheck before starting the bot container.
  </Step>

  <Step title="Tail logs and verify">
    ```bash theme={null}
    docker compose logs -f ollim-bot
    ```

    Once the bot connects to Discord, you receive the startup DM. Use
    `docker compose down` to stop and `docker compose up -d --build` to rebuild
    after changing source or prompts.
  </Step>
</Steps>

### What the compose stack does

| Service     | Image                         | Purpose                                                    |
| ----------- | ----------------------------- | ---------------------------------------------------------- |
| `ollama`    | `ollama/ollama`               | Local Ollama server bound to `127.0.0.1:11434` on the host |
| `ollim-bot` | Built from local `Dockerfile` | The bot, depending on `ollama` being healthy               |

| Volume        | Mounted at                              | Purpose                                                       |
| ------------- | --------------------------------------- | ------------------------------------------------------------- |
| `ollama_data` | `/root/.ollama` (in `ollama`)           | Pulled Ollama models persist across restarts                  |
| `bot_data`    | `/home/bot/.ollim-bot` (in `ollim-bot`) | Data directory — routines, reminders, sessions, profile files |
| `cli_data`    | `/home/bot/.claude` (in `ollim-bot`)    | Claude CLI configuration                                      |

The bot container runs as an unprivileged `bot` user. The Ollama port is bound
to `127.0.0.1` on the host so it isn't reachable from other machines on your
network.

<Note>
  To use a cloud provider (Claude subscription, Z.AI, DeepSeek, etc.) instead
  of bundled Ollama, set the provider's `ANTHROPIC_BASE_URL` and
  `ANTHROPIC_AUTH_TOKEN` in `.env` and remove the `ollama` service and its
  `depends_on` entry from `docker-compose.yml`. See
  [Model providers](/self-hosting/model-providers) for provider configurations.
</Note>

<Warning>
  The bot container can't complete Claude OAuth on your behalf — there's no
  browser inside. Either set `ANTHROPIC_AUTH_TOKEN` (any provider, including
  Ollama) to skip OAuth entirely, or run the bot natively once to complete
  login before switching to Docker.
</Warning>

## Running as a service

For persistent operation without Docker, run ollim-bot as a systemd user service:

```bash title="~/.config/systemd/user/ollim-bot.service" theme={null}
[Unit]
Description=ollim-bot Discord assistant
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
WorkingDirectory=<path-to-ollim-bot>
ExecStart=<path-to>/.local/bin/ollim-bot
Restart=on-failure
RestartSec=10

[Install]
WantedBy=default.target
```

Reload the service configuration and start the bot:

```bash theme={null}
systemctl --user daemon-reload
systemctl --user enable --now ollim-bot
```

<Tip>
  The bot sends you a DM before shutting down on crash, SIGINT, or SIGTERM —
  you'll see a message like `shutting down: received SIGTERM`. Combined with
  `Restart=on-failure`, this means you get notified and the bot comes back
  automatically.
</Tip>

<Warning>
  If Claude Code is not authenticated when the service starts, the bot
  DMs you an OAuth link and blocks until you complete sign-in. The
  systemd service may time out waiting — run `ollim-bot auth login`
  once manually before enabling the service. If you're using an
  alternative provider with `ANTHROPIC_AUTH_TOKEN`, this step is
  not needed.
</Warning>

## Session persistence

ollim-bot persists its Claude session across restarts — no context is lost. If you
want a fresh start, use `/clear` in Discord. See
[Session management](/architecture/session-management) for details on compaction,
lifecycle events, and session recovery.

## License

ollim-bot is licensed under [GPL-3.0](https://github.com/Ollim-AI/ollim-bot/blob/main/LICENSE.md).
If you fork the repo and distribute your modified version, your fork must also
be released under GPL-3.0 and include the full source — that's what copyleft
means. Running your own private fork for personal use has no such requirement.

The license also carries a Section 7 supplementary notice restricting use of
the repo's contents for training or evaluating machine learning models without
written permission from the copyright holder. This does not affect normal human
use, modification, or redistribution under GPL-3.0.

## Next steps

<Columns cols={2}>
  <Card title="Choose a model provider" icon="microchip" href="/self-hosting/model-providers">
    Use a local model, alternative subscription, or pay-per-token provider.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/getting-started/quickstart">
    Install ollim-bot and create a Discord bot.
  </Card>

  <Card title="Configuration reference" icon="sliders" href="/configuration/reference">
    All environment variables and configuration options.
  </Card>

  <Card title="System prompt" icon="code" href="/development/system-prompt">
    How the system prompt is structured and how to customize it.
  </Card>
</Columns>