Skip to content

personal-botA self-hosted personal assistant

Runs on your own machine, stores its memory in files you control, and replies in the chats you already use.

Read this first

This project drives a third-party desktop client, which violates that client's terms of service and can get an account restricted or banned. Use a secondary account with existing history, a residential connection, and the default send pacing. This is a private research project provided as is; you bear all risk. Read the disclaimer before running anything.

Architecture ​

The stack runs four containers for a single chat account: qq runs the official desktop client on a virtual display, bot runs the assistant, console serves the web panel you manage it from, and sandbox runs the assistant's shell commands as an unprivileged user.

Architecture of one stack: the official chat client runs headless and writes its local database; the driver reads that database, serves the console and the bot, and sends messages and downloads media through the client itself; the bot runs its commands in the sandbox

Start here ​

Works with every model pi supports ​

The assistant is built on pi, so every model provider and vision-capable model supported by pi is available out of the box. Sign in to a provider or add an API key on the console's Models and Jev page. The model catalog is fetched at startup and refreshed once a day automatically (unless PI_OFFLINE=1), and can be refreshed on demand from the page header without restarting any container.

For the full repository overview, see the README; for the details of context windows, memory, and comparisons with other frameworks, see docs/how-it-works.md.