Skip to main content
A service runs one part of your app, such as a frontend or an API. Each gets a public HTTPS URL, runtime settings, environment variables, and a deployment history. Services cost $1.50/month from workspace credits, or $0.25/month for workspaces that pay with x402 on Polygon. Use one project per codebase, with separate environments for development, staging, and production.

How it works

Choosing a deploy method

Source builds use your Dockerfile if you have one, or detect your framework automatically with Nixpacks or Railpack.

Creating a service

For GitHub, POST /v1/projects/from-repo creates the project, environment, services, and deployments in one request. See getting started for the token and an example. Connect private repositories through GitHub integrations first.
  • Locus reads .locusbuild if present, or creates a single web service.
  • Set autoDeploy: true on a GitHub service to deploy each push to its branch.
  • For manual service creation or a pre-built image, use POST /v1/services. Request fields are in the API reference.

Service configuration

Your container must listen on port 8080; Locus sets PORT=8080. Defaults: Keep secrets in environment variables. For custom Dockerfile paths, build arguments, and error monitoring, see the service API reference.

Service URL

Each service gets a URL like https://svc-abc123.buildwithlocus.com, with HTTPS and WebSockets. You can also attach a custom domain.

Deployment lifecycle

Each release moves from queued through building and deploying to healthy, or ends as failed. Source builds typically take 3–7 minutes, and pre-built images 1–2 minutes. See deployments to monitor, cancel, roll back, or troubleshoot a release.

Monorepo support

A project can hold several services from one repository. Set each service’s rootDir to its source directory, such as services/api or services/web. One push deploys every service in the project.

Project configuration (.locusbuild)

Keep service, addon, and variable configuration in a .locusbuild file at the repository root. Locus reads it during from-repo setup and git-push deploys. See the monorepo guide for the format and variables for a full-stack example.

Next steps

Deployments

Follow, fix, and roll back releases.

Variables and connections

Connect services to each other and to databases.