---
title: "Deploy Octobox"
description: "Inbox for your GitHub notifications, with archiving and search"
category: "Other"
url: https://railway.com/deploy/octobox
---

# Deploy Octobox

Inbox for your GitHub notifications, with archiving and search

**[Deploy Octobox on Railway](https://railway.com/template/octobox)**

Machine-readable deploy manifest (JSON, validated by TemplateCI): https://railway.com/deploy/octobox/manifest.json

- **Creator:** A3A
- **Category:** Other
- **Total deploys:** 1

## Template content

### Postgres https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/postgresql.svg

- **Image:** ghcr.io/railwayapp-templates/postgres-ssl:18

### octobox https://cdn.jsdelivr.net/gh/octobox/octobox@main/app/assets/images/infinitacle-round.svg

- **Source:** https://github.com/gridalpha/octobox-railway
- **Health check:** /healthz
- **Public domain:** Yes

### Redis https://cdn.jsdelivr.net/gh/homarr-labs/dashboard-icons/svg/redis.svg

- **Image:** redis:8.2
- **Start command:** `/bin/sh -c "rm -rf $RAILWAY_VOLUME_MOUNT_PATH/lost+found/ && exec docker-entrypoint.sh redis-server --requirepass $REDIS_PASSWORD --save 60 1 --dir $RAILWAY_VOLUME_MOUNT_PATH"`

### octobox-worker https://cdn.jsdelivr.net/gh/octobox/octobox@main/app/assets/images/infinitacle-round.svg

- **Source:** https://github.com/gridalpha/octobox-railway
- **Health check:** /healthz

## Documentation

# Deploy and Host Octobox on Railway

Octobox turns GitHub's notification feed into a real inbox. Instead of a list that empties itself the moment you glance at it, every thread gets an explicit *archived* state: mark it done, and if the issue or pull request sees new activity it comes back. Maintainers watching dozens of repositories triage with Gmail-style keyboard shortcuts and filter by repository, organisation, CI status, labels, author or assignee. It is an open-source Rails application from the Octobox team — self-host Octobox when notification history, saved searches and GitHub tokens should stay on infrastructure you control.

Deploy Octobox on Railway and you get the full production topology, not a single container. `octobox` runs the Puma web tier behind your public domain and migrates the database as it boots. `octobox-worker` runs Sidekiq with a scheduler, pulling fresh notifications from the GitHub API every ten minutes so the inbox is current before you open the tab. `Postgres` stores users, notifications and saved searches on a volume; `Redis` carries the Sidekiq queues and the Action Cable channel that live-updates rows. Only the web service is exposed — everything else talks over the private network.

![Railway architecture diagram of Octobox web, worker, Postgres and Redis](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789577812/octobox-architecture.webp)

## Getting Started with Octobox on Railway

Octobox has no local accounts — the only way in is GitHub OAuth — so there is one step before anyone can sign in. Deploy the template, copy the public domain Railway generates for the `octobox` service, then register an OAuth application at `https://github.com/settings/applications/new` with the `notifications` scope and a callback URL of `https:///auth/github/callback`. Paste the client ID and secret into `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`; the service redeploys and *Sign in* starts working. Open the URL, authorize the app, and the first sync fills the inbox within seconds. Archive a thread with `e`, star one with `s`, then open *Archive* in the sidebar to confirm it moved. To check the deployment end to end, leave the tab open for ten minutes and watch new notifications arrive without a refresh — that is `octobox-worker` running its scheduled sync. Any GitHub account reaching your URL can sign in by default; set `RESTRICTED_ACCESS_ENABLED=1` with `GITHUB_ORGANIZATION_ID` or `GITHUB_TEAM_ID` to restrict it.

![Octobox landing page showing the notification inbox product screenshot](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789577815/octobox-home.webp)
![Octobox feature cards describing archiving, filtering and status syncing](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789577817/octobox-feature-cards.webp)
![Octobox documentation page explaining OAuth scopes and archiving](https://res.cloudinary.com/rroe4rtk/image/upload/f_auto,q_auto/v1789577822/octobox-documentation.webp)

## About Hosting Octobox

GitHub marks a notification read as soon as you look at it, which makes the built-in inbox useless as a to-do list. Octobox keeps its own copy in Postgres and adds the states GitHub lacks, so a thread you are waiting on stays visible until you clear it. Teams self-host it when notification metadata — which private repositories you watch, who mentions you — should not sit on a third-party service.

- An archived state that un-archives itself when a thread gets new activity
- Starring, muting and bulk actions over multi-select, with keyboard shortcuts
- Filtering by repository, organisation, type, reason, state, CI status, labels, author and assignee
- Saved searches pinned to the sidebar, and rows showing issue, PR and CI status
- A documented REST API with bearer-token auth, plus a browser extension
- Optional per-user personal access tokens for wider scope and rate limits

The deployment splits the application the way upstream's Procfile does: the web tier answers requests and owns migrations, the worker tier owns every background job. Redis is not a cache here — it is the job queue.

## Why Deploy Octobox on Railway

Railway removes the parts of running a Rails app that are not Octobox.

- Postgres and Redis are provisioned, networked and backed by volumes already
- Web and worker tiers deploy from one repository and scale separately
- TLS, HSTS and the public domain are handled at the edge
- Migrations run on every deploy, so upgrades are a single push
- Private networking keeps the database, queue and worker off the internet

## Common Use Cases

- **Maintainer triage:** clear a morning's notifications across dozens of repositories in one pass.
- **Team review queues:** filter to review requests and pin it as a saved search so no pull request waits unnoticed.
- **Private notification history:** keep the record of what you were mentioned in on your own infrastructure.
- **Scripted workflows:** drive the REST API to feed notification counts into a dashboard or bot.

## Dependencies for Octobox

- **`octobox`** — the Rails web tier, built from [`gridalpha/octobox-railway`](https://github.com/gridalpha/octobox-railway) on top of the official `octoboxio/octobox` image. Serves the UI and API, and migrates at boot.
- **`octobox-worker`** — the same image running Sidekiq and `sidekiq-scheduler`: every notification sync, subject fetch and comment download.
- **`Postgres`** (`ghcr.io/railwayapp-templates/postgres-ssl:18`) — users, notifications, subjects, labels and saved searches, on a volume.
- **`Redis`** (`redis:8.2`) — Sidekiq queues and scheduler state, plus the Action Cable channel behind live row updates.

### Environment Variables Reference

| Variable | Service | Purpose |
|---|---|---|
| `GITHUB_CLIENT_ID` | octobox | OAuth client ID — required before anyone can sign in |
| `GITHUB_CLIENT_SECRET` | octobox | OAuth client secret |
| `OCTOBOX_ATTRIBUTE_ENCRYPTION_KEY` | both | 32-character key encrypting stored GitHub tokens |
| `OCTOBOX_SIDEKIQ_SCHEDULE_ENABLED` | worker | Enables the ten-minute server-side sync |
| `RESTRICTED_ACCESS_ENABLED` | octobox | Limits sign-in to one organisation or team |
| `GITHUB_DOMAIN` | both | Points Octobox at a GitHub Enterprise instance |

### Deployment Dependencies

- Source: [gridalpha/octobox-railway](https://github.com/gridalpha/octobox-railway), built on [octobox/octobox](https://github.com/octobox/octobox) (AGPL-3.0-only)
- Base image: [`octoboxio/octobox`](https://hub.docker.com/r/octoboxio/octobox)
- Runtime: Ruby 4, Rails 8.1, Puma, Sidekiq 8, PostgreSQL 18, Redis 8

## Hardware Requirements for Self-Hosting Octobox

| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 1 vCPU across web and worker | 2 vCPU |
| RAM | 1 GB (512 MB web, 512 MB worker) | 2 GB |
| Storage | 1 GB Postgres volume | 5 GB, growing with history |
| Runtime | Rails 8.1, PostgreSQL 13+, Redis 6+ | as deployed |

Sizing scales with how many people sign in, not with repository count.

## Self-Hosting Octobox with Docker

Upstream publishes a complete image, so the shortest local run is `docker-compose.yml`:

```
services:
  app:
    image: octoboxio/octobox:september-2026
    ports: ["3000:3000"]
    environment:
      RAILS_ENV: production
      RAILS_SERVE_STATIC_FILES: "true"
      SECRET_KEY_BASE: sixty-four-random-characters-here
      OCTOBOX_ATTRIBUTE_ENCRYPTION_KEY: exactly-32-characters-right-here
      GITHUB_CLIENT_ID: your-oauth-client-id
      GITHUB_CLIENT_SECRET: your-oauth-client-secret
      DATABASE_URL: postgres://postgres:postgres@db:5432/octobox
      REDIS_URL: redis://cache:6379
  db:
    image: postgres:18-alpine
    environment: { POSTGRES_PASSWORD: postgres }
  cache:
    image: redis:8-alpine
```

Note the tag. Octobox releases on the first of each month as `-`; `latest` stopped moving in January 2026, so pin the newest month. Generate the encryption key with the app's own helper — it must be exactly 32 characters:

```
docker run --rm octoboxio/octobox:september-2026 bin/rails secret | cut -c1-32
```

## How Much Does Octobox Cost to Self-Host?

Octobox is free and open source under AGPL-3.0, with no paid tier, seat limit or licence key — octobox.io runs the same software. The only cost is infrastructure: the web service, the worker, Postgres and Redis, a few dollars a month of usage-based billing for a small team. GitHub's API is free for the `notifications` scope.

## FAQ

**What is Octobox?**
An open-source inbox for GitHub notifications. It keeps its own copy in a database and adds archived, starred and muted states, filtering and saved searches GitHub does not have.

**What does this Railway template deploy?**
Four services: the `octobox` Rails web tier on a public domain, an `octobox-worker` Sidekiq service running the scheduled sync, a `Postgres` database and `Redis`.

**Do I need a GitHub OAuth app to self-host Octobox?**
Yes. Octobox has no local accounts, so sign-in goes through GitHub. Register an OAuth application with the `notifications` scope and a callback of `https:///auth/github/callback`, then set `GITHUB_CLIENT_ID` and `GITHUB_CLIENT_SECRET`.

**Why does Octobox need Redis as well as Postgres?**
Postgres is the durable store. Redis is the Sidekiq job queue — every sync runs as a background job, and the ten-minute scheduler keeps its state there.

**How do I stop strangers signing in to my self-hosted Octobox?**
Set `RESTRICTED_ACCESS_ENABLED=1` and either `GITHUB_ORGANIZATION_ID` or `GITHUB_TEAM_ID` on the `octobox` service, and add `read:org` to your OAuth application.

**How do I use the Octobox REST API?**
Open *Settings* from the user menu for your API token and send it as a bearer token: `curl -H "Authorization: Bearer " https:///api/notifications`.


## Similar templates

- [Rocky Linux](https://railway.com/deploy/rocky-linux) — Hosted Rocky Linux 9 workspace with SSH and persistent storage. 🚀
- [Foundry Virtual Tabletop](https://railway.com/deploy/X5tR6G) — A Self-Hosted & Modern Roleplaying Platform
- [Letta Code Remote](https://railway.com/deploy/letta-code-remote) — Run a Letta Code agent 24/7. No inbound ports, just deploy.

Open this page in a browser: https://railway.com/deploy/octobox