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

​
Choosing a deploy method

GitHub and git-push sources support automatic builds. Pre-built images must target linux/arm64.

​
Creating a service

For GitHub, start with:
Deploy a GitHub repository
Replace repo with your repository. Connect private repositories through GitHub integrations first. See authentication to get $TOKEN. Locus reads .locusbuild when present, or creates a single web service. The response includes the project, environment, services, and deployments. Set autoDeploy: true on a GitHub service to deploy each push to its configured 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. Configure a health check path that returns HTTP 200. Keep secrets in environment variables. For custom Dockerfile paths, build arguments, and error monitoring, use the service API reference.

​
Service URL

The creation response includes your service’s url, for example https://svc-abc123.buildwithlocus.com. Service URLs support HTTPS and WebSockets. You can also attach a custom domain.

​
Deployment lifecycle

Image deployments skip the build step. Source builds typically take 3–7 minutes, and pre-built images take 1–2 minutes.

​
Monitor a deployment

Follow progress in the dashboard or fetch a deployment by ID:
Check deployment status
Check about once a minute until it finishes. Failed deployments include recent logs. For running container counts, use GET /v1/services/:id?include=runtime. To cancel, roll back, restart, or redeploy, see the deployment reference.

​
Monorepo support

A project can contain multiple services from one repository. Set each service’s rootDir to its source directory, such as services/api or services/web. One push deploys all services 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 file format and variables for a full-stack example.

​
Troubleshooting

Start with the deployment logs. Common causes are a failing health endpoint, a port other than 8080, missing variables, or inaccessible source code. A newly healthy deployment may take up to 60 seconds to serve traffic. For persistent failures, use the troubleshooting guide.