Services & Deployments

A service is a single deployable container in your environment. It defines what code to run, how to build it, and what resources it gets. Each service costs $0.25/month from the workspace credit balance.

PORT 8080 requirement

Every Locus container must listen on port 8080. The platform injects PORT=8080 and routes all traffic there. Pre-built images that default to port 80 (e.g., nginx, httpd) will fail health checks unless reconfigured. Just make sure your app reads the PORT environment variable — most frameworks do by default.

Creating a service

Option A: from-repo (recommended)

If you have a GitHub repo, use POST /v1/projects/from-repo to create everything in one call — project, environment, services, and initial deployments. It auto-detects a .locusbuild file for multi-service repos, or creates a single web service with sensible defaults.

curl -s -X POST https://api.buildwithlocus.com/v1/projects/from-repo \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "my-app",
    "repo": "my-org/my-repo",
    "branch": "main"
  }'

Response includes the created project, environment, services, and deployment IDs.Private repos: The user must first connect their GitHub account via the Locus dashboard at https://buildwithlocus.com/integrations. Do not send users to the raw GitHub App URL — always direct them to the integrations page.

Option B: Pre-built image (fastest)

Provide a pre-built Docker image URI. Skips the build step entirely — goes straight from queued to deploying.

curl -s -X POST https://api.buildwithlocus.com/v1/services \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "'"$PROJECT_ID"'",
    "environmentId": "'"$ENV_ID"'",
    "name": "web",
    "source": {
      "type": "image",
      "imageUri": "registry.example.com/my-repo:latest"
    },
    "runtime": {
      "port": 8080,
      "cpu": 256,
      "memory": 512,
      "minInstances": 1,
      "maxInstances": 3
    }
  }'

Architecture: Pre-built images must be built for linux/arm64. Use docker build --platform linux/arm64 if building on a non-ARM machine. Images built from source (GitHub or git push) are handled automatically.

Option C: GitHub repo (manual setup)

Create a service with a GitHub source. Use this when you need more control than from-repo provides.

curl -s -X POST https://api.buildwithlocus.com/v1/services \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "'"$PROJECT_ID"'",
    "environmentId": "'"$ENV_ID"'",
    "name": "web",
    "source": {
      "type": "github",
      "repo": "my-org/my-repo",
      "branch": "main"
    },
    "buildConfig": {
      "method": "dockerfile",
      "dockerfile": "Dockerfile",
      "buildArgs": {"NODE_ENV": "production"}
    },
    "runtime": { "port": 8080, "cpu": 256, "memory": 512 },
    "autoDeploy": true
  }'

With autoDeploy: true, Locus triggers a new deployment on every push to the configured branch.

Choosing a deploy method

  Have a GitHub repo?
      │
      ├── YES ──→ Use from-repo (recommended)
      │           POST /v1/projects/from-repo
      │           • Auto-detects .locusbuild
      │           • One call: project + env + services + deploy
      │
      └── NO
           │
           ├── Have local code? ──→ Manual setup + git push
           │                        Create project/env/services, then
           │                        git push locus main
           │
           └── Have a Docker image? ──→ Pre-built image
                                        source.type: "image" with imageUri

Method	When to use	Source field
`.locusbuild` + `from-repo`	You have a GitHub repo (any size). One call creates project + env + services + deploys. Recommended for all repos.	`source.type: "github"` (auto)
Manual setup + `git push`	You have local code and no GitHub repo. Create project/env/services manually, then push code via git remote.	`source.type: "s3"` with `rootDir`
Pre-built image	You already have a Docker image in a container registry.	`source.type: "image"` with `imageUri`

Do NOT use from-repo with a fake or placeholder repo value. The repo field must be a real GitHub repository — Locus clones source code from it. If you don’t have a GitHub repo, use manual setup + git push instead.

One project per codebase

Each distinct codebase or application must get its own project and environment. Do not reuse an existing project/environment to deploy a different codebase.

Deploying github.com/alice/app-one? Create a new project for it.
Deploying github.com/bob/app-two next? Create another new project — do not deploy it into the project you created for app-one.
A project that previously failed? You may retry in the same project. But if the user gives you a different repo or codebase, always start fresh with a new project.

Service configuration

Runtime fields

Field	Default	Description
`port`	8080	Auto-injected — all containers must listen on 8080
`cpu`	256	CPU units (256 = 0.25 vCPU)
`memory`	512	Memory in MB
`minInstances`	1	Minimum running containers
`maxInstances`	3	Maximum running containers

Service fields

Field	Default	Description
`startCommand`	(image CMD)	Overrides the container’s CMD. Runs as `sh -c "<command>"`. Use for pre-start steps like `npx prisma migrate deploy && npm start`
`healthCheckPath`	`/`	Custom health check path (e.g., `/health`, `/healthz`, `/_health`)
`errorPatterns`	`ERROR/FATAL/Exception`	Custom error patterns for monitoring (array of strings)

Build config fields

Field	Default	Description
`method`	`dockerfile`	Build method
`dockerfile`	`Dockerfile`	Path to Dockerfile relative to the service root
`buildArgs`	`{}`	Docker build arguments (e.g., `{"NODE_ENV": "production"}`)

buildConfig fields are only available via the direct POST /v1/services API. They cannot be set in a .locusbuild file — .locusbuild uses auto-detection for builds. buildArgs are only applied during fresh builds (new deployments from source), not on redeploys.

Service URL

The service creation response includes a url field — the live auto-subdomain URL once deployed:

{
  "id": "svc_abc123",
  "name": "web",
  "url": "https://svc-abc123.buildwithlocus.com"
}

Service URLs support HTTPS, WebSockets (wss://), and all HTTP methods. No extra configuration needed for WebSocket connections — the edge router forwards Upgrade and Connection headers with a 24-hour connection timeout.

After deployment reaches healthy, the public URL may return 503 for up to 60 seconds while the container registers with service discovery. This is normal, not a bug.

Check service runtime status

curl -H "Authorization: Bearer $TOKEN" \
  "https://api.buildwithlocus.com/v1/services/$SERVICE_ID?include=runtime"

Response includes runtime_instances:

{
  "id": "svc_abc123",
  "runtime_instances": {
    "runningCount": 1,
    "desiredCount": 1,
    "pendingCount": 0
  }
}

runtime_instances is cached with a 30-second TTL. After a deployment reaches healthy, runtime counts may still show not_deployed for up to 30 seconds. Use deployment status as the primary readiness signal.

Deployment lifecycle

Every deployment moves through a sequence of statuses:

queued → building → deploying → healthy
                                  ↘ failed

Status	Duration	What’s happening
queued	5-30 seconds	Waiting for a build worker
building	2-5 minutes	Cloning repo and building image (GitHub/git push only)
deploying	30-90 seconds	Pulling image, starting container, running health checks
healthy	Terminal	Container running, health checks passing
failed	Terminal	Something went wrong — check logs
cancelled	Terminal	Deployment cancelled by user
rolled_back	Terminal	Replaced by a rollback deployment

Image deployments skip the building step entirely.

A deployment in queued for 2-5 minutes is normal — the build phase starts in the background. Don’t assume something is broken until at least 7-8 minutes have elapsed.

Monitor a deployment

Poll every 60 seconds until the status is terminal (healthy, failed, cancelled, or rolled_back).

# Poll once — do NOT use a blocking while loop
STATUS=$(curl -s -H "Authorization: Bearer $TOKEN" \
  "https://api.buildwithlocus.com/v1/deployments/$DEPLOYMENT_ID" | jq -r '.status')
echo "$(date +%H:%M:%S) — $STATUS"

Deployment details

durationMs — milliseconds from creation to completion (null if still running)
lastLogs[] — last 20 log lines from the build or runtime phase (on failed deployments)
metadata.phaseTimestamps — workflow timing breakdown:

Phase timestamp	Meaning
`queued`	Deployment record created
`execution_started`	Workflow execution started
`building`	Build phase entered (source builds only)
`deploying`	Deploy phase entered
`task_definition_registered`	Container task definition registered
`first_task_healthy`	First container passed health checks
`healthy` / `failed`	Terminal state

Monorepo support

For projects with multiple services in a single repo, set a rootDir on each service to point to its subdirectory. A single git push uploads the entire repo once and triggers a deployment for each service.

my-project/
├── services/
│   ├── api/          ← rootDir: "services/api"
│   │   ├── Dockerfile
│   │   └── src/
│   └── web/          ← rootDir: "services/web"
│       ├── Dockerfile
│       └── src/
└── package.json

Project configuration (.locusbuild)

A .locusbuild file at the repo root is the recommended way to configure any Locus project — single-service or multi-service. It defines services, addons, environment variables, and build settings in a version-controlled file that Locus auto-detects when using from-repo. See the SKILL.md monorepo companion guide for the full .locusbuild file format, setup, and examples.

Troubleshooting

Deployment stuck in queued

Deployments in queued for 2-5 minutes is normal — the build is starting up
If stuck for more than 10 minutes, check the deployment logs for errors
Verify the service configuration is valid (source type, image URI, etc.)

Health check failing

Ensure your app exposes a health check endpoint returning HTTP 200
Verify your app listens on port 8080 (the platform auto-injects PORT=8080)
Alpine images may need wget installed: apk add --no-cache wget
Check container logs for startup errors (crash loops, missing deps)

503 Service unavailable

Confirm the deployment reached healthy status
If recently deployed, allow 30-60 seconds for service discovery registration
Verify containers are running via ?include=runtime
Check that the service URL format is correct

Build failing

Check build logs for the specific error
Verify your Dockerfile is valid (or that auto-detection supports your framework)
Ensure all build dependencies are available in the build context
For GitHub sources, confirm Locus has access to the repository

Getting started

Features

Agent tools

Build with Locus

Checkout

Services & Deployments

PORT 8080 requirement

Creating a service

Choosing a deploy method

One project per codebase

Service configuration

Runtime fields

Service fields

Build config fields

Service URL

Check service runtime status

Deployment lifecycle

Monitor a deployment

Deployment details

Monorepo support

Project configuration (.locusbuild)

Troubleshooting

​PORT 8080 requirement

​Creating a service

​Choosing a deploy method

​One project per codebase

​Service configuration

​Runtime fields

​Service fields

​Build config fields

​Service URL

​Check service runtime status

​Deployment lifecycle

​Monitor a deployment

​Deployment details

​Monorepo support

​Project configuration (.locusbuild)

​Troubleshooting

PORT 8080 requirement

Creating a service

Choosing a deploy method

One project per codebase

Service configuration

Runtime fields

Service fields

Build config fields

Service URL

Check service runtime status

Deployment lifecycle

Monitor a deployment

Deployment details

Monorepo support

Project configuration (.locusbuild)

Troubleshooting