ShinBot

ShinBot is a self-hosted personal assistant. Ask it to research a question, use a website, work with files, or run a scheduled task. Watch its browser, take control to sign in, and give different bots their own roles and browser profiles.

Website · Documentation · Releases

ShinBot supports one owner with multiple bot profiles. Use a capable tool-calling model and review consequential actions. Handle email and calendar workflows through the browser or installed plugins.

Get started

Use Linux or macOS, Python 3.13 or newer, uv and a running Docker-compatible engine with Docker Compose.

uvx --prerelease allow shinbot start

ShinBot downloads its service images and opens http://localhost:8765 with a one-time setup link. Choose a password, connect a model, and try a small task. Home includes starter templates and prompts.

For a persistent CLI installation:

uv tool install --prerelease allow shinbot
shinbot start

You can also use python -m pip install --pre shinbot in a virtual environment. The Python package is the launcher and CLI; Docker still runs the application services. On a headless host, use shinbot start --no-open-browser and retrieve the token with shinbot setup-token.

See the installation guide, model setup and remote access guide.

What you can do

The app supports light, dark and system appearance. System is the default; your choice is saved in the browser.

Your installation and data

The launcher saves configuration in ~/.shinbot. Docker volumes hold conversations, notes, credentials, browser profiles, scheduled jobs and workspace files. Removing or reinstalling the Python package leaves that data in place. Keep the same OS account, launcher home and Docker engine when reinstalling.

shinbot status
shinbot doctor
shinbot stop
shinbot backup /safe/location/shinbot.tar.gz

Stopping preserves data. Backups contain credentials as well as your work; keep them private. Read backup and recovery before moving an installation or deleting volumes.

The gateway binds to loopback by default. Remote access can use an SSH tunnel or an HTTPS reverse proxy. Internal services stay private. Model providers receive the context needed for model calls. Executable plugins have workspace and outbound network access, so install code from sources you trust.

Built from six parts

Four services start by default. ShinBot uses published upstream packages through their public interfaces.

Extend ShinBot

Add sidebar apps, themes, chat and tool hooks, MCP servers, skills or bot templates through plugins. The extension guide explains the options and how to build your own.

The optional Projects plugin adds a GitHub attention inbox, issue-linked bot conversations and reminders, repository browsing, parallel worktrees and bot delegation. The optional Calendar plugin connects Google Calendar with read-only access and shows events alongside scheduled bot work. Manage encrypted integration and plugin credentials through Settings → Secrets. The Kanban plugin adds a board for work that needs several runs.

The official Telegram plugin adds a private chat connection. Follow its setup guide when you want to use it.

Contribute

The official repositories are shinbot-official-plugins and shinbot-official-templates. Users can add public personal repositories in the same format. Starter catalogs are included under marketplaces/.

From a source checkout:

uv sync --frozen --extra computer
npm --prefix runtime ci --ignore-scripts
npm --prefix runtime run build
uv run --frozen shinbot start --build

Read the architecture, development and tests, plugin guide, and template format.

GitHub Actions checks Python, the runtime, browser journeys, container integration, packaging and documentation. Publishing runs only for published GitHub Releases, which publish versioned Docker images, the Python package, the landing page and documentation from the release tag. The release guide covers trusted publishing, Docker credentials and GitHub Pages.

Licenses

ShinBot is MIT-licensed. Application dependencies primarily use permissive licenses. Reviewed exceptions include noVNC and certifi under MPL-2.0, and the optional Telegram library under LGPL-3.0. Dependencies are distributed unchanged with their notices. Platform components, including Linux, Chromium and TigerVNC, have separate licenses. See the license guide for the application, documentation and platform inventories.