Hosted compute settings

Hosted compute settings decide whether a workspace lets nima run agent operations on nima-hosted VMs, and how much those runs may spend. The two operations below read and change that one settings object. Starting and controlling the operations themselves is on the operations page, and what a hosted VM is lives in hosted VMs.

Hosted compute settings routes and scopes

The two hosted compute settings routes below read and change one settings object.

Paths are relative to https://api.getnima.io. Both calls carry Authorization: Bearer <your key>, need the scope above, and are refused unless the caller is a workspace owner or admin (403 INSUFFICIENT_PERMISSIONS).

integrations:write cannot be picked when you create a key in Settings or on the OAuth consent screen. It comes only from a private Slack confirmation: an owner or admin runs /nima mcp-key integrations (or messages @nima mcp-key integrations) and confirms, and nima returns a 30-day key that carries that one scope. That key cannot start operations, which needs a separate mcp-key operations key. See Scopes and permissions.

If the platform's agent operations are not switched on, every route here answers 404. They are on in production today.

Read hosted compute settings

GET /v1/agent-compute returns the workspace's hosted compute settings object. It takes no parameters and no body. It is readable even when the workspace plan lacks agent compute, so you can read the defaults before anything is enabled. A workspace that never changed anything gets the defaults below.

curl https://api.getnima.io/v1/agent-compute \
  -H "Authorization: Bearer $NIMA_KEY"

{
  "enabled": false,
  "defaultTarget": "own_harness",
  "allowedKinds": [
    "implement_spec",
    "fix_ci",
    "reproduce_issue",
    "run_checks",
    "browser_check"
  ],
  "maxConcurrentOperations": 3,
  "maxOperationsPerDay": 10,
  "monthlyComputeBudgetUsd": 25,
  "monthlyAiBudgetUsd": 100,
  "defaultOperationBudget": { "aiUsd": 5, "activeMinutes": 60, "maxSessions": 10 },
  "maxOperationBudget": { "aiUsd": 25, "activeMinutes": 120, "maxSessions": 20 },
  "allowOperatorExec": false,
  "alertThresholdsPercent": [50, 80, 100]
}

Settings fields and defaults

The settings object has these fields. A stored value outside its range is clamped when read, and money values round to cents. allowedKinds and alertThresholdsPercent are de-duplicated, and thresholds are sorted ascending (a threshold outside 1 to 100 is dropped).

Operation kinds are implement_spec, fix_ci, reproduce_issue, run_checks, browser_check and task. task is left out of the default allowedKinds: an admin opts in by adding it to the list.

What the fields do:

• enabled is the opt-in. While it is false, a request for the nima_vm target is refused and only implement_spec can run, as a handoff to your own coding agent.
• defaultTarget is used only for implement_spec when the request names no target and hosted compute is enabled. Every other kind runs on a VM.
• maxConcurrentOperations and maxOperationsPerDay cap hosted operations. Hitting either fails the new operation instead of queueing it. The day is the UTC day. nima also applies its own per-workspace concurrency ceiling, and the lower of the two limits applies.
• monthlyComputeBudgetUsd and monthlyAiBudgetUsd are per UTC calendar month.
• defaultOperationBudget is what an operation gets when its requester names no budget. maxOperationBudget is the most a member can give one operation.
• allowOperatorExec lets the nima team run break-glass commands in your operations' containers. It stays off unless you turn it on.
• alertThresholdsPercent are the budget shares at which nima records a threshold event. nima does not deliver that event to a person today, so do not rely on it as an alert.

Update hosted compute settings

PATCH /v1/agent-compute changes the settings and returns { settings, cancelledOperations }. Send only the fields you want to change. Each field you send replaces the stored one; allowedKinds and alertThresholdsPercent are replaced as whole lists, not merged.

The body is strict. An unknown key, a wrong type or an out-of-range value is a 400 with the message Invalid agent compute settings, and nothing is saved. The check that the default budget stays within the maximum runs on the merged result, so lowering maxOperationBudget below the stored default fails unless you lower the default in the same call.

curl -X PATCH https://api.getnima.io/v1/agent-compute \
  -H "Authorization: Bearer $NIMA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "allowedKinds": ["run_checks", "browser_check", "task"],
    "monthlyAiBudgetUsd": 50
  }'

{
  "settings": {
    "enabled": true,
    "defaultTarget": "own_harness",
    "allowedKinds": ["run_checks", "browser_check", "task"],
    "maxConcurrentOperations": 3,
    "maxOperationsPerDay": 10,
    "monthlyComputeBudgetUsd": 25,
    "monthlyAiBudgetUsd": 50,
    "defaultOperationBudget": { "aiUsd": 5, "activeMinutes": 60, "maxSessions": 10 },
    "maxOperationBudget": { "aiUsd": 25, "activeMinutes": 120, "maxSessions": 20 },
    "allowOperatorExec": false,
    "alertThresholdsPercent": [50, 80, 100]
  },
  "cancelledOperations": 0
}

What enabling hosted compute checks

Sending enabled: true first checks the workspace plan, then the prices. If the plan does not include agent compute the call is a 403. If nima has not configured an agent model and harness, the model does not fit its harness, or compute and model prices are missing, the call is a 409. Nothing is saved when a check fails. Enabling grants no GitHub publishing permission: that is a separate consent, covered on the writers page.

What disabling hosted compute cancels

Any PATCH that leaves hosted compute off, including one that sends enabled: false, cancels every unfinished hosted (nima_vm) operation in the workspace with the end reason compute_disabled, and denies new budget leases and run tokens. cancelledOperations in the response is how many operations were cancelled. "Unfinished" means any state other than published, reported, failed, cancelled or expired, so parked operations are cancelled too. Handoffs to your own coding agent are not touched. Disabling does not revoke GitHub publishing consent and does not undo commits an operation already made.

Errors from hosted compute settings

Both operations return the standard error envelope. These are the cases specific to this resource.