# Octobox: a self-hostable inbox for GitHub notifications

> Octobox adds an archived state, stars and filters on top of GitHub's notification list. It is a Rails application you can run yourself, and the repository ships a development docker-compose file to get there.

**octobox/octobox** — 📮 Untangle your GitHub Notifications

- Repository: https://github.com/octobox/octobox
- Website: https://octobox.io
- Stars: 4,484 · Forks: 347
- Language: Ruby
- License: AGPL-3.0
- Published: 2026-09-23 · Updated: 2026-09-23 · Language: en
- Canonical page: https://hysenlabs.com/projects/octobox-octobox

## The problem Octobox solves for GitHub maintainers

GitHub's notification list is read-once. The README puts it plainly: notifications are marked as read and disappear from the list as soon as you load the page or view the email. There is no third state between unread and gone, so a maintainer who wants to come back to a thread later has to keep it open in a tab or move it into an email client with its own filters and labels. Octobox's answer is to add an archived state to each notification. Archiving means done, and the item leaves the inbox. If anything happens on that thread, issue or pull request, the next sync moves the item back into the inbox. The intended user is the person who already lives in the GitHub notifications page and has run out of patience with it, and who prefers a web interface to Gmail rules.

## What the inbox actually shows and how filtering works

Octobox is not a thin wrapper over the GitHub API. The README lists the data it puts next to each notification: issue or pull request status, CI status, labels, organisation, repository, type, action, state and reason. That is more context than the notification page gives you, and it is what makes triage possible without opening every item. Filtering works on those same dimensions, and the README notes that filters can keep notifications from bots alongside regular labels, authors and assignees. There is also a prefix-based search syntax, described in the README as an alternative to guessing at keywords, which lets you combine filters to reach a specific notification. The design trade-off is that all of this depends on syncing. The repository layout includes a background job setup and Redis, and the docker-compose file wires Redis in as a separate service, which tells you that Octobox is not stateless: it stores your notifications in its own database and refreshes them on a schedule. The README also mentions that thread viewing is in public beta, enabled by choosing 'on octobox' from the 'Open notifications' menu in /settings, and that threads must be synchronised before they can be viewed. Some notifications show an external-link icon when no thread has been synchronised yet.

## Requirements before you install anything

The README states one hard requirement: web notifications must be enabled in your GitHub settings, or Octobox will not work. The same section notes that vulnerability notifications have to be enabled separately if you want them. This is a per-account setting on GitHub's side, not something Octobox can turn on for you, and it is the first thing to check because a misconfigured account looks like a broken installation. The repository also expects a GitHub OAuth application, since .env.example defines GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET. If you run Octobox as a GitHub App instead, the same file lists GITHUB_APP_ID, GITHUB_APP_SLUG, GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET, GITHUB_APP_JWT and GITHUB_WEBHOOK_SECRET, with a comment noting that GITHUB_WEBHOOK_SECRET is required for any publicly reachable deployment because /hooks/github otherwise accepts unsigned requests. That comment is the security boundary of a self-hosted install and should be treated as such.

## Installing Octobox with Docker and taking a first pass at the inbox

The README points to docs/INSTALLATION.md for self-hosting and mentions deployment to Heroku, Docker and more. The repository also ships a docker-compose.yml described in its own header as a development configuration that pulls images from Docker Hub and uses the default development environment. Copy .env.example to .env and fill in the two OAuth values before starting anything, since the compose file reads GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET from the environment.

```bash
cp .env.example .env
# set GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET in .env
docker compose up
```

The compose file maps port 3000 to the host, so the instance should be reachable at http://localhost:3000 once the app container and its Postgres 16 and Redis services are up. The database credentials in that file are development defaults (OCTOBOX_DATABASE_USERNAME=postgres, OCTOBOX_DATABASE_PASSWORD=development), which is fine for a local trial and not something to expose.

Once signed in through GitHub, the keyboard shortcuts are the fastest way to see what the inbox does. The README lists them, and they are worth learning in this order: j and k to move down and up the list, x to mark a notification, y or e to archive the marked ones, s to star the current one, and d to mark it read both in Octobox and on GitHub. Press ? for the help menu.

If you would rather not run a server, the README documents a desktop route using Nativefier, which wraps a URL in a local application binary.

```bash
npm install -g nativefier
nativefier "https://octobox.io"
```

The output is a .exe, .app or equivalent in the current folder, built against the hosted service or your own self-hosted URL. There is also a cross-browser web extension maintained outside the main repository, linked from the README and published for Chrome and Firefox.

## Where Octobox is the wrong tool

Octobox stores a copy of your notifications in its own database, which means a self-hosted instance is another service to run, back up and upgrade. The docker-compose file is explicitly a development configuration, and the header says so: it is meant for trying Octobox locally or as an example for a production configuration you write yourself. Anyone treating that file as a production deployment is skipping the part where you decide about TLS, a real database password and the webhook secret. The second limitation is scope. Octobox manages notifications; it does not replace code review, CI or issue tracking, and the README's own framing is about spending less time managing notifications, not about doing the work they point to. The third is that thread viewing is described as public beta, with the caveat that some notifications will not have a synchronised thread and will show an external-link icon instead. If inline comment threads are the reason you are interested, that part is not finished. Finally, if your workflow already lives in email and Gmail filters handle it, Octobox asks you to move that workflow into a web app, which is a real cost even when the app is better at it.

## Octobox compared with the GitHub notifications page

The obvious alternative is GitHub's own notifications page, and the difference is not cosmetic. GitHub has no archived state, so the only way to remove an item from the list is to read it, and the only way to keep it is to leave it unread. Octobox separates those two actions: x marks an item without archiving it, y or e archives it, and d marks it read in both places. The second difference is that archived items come back. The README describes this as the core of the design: if new activity happens on the thread, issue or pull request, the next sync unarchives the item and moves it back into the inbox. GitHub's list cannot do that because it has no archived state to restore from. The third difference is metadata. GitHub shows title, organisation, repository and type; Octobox adds issue and pull request status, CI status, labels, action, state and reason, and lets you filter on all of them. The cost of that is the sync loop and the database. GitHub's page is always current because it is the source; Octobox is a replica that has to be refreshed, and the README's keyboard shortcut list includes r or . for exactly that reason.

## Licence, upgrades and what self-hosting commits you to

Octobox is licensed under AGPL-3.0, and the README describes it as 100% developed and managed in the open under a FLOSS license. The AGPL matters if you plan to run a modified Octobox as a network service for other people: the licence's network clause is the part to read, and it is worth having someone who understands it look at your specific case rather than assuming a permissive licence. This is not legal advice, just the identifier the repository ships. On upgrades, the project publishes dated monthly releases, with september-2026, august-2026 and july-2026 as the most recent, and the last push to the default branch was on 2026-09-22. The Dockerfile builds from ruby:4.0.6-alpine, installs Node and Postgres client libraries, precompiles assets with RAILS_ENV=production bundle exec rake assets:precompile, and sets RUBY_YJIT_ENABLE=1 and LD_PRELOAD=/usr/lib/libjemalloc.so.2. Those environment variables are baked into the image, which means a self-hosted deployment inherits the project's runtime choices rather than picking its own. The upgrade path is to pull a newer image and run migrations; the repository does not document rollback, so a database backup before an upgrade is the only recovery route you can confirm from what is published.

## Conclusion

Adopt Octobox if you triage a high volume of GitHub notifications and want an archived state that survives new activity, plus filters GitHub itself does not offer. Do not adopt it if you only need a read/unread list, or if you cannot enable web notifications in your GitHub settings, because the README states that is a requirement. Before committing, verify that your GitHub notification settings have web notifications enabled, and decide whether you are running the hosted instance or your own deployment, since only the latter puts your notification data under your control.

## FAQ

### What does Octobox do?

Octobox manages your GitHub notifications with an extra archived state, so you can mark a notification as done and have it return to the inbox if new activity happens on the thread, issue or pull request. It also adds stars, richer notification metadata and filters by repository, organisation, type, action, state, CI status and reason.

### How do I use Octobox?

Enable web notifications in your GitHub settings, then either sign in to the hosted instance or self-host it following docs/INSTALLATION.md. In the inbox, use the keyboard shortcuts: j and k to move through the list, x to mark, y or e to archive, s to star, and d to mark read in Octobox and on GitHub.

### What is Octobox?

Octobox is an open source Ruby on Rails application for managing GitHub notifications, licensed under AGPL-3.0 and developed in the open on GitHub. It can be self-hosted, deployed to Heroku or Docker, or used through the hosted service at octobox.io.

### How much does Octobox cost?

The repository does not state a price. The software is published under AGPL-3.0 and the README documents self-hosting through docs/INSTALLATION.md, so the cost of running it yourself depends on where you deploy it, while the hosted service at octobox.io is a separate offering the README does not price.

## Sources

- [License: AGPL-3.0](https://github.com/octobox/octobox/blob/main/LICENSE)
- [octobox/octobox on GitHub](https://github.com/octobox/octobox)
- [Project website](https://octobox.io)
- [README](https://github.com/octobox/octobox/blob/main/README.md)
- [Releases](https://github.com/octobox/octobox/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/octobox-octobox