Deploy Octobox

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.

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.

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 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

Deployment Dependencies

• Source: gridalpha/octobox-railway, built on octobox/octobox (AGPL-3.0-only)
• Base image: octoboxio/octobox
• Runtime: Ruby 4, Rails 8.1, Puma, Sidekiq 8, PostgreSQL 18, Redis 8

Hardware Requirements for Self-Hosting Octobox

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.