Keel (Backend) Documentation

This section covers everything needed to set up and run the Holt Keel (Backend) server.

Keel is an ASGI application built on FastAPI and served with uvicorn. Running python main.py launches uvicorn for you using the settings in config.toml. The Docker image is based on python:3.13-slim and starts the same way.

Installation Options

Production Deployment

Recommended for hosting Holt in production:

Development Setup

Perfect for contributors and developers who want to modify the code:

  1. Python Installation - Install Python 3.13 and required dependencies
  2. Development Installation - Set up the development environment

Additional Configuration

  • SSL Certificates - Set up SSL certificates with automatic renewal using Let’s Encrypt

Requirements

  • Development: Python 3.13, pip
  • Production: Docker and Docker Compose
  • Security: SSL certificates (production only)

Presence, Typing and Privacy

Holt supports user presence, typing indicators and last-seen timestamps. These are designed to be private by default and can be controlled both by each user and by the instance operator.

Presence statuses

A user’s presence can be one of:

  • online - active and reachable
  • idle - connected but inactive
  • dnd (do not disturb) - active but asking not to be disturbed
  • invisible - appears offline to everyone

Privacy model

  • Presence and last-seen are only visible to people who share a channel with you. The relationship is mutual and reciprocal: if you can see someone, it is because you share a channel, and the same applies in reverse.
  • The model is block-aware. Blocking removes mutual visibility.
  • invisible appears exactly the same as being genuinely offline. There is no way to tell an invisible user apart from one who is simply not connected.

Opting out

Privacy is opt-out at two levels:

Per user

  • Set your status to invisible to appear offline to everyone.
  • share-last-seen - turn off to stop sharing your last-seen timestamp (share_last_seen).
  • share-typing - turn off to stop sending typing indicators (share_typing).

Per instance (in config.toml)

Key Default Description
[presence] enabled true Enable or disable user presence (online/idle/dnd/invisible statuses) for the whole instance.
[presence] last_seen true Allow showing last-seen timestamps for offline users (users can still opt out individually).
[typing] enabled true Enable or disable typing indicators in DMs and group channels.

Disabling a feature at the instance level overrides per-user settings. For example, if [presence] enabled is false, no presence is tracked or shown for anyone on that instance.