API reference (v1)

Base URL: your deployment, e.g. https://lgrcloud.example.com. JSON in and out. Errors look like {"error": {"type": "not_found", "message": "run run_x not found"}}. Starting runs, sending messages, launching or starting instances and scaling fleets up return 402 insufficient_credit when the organisation has no credit left (see Billing).

#Authentication

• API key: Authorization: Bearer lgr_.... Keys belong to one project. GET endpoints that stream (SSE) also accept ?token=.
• Browser session: the lgr_session cookie set after signing in. Pick the project with lgr-project: proj_... (or ?project= for SSE); otherwise the user's first project is used. Account management endpoints require a session.

#Runs

Run body:

{
  "task": "Fix the failing tests in tests/api and explain the cause",
  "agent": "billing-service@v3",
  "harness": "lagrange",
  "instructions": "Do not change public interfaces.",
  "workspace": { "repo": "github.com/acme/app", "ref": "main" },
  "model": { "name": "claude-sonnet-4-6" },
  "tools": ["Bash", "Read", "Edit"],
  "mcp_servers": [{ "name": "linear", "url": "https://mcp.linear.app/mcp", "secret": "LINEAR_TOKEN" }],
  "limits": { "max_minutes": 20, "max_cost_usd": 2, "max_turns": 80 },
  "approval": "ask",
  "profile": "dev",
  "continue": true,
  "persist_profile": true,
  "metadata": { "ticket": "ACME-142" },
  "callback_url": "https://example.com/hooks/lagrange"
}

Only task is required. Set at most one of profile, instance, fleet. continue resumes the harness conversation stored on the profile or instance. persist_profile: false runs on a profile without saving a new version. callback_url gets the result when the run finishes; see Callbacks.

A run on a fresh sandbox needs something to call a model with: a platform model (model.name such as tensorblock/gpt-5), or a key for the harness's provider in the project secrets or on the API host (OPENAI_API_KEY for codex, ANTHROPIC_API_KEY for claude-code and lagrange, or Claude Code's Bedrock and Vertex switches). With neither, codex and claude-code runs, on any target, use the platform model named after the harness's default, such as tensorblock/gpt-6.1-sol for codex (see Billing). When the platform doesn't have it, the run is refused with 400 and a message saying which to set. Runs on a profile or instance are not refused, since the harness state stored there may hold its own login.

Statuses: queued, running, succeeded, failed, cancelled.

#Agents and improvements

While a candidate serves runs, in a canary or in its first 50 runs after promotion, the platform compares it with the version it was built from once it has 10 finished runs. If its success rate is more than 10 points lower, or its cost per run more than 10% higher, a canary is stopped (rejected) and a promotion rolled back (rolled_back), with stopped_reason saying which.

Agent spec (the body of POST /v1/agents; everything but name is optional):

{
  "name": "support-bot",
  "harness": "lagrange",
  "model": { "name": "claude-sonnet-4-6" },
  "instructions": "Answer from the ticket history. Escalate refunds.",
  "bundle": "bnd_5d02c7a3b81e4f0a9c6d7e21",
  "skills": ["triage"],
  "setup": ["pip install --user -r requirements.txt"],
  "mcp_servers": [
    { "name": "linear", "url": "https://mcp.linear.app/mcp", "secret": "LINEAR_TOKEN" },
    { "name": "crm", "command": "python3", "args": ["scripts/crm_mcp.py"], "env": { "CRM_TOKEN": "${CRM_TOKEN}" } }
  ],
  "secrets": ["LINEAR_TOKEN", "CRM_TOKEN"],
  "egress": { "allow": ["api.zendesk.com", "*.githubusercontent.com"] },
  "limits": { "max_minutes": 30 }
}

harness is a built-in harness id, or {"command": "python3", "args": ["harness/main.py"]} to run the agent's own harness from its files; see the harness protocol. skills names skills in the bundle and defaults to all of them. Before the harness starts, each run unpacks the bundle's skills where the harness loads them, copies its workspace/ files into the working directory and runs the setup commands there; a failing command fails the run with its output. Instances and profiles keep what they were prepared with and run setup again only when the bundle or setup changes. An MCP server has either a url (with an optional bearer token secret) or a command that runs inside the sandbox; ${NAME} in its env is replaced with the project secret.

POST /v1/agents returns the agent with the new version, its endpoint, its console_url and warnings: what would make calls to it fail, such as secrets the spec uses that the project hasn't set, a platform model that isn't available, or a harness with no model to call. The deploy still succeeds, since secrets can be set afterwards and an agent served on an instance may use a login stored there. POST /v1/agents/:id/versions returns the same warnings. An unknown harness id is rejected.

POST /v1/agents/import is how the console deploys a folder. The body is the folder as a .tar.gz (Content-Type: application/gzip) or a .zip (application/zip); ?name= names the agent when the archive has no single top folder. The folder's lgr.yaml is used when it has one. Otherwise the spec is built as lgr import builds it, with every visible file and folder in the workspace (dot-files, .git, node_modules and the like are left out). The skills and files are stored as a bundle, and the response has the spec ready for POST /v1/agents (with bundle set), source (lgr.yaml or detected), bundle, the workspace files, the secrets the spec uses with whether each is set, and warnings.

POST /v1/agents/draft is how the console creates an agent from scratch. Drafting takes the model a minute or more, so it answers 202 with {id, status: "running"} at once; poll GET /v1/agents/draft/:id until status is done and read draft. A failed draft answers that poll with its error. A platform model (through Forge, like every model call) turns the description in prompt into {name, instructions, skills: [{name, description, instructions}], secrets: [{name, description, used_by}]}: the AGENTS.md text, up to a few skills, and the secrets those skills read, each with what it is for and where to get it, and the skills that read it. A secret that no skill or instruction reads is dropped. Outside services are called from skills over their HTTP APIs, with the secrets as environment variables, so a drafted agent needs no MCP servers to run. The console shows the draft for editing, then packs it as a folder and sends it to /v1/agents/import, so it is reviewed and deployed like an upload. Needs credit left, like a run; answers 503 when platform models are unavailable and 502 when the model's reply can't be read.

POST /v1/agents/:id/adjust is how the console adjusts a deployed agent. The model gets the version's instructions, its skills (each SKILL.md, and the names of the other files in the skill's folder) and its secrets, and the change in prompt. Like a draft, it answers 202 and is polled at GET /v1/agents/draft/:id; the finished draft has the whole agent after the change plus a summary, and the poll also returns base, the version as it was, so the change can be shown as a diff. Secrets the version already had are kept even when nothing the model sees reads them. POST /v1/agents/:id/adjust/save writes a new bundle from the version's: skills whose text changed get a new SKILL.md (keeping any other front matter), removed skills lose their folder, and everything else (workspace files, a skill's other files, harness, model, limits) is kept as it was.

With ?preview=true, a new version of an existing agent is added without going live: runs and API calls naming the agent keep the current version, while the Playground (or a run naming agent@v3) can try it. PATCH /v1/agents/:id with current_version makes it live. A new agent's first version is always live.

egress.allow limits the hosts the harness can reach while it works: example.com matches that host, *.example.com its subdomains. The model API (including a custom ANTHROPIC_BASE_URL or OPENAI_BASE_URL) and the agent's remote MCP servers are always allowed; setup commands may reach any public host. Blocked connections show up as egress blocked log events on the run. Without egress, any public host is allowed. Private and loopback addresses are never reachable. This is enforced when the server runs the egress proxy and sandboxes have no other route out (see the README's Sandboxes section).

#Bundles

A bundle is a .tar.gz with skills/<name>/SKILL.md (plus any files the skill uses) and workspace/.... lgr deploy builds and uploads it from skills and files in lgr.yaml. Bundles are content-addressed per project: uploading the same archive again returns the same id.

#Examples

Agents that ship with the platform, kept as agent folders under examples/. Deploying one creates an ordinary agent in the project, on the example's suggested harness and model when this deployment offers both, otherwise on the default harness. Its harness and model can be changed like any agent's.

#Compute

Instance states: provisioning, running, stopped, failed, terminated. Sizes: lgr.small (1 vCPU, 2 GiB), lgr.medium (2, 4), lgr.large (4, 8), lgr.xlarge (8, 16).

#Agent services

An instance or fleet with an agent (name, or name@v3 to pin a version) serves that agent. Messages become runs on the instance with the agent's current version, and the message source is recorded in the run's input.metadata.source (message, webhook or schedule).

Message body:

{ "message": "Check the error rate on the checkout service", "conversation": "continue", "metadata": { "ticket": "OPS-9" }, "callback_url": "https://example.com/hooks/lagrange" }

conversation is continue (the default for instances: resume the conversation stored on the instance) or new (the default for fleets). Messaging an instance that is not running returns 409.

Trigger body:

{ "name": "standup", "kind": "schedule", "instance": "desk", "schedule": "0 9 * * 1-5", "message": "Post the daily summary" }

Set exactly one of agent, instance, fleet; an agent gets a new run of its live version each time. kind is webhook or schedule. Schedules are five-field cron expressions in UTC and need a message. A webhook's message defaults to {{body}}; {{body}} is replaced with the request body, pretty-printed when it is JSON. Unknown and paused webhooks both return 404. A schedule missed while the API was down fires once when it comes back. A trigger with a callback_url sends the result of every run it starts there.

#Callbacks

A run started with a callback_url, directly, as a message, or by a trigger, has its result POSTed to that URL when it finishes:

POST /hooks/lagrange HTTP/1.1
content-type: application/json
user-agent: LagrangeCloud-Callbacks/1.0
lgr-delivery: dlv_3c9e01b2f7aa
lgr-event: run.completed
lgr-signature: t=1791403200,v1=5f1d…

{"id": "dlv_3c9e01b2f7aa", "type": "run.completed", "created_at": "2026-10-07T20:00:00.000Z", "run": { "id": "run_…", "status": "succeeded", "result": "…", "usage": { … }, "input": { … }, "console_url": "https://…/console/#run=run_…" }}

type is run.completed, run.failed or run.cancelled, and run is the run as POST /v1/runs returns it, with absolute links when LGR_PUBLIC_URL is set. Answer with any 2xx status. Anything else, including redirects, and no answer within 10 seconds count as a failure, and the same delivery is sent again after 30 seconds, 2 minutes, 10 minutes and 1 hour. Use lgr-delivery (the payload's id) to drop duplicates.

lgr-signature is t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>"> keyed with the project's signing secret. Recompute it over the raw body, compare in constant time, and reject timestamps more than five minutes old. The SDK exports verifyCallback(secret, header, body); the console's Settings → Callbacks has the same check for Node.js to copy.

Callback URLs must be http or https without credentials. Hosts that are, or resolve to, loopback, private or link-local addresses are refused, checked when the run starts and again on every attempt (LGR_ALLOW_PRIVATE_CALLBACKS=1 lifts this for self-hosted installs).

#Billing

Projects in an organisation spend its prepaid credit: runs pay for sandbox time, plus model tokens when they use the platform's model key rather than the project's ANTHROPIC_API_KEY / OPENAI_API_KEY secret (GET /v1/harnesses lists each harness's credential); instances pay for uptime, charged every minute and when they stop. A run on the platform's key gets limits.max_cost_usd capped at the credit left. Without credit, running instances are stopped once idle with a state_reason; their disks are kept.

#Platform

#Accounts