Deploy and Host Mastra Factory on Railway

Mastra Factory is an open-source software factory from the team behind the Mastra agent framework. Connect a GitHub repository and Factory turns issues into plans, implementations and pull requests, with coding agents doing the work and your team approving each stage: intake, triage, planning, building, review and done.

About Hosting Mastra Factory

Factory is a Node.js server that serves its own web UI and API, keeps all state in Postgres with pgvector, and runs agent commands in a sandbox. This template runs the upstream Factory project (mastra-ai/softwarefactory-template, @mastra/factory 0.24.0) on Railway next to a pgvector Postgres, with no Mastra platform account needed.

Agents run their commands in a local sandbox inside the Factory container: they clone your repository onto a Railway volume, install, test and push from there. Set an E2B key later if you want every session in an isolated VM instead.

Sign-in goes through WorkOS, and only the email addresses you list can get in. Anyone else who signs in is refused, so strangers cannot use your container to run code.

Common Use Cases

Turn GitHub issues into reviewed pull requests, with a person approving the plan and the merge
Hand a backlog of small fixes, refactors and test gaps to coding agents
Run Claude, OpenAI or other models on your own subscriptions or API keys, with sessions you can watch live
Give a small team one shared agent workspace with per-person model accounts

Dependencies for Mastra Factory Hosting

Postgres with pgvector (included) for agent memory, sessions and Factory data
A free WorkOS account for sign-in
A GitHub App you create on your account or organization, for repository access
A model account: Anthropic or OpenAI subscription sign-in, or an API key from any supported provider

Deployment Dependencies

Mastra Factory: https://mastra.ai/factory and docs at https://factory.mastra.ai
Upstream source: https://github.com/mastra-ai/softwarefactory-template
Container image for this template: https://github.com/hmseeb/mastra-factory-railway
WorkOS: https://dashboard.workos.com
GitHub App permissions Factory needs: https://factory.mastra.ai/configure/github

Implementation Details

Before you click Deploy (5 minutes). The form asks for three values.

Create a WorkOS account at https://dashboard.workos.com. Under Authentication, turn on Email + Magic Auth (or whichever sign-in method you want). Copy the API key (sk_...) and Client ID (client_...) from API Keys.
Paste them into WORKOS_API_KEY and WORKOS_CLIENT_ID.
Put your email in FACTORY_ALLOWED_EMAILS. Add teammates separated by commas. Only these addresses can sign in, and only once WorkOS has verified them.

Right after it deploys. In WorkOS, go to Redirects and add https:///auth/callback, using the domain Railway gave the factory service. Then open your domain and sign in. (The button on the sign-in page reads "Continue with GitHub", but it opens WorkOS.)

Connect GitHub. Factory needs a GitHub App to see your repositories. Create one at GitHub → Settings → Developer settings → GitHub Apps → New GitHub App:

Callback URL and Setup URL: https:///auth/github/callback
Webhook URL: https:///web/github/webhook. Webhook secret: copy GITHUB_APP_WEBHOOK_SECRET from the factory service's Variables tab.
Repository permissions: Contents, Issues and Pull requests set to Read and write. Metadata is read-only and added automatically.
Events: Issues, Issue comment, Pull request, Pull request review, Pull request review comment.

After creating it, generate a private key, then set these five variables on the factory service and redeploy: GITHUB_APP_ID, GITHUB_APP_SLUG (the name in the app's URL), GITHUB_APP_CLIENT_ID, GITHUB_APP_CLIENT_SECRET, and GITHUB_APP_PRIVATE_KEY (paste the whole .pem file). In Factory's onboarding, Connect GitHub, install the app on the repositories you want, and pick one.

Choose a model. Onboarding offers sign-in with an Anthropic (Claude Pro or Max) or OpenAI (ChatGPT) subscription, or an API key from a long list of providers. Each person can use their own account. For ChatGPT sign-in, first turn on device code sign-in under ChatGPT Settings → Security.

Pull requests from agents. GitHub App tokens cannot run gh commands inside the sandbox. To let agents open pull requests, save a classic personal access token with repo scope under Factory's Settings → Repositories → GitHub CLI tokens.

Variables

Variable	What it does
`WORKOS_API_KEY`, `WORKOS_CLIENT_ID`	WorkOS sign-in
`FACTORY_ALLOWED_EMAILS`	Comma-separated emails allowed in. Required; the server refuses to start without it
`MASTRACODE_PUBLIC_URL`	Public origin for every OAuth callback. Change to `https://your.domain` after adding a custom domain, and update WorkOS and GitHub to match
`FACTORY_CREDENTIAL_ENCRYPTION_KEY`	Encrypts stored model keys and tokens, generated per deploy. Never change it, or stored credentials become unreadable
`WORKOS_COOKIE_PASSWORD`	Seals sessions and signs OAuth state, generated per deploy
`GITHUB_APP_*`	Your GitHub App. All five must be set for GitHub to light up
`GITHUB_APP_WEBHOOK_SECRET`	Generated per deploy. Paste the same value into your GitHub App
`FACTORY_SANDBOX_PROVIDER`	`local` runs agent commands in the Factory container
`E2B_API_KEY`	Optional. To use isolated E2B sandboxes, set this and clear `FACTORY_SANDBOX_PROVIDER`

Other upstream settings (Linear, Jira, GitLab, Slack, Amazon Bedrock) can be added as variables on the factory service; see the environment reference.

Troubleshooting

WorkOS shows "Invalid redirect URI". Add https:///auth/callback under WorkOS Redirects, exactly, including https://.
Sign-in finishes but lands back on the sign-in page. Your email is not in FACTORY_ALLOWED_EMAILS, or WorkOS has not verified it. Fix the variable and redeploy.
Deploy fails with FACTORY_ALLOWED_EMAILS is required. Set it; this is the lock that keeps the instance private.
Onboarding says GitHub is "Unavailable for this deployment". One of the five GITHUB_APP_* variables is missing. https:///web/github/status lists which.
"Couldn't load GitLab / Jira / incident.io". Expected when those integrations are not configured. Click Skip for now.

Scaling and limits. This template runs one Factory replica. Repository checkouts and agent work share the container's CPU and memory, so give the factory service more resources if you run many sessions at once, or move to E2B. Running several replicas needs Redis (REDIS_URL) and is not set up here. Data lives in Postgres, and checkouts live on the /data volume, so both survive redeploys.

Why Deploy Mastra Factory on Railway?

Railway is a singular platform to deploy your infrastructure stack. Railway will host your infrastructure so you don't have to deal with configuration, while allowing you to vertically and horizontally scale it.

By deploying Mastra Factory on Railway, you are one step closer to supporting a complete full-stack application with minimal burden. Host your servers, databases, AI agents, and more on Railway.