Skip to main content

Deployment

Deploy the Factory Server to Mastra platform or self-host it in your own environment. Both options use the Factory Server project created in Get started.

Before you begin​

Choose a setup​

SetupFactory ServerSupporting services
Full platform (default)Mastra platformMastra platform auth, PostgreSQL, and sandboxes
Local server with platform resourcesYour computerMastra platform auth, PostgreSQL, and sandboxes
Fully self-hostedYour infrastructureYour auth provider, database, and sandbox provider

Continue with Deploy for the full-platform setup or Self-host when the Factory Server runs in your environment.

Deploy​

Use the generated project's deploy script to deploy to Mastra platform. The CLI builds and uploads the application to a platform environment and reports its public URLs.

  1. Check the server​

    From the Factory Server directory, run:

    npm run check
npm run build

    Review local environment values so a localhost callback origin isn't used by the deployed server.

  2. Prepare the environment​

    In Platform, choose the target project and review its environment configuration. Confirm the attached database, encryption key, provider access, integration credentials, and public origin.

    The public origin must point to the deployed Factory endpoint. Configure allowed origins only when serving the UI from a separate origin. A deployed server requires persistent database storage.

    See Environment variables for variable names and the distinction between Platform integration and sandbox credentials.

  3. Run the deployment​

    Inside your Factory project directory, run the deployment command:

    npm run deploy

    Review the CLI's organization, project, and environment selection. The default environment is production. You can pass flags to the deploy command to customize its behavior.

    Deployment flags

    To target another named environment, pass it explicitly:

    npm run deploy -- --env staging

    The CLI can create an environment if it doesn't exist. Review configuration and secret changes when prompted. Use the deployed Factory URL and credentials for the target environment.

    To configure a EU region for a new environment, pass --region eu:

    npm run deploy -- --env staging --region eu

    It doesn't relocate an existing environment. Confirm the chosen environment and attached database region in Platform before deploying.

    For a Factory project, the CLI derives a Factory URL and a Studio URL from the environment slug. Other project types use a server URL. Use the actual URLs returned for your project instead of constructing addresses from a project name.

  4. Verify the deployed Factory​

    Open the Factory URL reported by the CLI. Confirm sign-in returns to this server, repository access works, and existing provider credentials remain usable. Create a new issue in a subscribed source, investigate it, and verify the session's actual sandbox provider.

    Inspect the Platform deployment logs if a step fails.

Self-host​

Run Factory on a virtual machine, in a container, or on a hosting service that supports a persistent Node.js process. The build includes Factory's browser UI and API, so you can serve both from the same domain.

A self-hosted Factory Server can use Mastra platform services or your own providers. Configure Auth, Storage, and Sandboxes independently, and connect your preferred model providers.

For a fully self-hosted setup, create your project with the --no-platform flag:

npm create factory@latest my-factory -- --no-platform

The installer copies .env.example to .env without adding platform credentials, so configure your authentication, database, and sandbox providers before deployment.

Requirements​

  • Runtime: Node.js matching the engines.node requirement in your Factory project's package.json. Keep the server running so Factory can process intake and agent work in the background.
  • Storage: A persistent database. The generated server uses PostgreSQL with pgvector through DATABASE_URL. For another provider, follow Storage configuration.
  • Public endpoint: An HTTPS URL that supports streaming responses for live sessions. Set MASTRACODE_PUBLIC_URL to this origin and use it for authentication and integration callbacks.
  • Secrets: Provider and integration credentials in your deployment's environment settings. Keep the credential encryption key and state-signing secrets stable across deployments.
  • Sandbox environment: Network access to your chosen cloud sandbox provider. For local execution, install Git and your repository's build tools on the server, and use persistent disk space for session directories.

Deployment outline​

  1. Connect your Factory Server repository to your hosting service, or copy it to the machine where it will run. Configure your chosen providers in the project.

  2. Add the project's environment variables to the deployment environment. Set NODE_ENV=production and configure PORT for your hosting service. Update callback URLs for any auth or integration apps you manage.

  3. Install dependencies and build from the Factory Server directory:

    npm ci --include=dev
npm run check
npm run build

  4. Use npm run start as the service's start command. This uses the generated project's Mastra CLI and varlock dependencies, so retain them in the runtime environment. Configure automatic restarts and route HTTPS traffic to the server's listening port.

  5. Open the deployed Factory URL and sign in. Import an issue from your connected repository and run an investigation to confirm the agent can use its sandbox.

The build writes the server and Factory UI to .mastra/output. You can also package this output for a container deployment. See the Mastra server deployment guide for running the build directly with Node.js.