Agent Workflow

AI agents can set up infrastructure, deploy services, and manage the full lifecycle through the Locus API. This guide covers the recommended workflow, communication best practices, token management, and timing expectations.

Getting started

Load the SKILL.md

The Build with Locus SKILL.md is the canonical API reference for agents. Load it to learn all available endpoints, authentication, and request/response formats.

Read https://buildwithlocus.com/SKILL.md and follow the instructions

Authenticate

Exchange your claw_ API key for a JWT token. Use this token as a Bearer header on all subsequent requests. Tokens expire in 30 days — refresh as needed with POST /v1/auth/refresh.

Deploy

Create a project, environment, and service, then trigger a deployment. The full setup-to-deploy flow takes about a minute of API calls, plus 3-7 minutes of build time.

Agent communication guidelines

Never go silent for more than 30 seconds during multi-step workflows. The human should always know what you’re doing, what you’re waiting on, and how long it will take.

Core principles

Announce before you act. Tell the human what you’re about to do before making an API call.
Set time expectations. If an operation takes more than a few seconds, say how long.
Report outcomes. After each step, confirm success and share IDs/URLs the human might need.
Bridge the gaps. The setup steps (project, environment, service creation) each take under 1 second, but the human sees silence — narrate the flow.
Never block in long-running shell loops. Do not use while true loops to poll deployment status — they block tool output and make you go silent. Instead, poll once per tool call, report the status, then poll again in the next call.

Communication during setup

When walking through the core workflow (auth → project → environment → service → deploy), weave the steps naturally into your response:

Authenticating with Locus...                          → (exchange key)
Authenticated. Creating project "my-app"...           → (create project)
Project created (proj_abc123). Setting up production environment...  → (create env)
Environment ready. Creating service "web"...          → (create service)
Service created — it will be live at https://svc-xxx.buildwithlocus.com
Triggering deployment...                              → (create deployment)
Deployment queued (deploy_xyz). This will take 3-7 minutes for a GitHub build.
I'll let you know when it's live.

Token management for agents

Get a fresh token at the start of every debugging session. Stale or expired tokens are the #1 cause of 401 Unauthorized errors. Verify your token works before debugging anything else:

curl -s https://api.buildwithlocus.com/v1/auth/whoami -H "Authorization: Bearer $TOKEN"

If /whoami returns 401, your token is bad. Get a fresh one and retry.

Persisting tokens across tool calls

Shell variables are lost between tool calls. Three strategies:

Chain commands in a single shell invocation using &&
Save to file: echo $TOKEN > /tmp/locus-token.txt and read it back: TOKEN=$(cat /tmp/locus-token.txt)
Re-exchange at the start of each tool call (fast, under 100ms)

401 error patterns

Symptom	Likely cause	Fix
ALL endpoints return 401	Token expired or invalid	Get fresh token via `/auth/exchange`
`/whoami` works, one endpoint returns 401	Endpoint routing issue	Check URL syntax, method, and path
Some endpoints work, others 401	Mismatched base URLs	Verify all calls use the same base URL

Deployment workflow

Trigger and inform

Trigger the deployment, then immediately tell the human what’s happening:

Deployment ID for reference
Current status (queued)
Expected wait time (3-7 minutes for GitHub/git push, 1-2 minutes for images)
That you’ll update them when it’s done

Monitor silently

Poll deployment status every 60 seconds. Do not send updates on every poll — the human doesn’t need to know it’s still building.

Report completion

When the deployment reaches healthy or failed, notify the human with the result, service URL (on success), or logs and next steps (on failure).

Operation timing reference

Operation	Expected Duration	Notes
Auth token exchange	<1s
Project/environment/service creation	<1s each	Fast, but narrate them
Deployment (GitHub source)	3-7 minutes	Full build + deploy
Deployment (pre-built image)	1-2 minutes	Skips build phase
Addon provisioning (Postgres)	30-60s
Addon provisioning (Redis)	10-20s
Domain verification (BYOD)	1-30 minutes	DNS propagation
Domain purchase registration	1-15 minutes
Environment variable update	<1s	Requires redeploy to take effect
Service restart/redeploy	1-3 minutes	Rolling restart, no rebuild

Best practices

Do	Don’t
Tell the human immediately when deployment is triggered	Send status updates every 10 seconds
Set clear timing expectations (3-7 min for builds)	Assume something is broken if `queued` lasts 2-3 min
Poll every 60 seconds	Poll faster than once per minute
Update human only on completion (success or failure)	Say “something might be wrong” before 7-8 min
Include the deployment ID for reference	Retry deployments without checking logs first
Fetch logs only on failure or when explicitly asked	Stream logs during normal builds

Capabilities

Capability	Description
Project management	Create, update, list, and delete projects
Environment setup	Create environments (dev, staging, production) within projects
Service configuration	Create services from GitHub, Docker images, or git push sources
Deployments	Trigger, monitor, cancel, rollback, and inspect deployments with log access
Environment variables	Set, merge, and resolve variables across scopes
Addons	Provision Postgres and Redis, with auto-injected connection strings
Custom domains	Register, verify, purchase, and attach domains to services
Git push deploys	Deploy code by pushing to the Locus git remote

Common scenarios

Deploy a new application

Create a project and environment
Create a service with the appropriate source (GitHub, image, or git push)
Set environment variables if needed
Trigger a deployment
Poll until healthy, then report the service URL to the human

Add a database to an existing service

Provision a Postgres addon in the service’s environment
Wait for addon status to reach available (30-60 seconds)
Add the addon template to the service’s variables: "DATABASE_URL": "${{db.DATABASE_URL}}"
Trigger a new deployment on the service
Verify the deployment reaches healthy

Update and redeploy a service

Push new code via git push locus main (or update the image URI)
If using git push, deployments trigger automatically for all services in the project
If using image source, trigger a new deployment manually
Poll until healthy and report to the human

Handle a failed deployment

Fetch deployment details — lastLogs[] contains the last 20 log lines
Common failures: health check timeout (missing /health endpoint), port mismatch (must be 8080), missing dependencies, build errors
Fix the issue (update code, variables, or service config)
Trigger a new deployment
Report the failure reason and fix to the human

Response format

Most CRUD endpoints return the entity directly (not wrapped in a data envelope). Lists use plural keys: {projects: [...]}, {services: [...]}, etc. Aggregate endpoints return named objects:

POST /v1/projects/from-repo returns { project, environment, services, deployments, ... }
GET /v1/variables/service/:id/resolved returns { variables: { ... } }

HTTP status codes: 200 (ok), 201 (created), 204 (deleted), 400 (bad request), 401 (bad/expired token), 402 (insufficient credits), 404 (not found), 500 (server error).

Companion guides

These guides cover features beyond the core deploy path. Load them on-demand when needed.

Guide	When to use
agent-quickstart.md	Copy-paste deploy scripts, SSE status streaming, error recovery
billing.md	Credit balance, payments, 402 handling
deployment-workflows.md	Deployment timing, cancel, rollback, restart, redeploy
monorepo.md	`.locusbuild` file format, from-repo setup, verification
logs.md	Stream or search logs, logging best practices
webhooks.md	Set up webhooks for deployment events, error alerts
addons.md	Provision Postgres/Redis, run queries, execute migrations
domains.md	Add custom domains (BYOD or purchase)
git-deploy.md	Git push deploy, GitHub App integration, auto-deploy
api-reference.md	Complete table of all 80+ API endpoints
troubleshooting.md	Platform architecture, common issues

Policy guardrails

Agent actions are subject to the spending controls configured in the Locus dashboard. Allowances, per-transaction budgets, and approval thresholds apply to any API calls that cost credits. See the Platform Walkthrough for details on configuring agent controls.

Getting started

Features

Agent tools

Build with Locus

Checkout

Getting started

Agent communication guidelines

Core principles

Communication during setup

Token management for agents

Persisting tokens across tool calls

401 error patterns

Deployment workflow

Operation timing reference

Best practices

Capabilities

Common scenarios

Response format

Companion guides

Policy guardrails

​Getting started

​Agent communication guidelines

​Core principles

​Communication during setup

​Token management for agents

​Persisting tokens across tool calls

​401 error patterns

​Deployment workflow

​Operation timing reference

​Best practices

​Capabilities

​Common scenarios

​Response format

​Companion guides

​Policy guardrails

Getting started

Agent communication guidelines

Core principles

Communication during setup

Token management for agents

Persisting tokens across tool calls

401 error patterns

Deployment workflow

Operation timing reference

Best practices

Capabilities

Common scenarios

Response format

Companion guides

Policy guardrails