Deploy and Host Möbius on Railway

Möbius is your portal to the world of AI agents — the harness and the interface for working with them. Describe the personal and work apps you need, coordinate the agents that build them, and keep everything they learn, all running on infrastructure you own outright. This template deploys the official image directly and fixes two real, reproducible bugs in the reference marketplace template's deploy configuration — not application bugs, deploy-config bugs, confirmed by reading Möbius's own source rather than guessed at.

About Hosting Möbius

This template runs ghcr.io/mobius-os/mobius:main — the project's own official image — completely unmodified. Everything this template adds lives in Railway's own service configuration: the healthcheck path, one pinned port variable, the volume mount, and a restart policy tuned to how Möbius itself expects to be restarted. No custom Dockerfile, no forked code.

Möbius serves as one container backed by a single persistent volume: your chats, apps, agent memory, and files all live there, surviving restarts and image updates. It's a progressive web app you can install on your phone or desktop, reachable over one HTTPS endpoint with nothing else to wire up — no separate database, no cache, no message queue.

What Was Actually Wrong With the Reference Template

Two things, both confirmed directly from source rather than inferred from symptoms.

The healthcheck path doesn't exist. The reference template's service config sets healthcheckPath to /recover/health. A full search across the entire mobius-os/mobius repository — every route file, every router registration — turns up zero occurrences of that string anywhere in the code. The real health and readiness routes, registered explicitly in backend/app/main.py, are /api/health, /api/health/strict, /api/ready, and /api/ready/agent. Interestingly, the project's own railway.toml (checked into the repo, presumably meant for exactly this kind of deployment) already specifies /api/ready correctly — the marketplace template's own config simply doesn't match the project's own documented recommendation. This template uses /api/ready, which is both the one the app actually serves and the one the maintainers themselves chose.

The port isn't pinned, and that's a real trap here specifically. Möbius's entrypoint.sh computes its listening port as _public_port=${PORT:-8000} — it honors whatever $PORT value Railway auto-injects for the service, falling back to 8000 only if nothing is set. Deployed without setting PORT explicitly, Railway auto-assigned 8080 in testing here — while the image's Dockerfile (written primarily for VPS/docker-compose use, where a Caddy reverse proxy sits in front on port 8000) still declares EXPOSE 8000, and a service domain configured to match that declaration ends up targeting a port nothing is actually listening on. The result is genuinely confusing to debug from the outside: the deployment reports SUCCESS, Railway's own internal healthcheck against the correct (auto-assigned) port passes cleanly, and yet the public domain returns 502 Application failed to respond indefinitely, because the domain's target port and the app's real listening port have silently diverged. Setting PORT=8000 explicitly — pinning both the app and the domain to the same known value — closes that gap completely.

What Was Verified

Both fixes were confirmed by deploying, not just reasoned about. With the healthcheck pointed at /recover/health and no PORT pinned (matching the reference template's actual published configuration), the deployment either fails the healthcheck outright or reaches SUCCESS while 502ing on the public domain — reproduced directly rather than assumed. With both fixes applied — /api/ready as the healthcheck, PORT=8000 set explicitly — the deploy log shows Uvicorn binding to 0.0.0.0:8000 (matching the domain's target port exactly), and the public domain serves real responses: GET /api/ready returns 200 with {"ready":true,"boot_id":"..."}, and GET /api/health returns 200 with a full status payload including the build SHA and boot protocol version.

Common Use Cases

Build the apps you need: dashboards, trackers, small tools, described in chat and built by the agent alongside you
A private AI workspace: agents that remember your decisions, preferences, and project context across every session
Delegated and scheduled work: hand off parallel tasks or overnight jobs, review results when you're back
A shared household or team agent: one instance that sharpens its own skills, apps, and memory nightly through Reflection
Data residency: keep sensitive work on infrastructure you actually control, not a third-party's servers

Dependencies for Möbius Hosting

Möbius is self-contained — the image bundles the agent runtime and app compiler, and one persistent volume covers everything it needs to remember. The only thing you bring is your own AI provider connection.

Deployment Dependencies

Möbius Source Code — MIT
Möbius Homepage
Official image: ghcr.io/mobius-os/mobius

Implementation Details

No external database, cache, or additional services — one volume at /data covers all persistent state. The restart policy is set to ALWAYS with a 3-retry cap, matching the reasoning in Möbius's own railway.toml: a planned restart drains cleanly and exits 0, and an ON_FAILURE policy would never revive that clean exit, leaving the instance 502ing until someone notices and manually redeploys. ALWAYS handles the clean-restart case correctly while the retry cap still bounds a genuine crash loop.

Why Deploy Möbius on Railway?

Railway gives Möbius a home that's genuinely yours — one click provisions the container and its volume, attaches a public URL, and keeps the image current, with no Dockerfile to maintain and no server to patch. Because everything lives inside your own Railway project, your data and your agent's memory are never shared with or locked into anyone else's platform.

Beyond the infrastructure, this template specifically closes the gap between "the template exists" and "the template actually deploys and stays reachable." A healthcheck pointed at a route that was never registered, and a port that can silently drift between what the app binds to and what the public domain targets, are exactly the kind of deploy-config bugs that are invisible until you're the one debugging a 502 with a green deploy log staring back at you.

Frequently Asked Questions

Why does the reference Möbius template show reduced health?

Its configured healthcheck path, /recover/health, isn't a route that exists anywhere in the Möbius codebase — every healthcheck attempt against it fails by construction. This template points at /api/ready instead, the actual readiness endpoint, which is also what the project's own railway.toml specifies.

Why pin `PORT=8000` manually — isn't that Railway's job?

Normally Railway's own port handling is enough, but Möbius reads Railway's auto-injected $PORT directly inside the app (entrypoint.sh), and that assigned value isn't guaranteed to match what the service's public domain has been configured to route to. This template pins both to the same value so they can't drift apart — a real failure mode reproduced directly, not a hypothetical one.

Does this template change how Möbius behaves?

No. It's the unmodified official image — every difference from a bare docker run is Railway service configuration: healthcheck path, one environment variable, the volume mount, and the restart policy.

What do I configure myself after deploying?

Just an AI provider connection (Claude or Codex), from Settings inside the app. SECRET_KEY generates itself automatically on first boot — Möbius's own entrypoint handles that for exactly this one-click scenario.

Where can I download Möbius?

Source is on GitHub at github.com/mobius-os/mobius. Use this template to deploy the official image with both known deploy issues already fixed, in one click.

Source for this template's docs: https://github.com/shruti060701/mobius-railway