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
.locusbuildif present, or creates a singlewebservice. - Set
autoDeploy: trueon 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 setsPORT=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 likehttps://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’srootDir 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.