eidos-agi/railguey

railguey

<p align="center" <img src="https://raw.githubusercontent.com/eidos-agi/railguey/main/logo.png" alt="railguey" width="500" </p

<p align="center" Project-scoped Railway CLI.<br Reads <codeRAILWAYTOKEN</code from each project's <code.env.local</code, with no Railway account login or repo linking. </p

<p align="center" <a href="https://pypi.org/project/railguey/"<img src="https://img.shields.io/pypi/v/railguey" alt="PyPI"</a <a href="https://github.com/eidos-agi/railguey/actions/workflows/ci.yml"<img src="https://github.com/eidos-agi/railguey/actions/workflows/ci.yml/badge.svg" alt="Tests"</a <a href="https://pypi.org/project/railguey/"<img src="https://img.shields.io/pypi/pyversions/railguey" alt="Python"</a <a href="LICENSE"<img src="https://img.shields.io/github/license/eidos-agi/railguey" alt="License"</a </p

---

railguey is for teams and businesses that need reliable Railway deployments. It is not the simplest way to deploy — Railway's built-in GitHub app is simpler. But railguey is more reliable, because it draws a cleaner engineering boundary.

Why not just use Railway's GitHub App?

Railway's GitHub App is fast to set up: connect your repo, push to main, and your service deploys. For prototyping, that speed is genuinely great. But speed of setup and quality of engineering are different things.

The GitHub App bundles five responsibilities into one opaque chain: watch for code changes, authenticate to GitHub, receive a webhook, clone the repo, build and deploy. When the chain works, it feels like magic. When it doesn't — and it has broken four times in four months — there is no observability, no retry, and no notification. Your push goes in. Nothing comes out. You find out when a customer does.

git push
   |
   v
GitHub webhook -> Railway GitHub App -> clone/build/deploy
   |                    |                     |
   +-- missed event     +-- auth drift        +-- silent trigger failure

Every decision diamond in this diagram is a place where the chain can silently break. Missed webhooks, lost build triggers, GitHub App auth failures — all produce the same result: nothing happens, and nobody tells you.

This isn't a bug. It's an architectural choice. Railway chose to own the entire pipeline from push to deploy, which means every failure in GitHub's webhook delivery becomes Railway's problem — and yours.

How railguey fixes this

railguey separates concerns. GitHub Actions watches your repo (GitHub watching GitHub — the thing it was built for). railguey handles the deploy via Railway's API using project-scoped tokens. Railway builds and runs your service (the thing it was built for). Each system does one job.

git push
   |
   v
GitHub Actions -> tests -> railguey -> Railway API -> build/deploy
       |             |        |              |
       +-- visible   +-- fail +-- nonzero    +-- deployment status

If CI fails, GitHub tells you. If the deploy fails, the CLI returns an error. If the service is unhealthy, railguey doctor catches it. Every step is observable, retryable, and owned by the system best suited to do it.

Fast delivery and good engineering aren't opposites — but Railway's GitHub App trades the second for the first. railguey gives you both.

| Doc | What it covers | |-----|---------------| | WHY-NOT-RAILWAY-APP.md | The architectural argument — why coupling CI/CD triggering with deployment is a design flaw, not just a bug | | WHY-RAILGUEY.md | The evidence — four incidents, community reports, and what the project-token pattern does differently | | WHY-RAILGUEY.md#case-study | Real-world case study — ghost GitHub repo links silently blocked env var operations across 5 services | | docs/railway-agent-ssh.md | railguey research — asking Railway's own agent about Railway services over ssh railway.new: setup, persistent conversations, flags, troubleshooting |