# What infrastructure do background coding agents need?

> The seven pieces a background coding agent needs, from sandbox to spend cap, what Nodus provides for each, and the cap math for an overnight GPU job.

Source: https://www.nodus-compute.ai/blog/infrastructure-for-background-coding-agents/
Build revision: 169237faa28dd1c66cd46998b23235aee0db1b80

A background coding agent needs seven pieces of infrastructure: an isolated sandbox per task, scoped access to the repo and secrets, compute that can run for hours with GPUs when the task needs them, a spend cap the agent cannot raise, logs and status it can poll, checkpoint and resume, and automatic cleanup. Nodus covers the compute side of that list through one MCP server: CPU Sandboxes, GPU Jobs that resume from checkpoints, Budgets that block new work, and logs the agent can read. Your git host and the agent loop itself come from elsewhere.

Most background agent guides stop at the sandbox, where the agent edits code and runs tests. The expensive part starts when the agent launches something long, like a fine-tune that runs overnight while nobody watches.

## What are the seven components, and which ones does Nodus cover?

Nodus covers all seven at least in part, and the gaps are specific: no GPU Sandboxes, no git hosting and no loop for your coding agent. We built this map from the current Nodus docs and checked every row against the linked page.

|Component|Why the agent needs it|What Nodus provides today|
|-|-|-|
|Isolated sandbox per task|Runs model-written code away from your laptop and other tasks|[Sandboxes](https://www.nodus-compute.ai/docs/guides/sandboxes/): CPU only, no outbound network by default, `maxCostUSD`, idle stop|
|Repo and secrets access|Clones private code and calls APIs without pasting keys|[Secrets](https://www.nodus-compute.ai/docs/guides/secrets/) redacted from logs; a [GitHub Connection](https://www.nodus-compute.ai/docs/guides/connections/) clones one repo with a short-lived read-only token|
|Long-running compute and GPUs|Training, evals and builds that outlive a chat session|[Jobs](https://www.nodus-compute.ai/docs/guides/jobs/) on a named GPU or a minimum GPU memory, with a `timeout`|
|A cap the agent can’t raise|Stops a loop or a wrong GPU count before it costs a weekend|[Budgets](https://www.nodus-compute.ai/docs/guides/billing/budgets/) with `action: Block`, plus `maxCostUSD` per run|
|Status and logs it can poll|Lets the agent check progress instead of guessing|MCP `wait`, `logs`, `describe` and `events`; [webhooks](https://www.nodus-compute.ai/docs/guides/webhooks/) such as `job.succeeded`|
|Checkpoint and resume|A lost machine or a cap costs minutes, not the whole run|`recovery.continuity: Checkpointed` restores `/nodus/state` on new capacity|
|Cleanup|Nothing forgotten keeps billing|Sandbox `maxLifetime` and `onIdle: Delete`; Job `ttlSecondsAfterFinished`|

Docs checked October 28, 2026.

GPU Sandboxes are not available yet: the [Sandboxes page](https://www.nodus-compute.ai/docs/guides/sandboxes/) says a spec with `resources.gpu` is refused. So the agent edits and tests in a CPU Sandbox, and anything that needs a GPU goes out as a Job.

## Why does every task need its own sandbox?

A separate sandbox per task keeps one agent’s mistakes out of everything else. Model-written code can delete files, fork processes or try to reach the network, and you want that contained.

On Nodus, each Sandbox runs on CPU machines Nodus operates, in its own network namespace with a default-deny firewall, its own cgroup limits and a non-root user, per the [isolation page](https://www.nodus-compute.ai/docs/concepts/sandboxes-isolation/). Egress is `Deny` unless you choose `AllowList` or `Open`. Creating a Sandbox with the same name and spec returns the existing one, which is how an agent reconnects after its own restart.

The same page is clear about the limit: anything you put in a Sandbox is readable by the code running there. Give it only the credentials its task needs, and keep egress closed unless the work needs the network.

## How should the agent get repo and secret access?

Give the agent short-lived, narrow credentials, never your personal token. The GitHub side of this is well understood: [GitHub’s own docs](https://docs.github.com/en/apps/overview) prefer GitHub Apps because they use fine-grained permissions and short-lived tokens.

Nodus follows that pattern for reads. A `GitHub` Connection installs the Nodus GitHub App, and a Sandbox clones a pinned commit with a token that can only read that one repository and never appears in the Sandbox’s files or environment. Secrets are stored once, never returned by the API, and redacted from logs. A command that pastes a secret’s literal value into `env` is refused with `SecretValueInEnv`.

What Nodus does not do is host your code or open pull requests. Pushing a branch and opening the PR stays with your git host and whatever identity your agent uses there.

## Where does the long-running GPU work run?

Long GPU work runs as a Job, not inside the agent’s session. A Job takes an image, a command, a GPU, a `timeout` and a `maxCostUSD`, then runs to completion while the agent does something else.

The agent creates it through the Nodus MCP server. The first `apply` call returns a dry run with the estimated cost and an `etag`, and nothing is created until a second call with `confirmed: true` and the same `etag`, as the [MCP guide](https://www.nodus-compute.ai/docs/guides/mcp/) describes. Connecting Claude Code to the hosted server is one command from the [connect page](https://www.nodus-compute.ai/connect/):

Terminal window

```sh
claude mcp add --scope user --transport http nodus https://api-next.nodus-compute.ai/mcp
```

Then run `/mcp` in Claude Code, choose nodus and sign in. The [MCP setup post](https://www.nodus-compute.ai/blog/give-claude-code-codex-cursor-gpus-mcp/) covers Codex and Cursor too.

## How much should the agent be allowed to spend overnight?

Set the per-run cap at the listed rate times GPUs times expected hours, plus about 20% headroom, and put a blocking Budget around all agent work. This is the rule we use, and here is the math for one run.

Say the agent launches a fine-tune at 6 pm that should take 8 hours on one NVIDIA H100. The H100 is listed at $2.60/hr on the [Nodus pricing page](https://www.nodus-compute.ai/pricing/), so the expected cost is 8 x $2.60 = $20.80. With 20% headroom, 8 x $2.60 x 1.2 = $24.96, so the cap is $25. That cap allows about 9.6 hours of H100 time (9.6 x $2.60 = $24.96).

```yaml
apiVersion: nodus.dev/v1
kind: Job
metadata:
  name: overnight-finetune
spec:
  image: nodus/pytorch
  command: [python, train.py]
  resources:
    gpu: H100
  timeout: 10h
  maxCostUSD: "25.00"
  recovery:
    continuity: Checkpointed
```

Now suppose the script hangs and nothing stops it. By 6 pm the next day, 24 hours in, it has cost 24 x $2.60 = $62.40. Left until 9 am Monday, a Friday evening launch runs 63 hours and costs 63 x $2.60 = $163.80. With the cap, it checkpoints and suspends with reason `MaxCostReached` at $25.

![Cumulative cost of one H100 job left running: uncapped it reaches $20.80 at 8 hours, $62.40 at 24 hours and $163.80 at 63 hours, while a $25 maxCostUSD cap stops it near $24.96 at 9.6 hours.](https://www.nodus-compute.ai/blog-charts/infrastructure-for-background-coding-agents/overnight-cap.svg) *A hung overnight job costs the cap, not the weekend.*

The `timeout: 10h` is a second guard: 10 x $2.60 = $26, so the $25 cap fires first. Whichever limit is reached first stops the run.

The cap is not the ceiling the agent can’t move, though. The [Budgets docs](https://www.nodus-compute.ai/docs/guides/billing/budgets/) say anyone can raise a run’s `maxCostUSD` at any time, but not lower it, so an agent with write access to Jobs can raise its own cap. The hard ceiling is a Budget with `action: Block`, created by you, with the agent’s MCP grant leaving out the scope to change Budgets. A monthly $500 Budget over everything the agent launches allows 24 such runs (24 x $20.80 = $499.20) before new work is refused with `402 BudgetExceeded`.

```yaml
apiVersion: nodus.dev/v1
kind: Budget
metadata:
  name: agent-monthly
spec:
  limitUSD: "500.00"
  period: Monthly
  scope:
    selector:
      matchLabels: {nodus.dev/launched-by: mcp}
  action: Block
  thresholds: [50, 80, 100]
```

Everything created through the MCP `apply` flow carries the label `nodus.dev/launched-by: mcp`, so this Budget covers agent work and nothing else. The [spending limits post](https://www.nodus-compute.ai/blog/ai-agent-gpu-spending-limits/) walks through the grant and key setup step by step.

## How does the cap change with the GPU the agent picks?

The same $25 buys very different amounts of time depending on the GPU, so derive the cap from the GPU, not from habit. Here is what one 8-hour run costs and how long a $25 cap lasts at each listed rate.

|GPU|Listed rate|8-hour run|Hours a $25 cap buys|
|-|-|-|-|
|NVIDIA L4|$0.43/hr|$3.44|58.1|
|NVIDIA A100 80 GB|$1.09/hr|$8.72|22.9|
|NVIDIA H100|$2.60/hr|$20.80|9.6|
|NVIDIA H200|$3.593/hr|$28.74|7.0|
|NVIDIA B200|$5.50/hr|$44.00|4.5|

Prices checked October 28, 2026 on the [Nodus pricing page](https://www.nodus-compute.ai/pricing/). Hours are $25 divided by the hourly rate.

![Hours of GPU time a $25 cap buys at listed Nodus rates: L4 58.1 hours, A100 80 GB 22.9 hours, H100 9.6 hours, H200 7.0 hours and B200 4.5 hours.](https://www.nodus-compute.ai/blog-charts/infrastructure-for-background-coding-agents/hours-per-cap.svg) *A $25 cap covers more than two days on an L4 and under five hours on a B200.*

If an agent asks for an H200 or a B200 for the 8-hour job, a $25 cap suspends it before it finishes. That is the point of computing the cap from the request: a mismatch shows up in the estimate, before any money is spent.

## How does the agent know what happened while it was away?

The agent should poll status and read logs, not trust its memory of what it launched. Through MCP, `wait` blocks up to 60 seconds for a state, `logs` reads up to 2,000 lines, and `describe` and `events` show why something stopped. Logs are kept after the machine is gone, per the [logs guide](https://www.nodus-compute.ai/docs/guides/logs/).

For a person, or an agent loop that sleeps between turns, webhooks are cheaper than polling. Events include `job.succeeded`, `job.failed`, `job.restored` and `job.max_cost_reached`. One caution from the MCP guide applies here: log output comes back marked as untrusted, and the agent must treat it as data, not instructions.

## What happens when a machine is lost or the cap is hit?

With checkpointing on, both cost minutes instead of the whole run. Your program writes its state to `/nodus/state` (the path is also in `NODUS_STATE_DIR`), and Nodus saves and restores that directory when capacity is reclaimed or the run moves. A Job that hits its cap also checkpoints, and raising `maxCostUSD` resumes it from there.

This is what lets an agent schedule GPU work on cheaper interruptible capacity without babysitting it. The [checkpointing post](https://www.nodus-compute.ai/blog/automatic-checkpointing-and-resume-for-training/) shows what to save and how often.

## What does Nodus not cover?

Nodus does not run your coding agent’s loop, host your code or review your pull requests. Those come from other tools.

* The agent loop: [Claude Code](https://code.claude.com/docs/en/overview), [Codex Cloud](https://developers.openai.com/codex/cloud), where each task gets its own workspace and keeps going while your computer sleeps, or [Cursor Cloud Agents](https://cursor.com/docs/cloud-agent), which run in isolated cloud VMs and support MCP servers.
* Git hosting and pull requests: your git host, ideally through an app with fine-grained, short-lived tokens.
* GPU inside the sandbox: not available on Nodus yet; send GPU work out as a Job.

Nodus also has [Agents](https://www.nodus-compute.ai/docs/guides/agents/), in Beta, where each run works in its own sandbox and survives restarts by replaying recorded steps. It is separate from connecting an outside coding agent over MCP. If you want the agent to go from a prompt to a trained model, the [Claude Code training walkthrough](https://www.nodus-compute.ai/blog/claude-code-train-model-from-prompt/) shows the full loop.

## FAQ

### Can the agent create GPU Sandboxes on Nodus?

Not yet. The Sandboxes docs say a spec with `resources.gpu` is refused, so run tests in a CPU Sandbox and submit GPU work as a Job with its own cap.

### Can an agent lower or remove a cap to save money?

No. A run’s `maxCostUSD` can be raised but not lowered, and on a Sandbox a lower cap or no cap counts as a different spec. To stop spend early, suspend or cancel the run.

### What happens to agent work when the Budget runs out?

New work in scope is refused with `402 BudgetExceeded`. Running work in scope checkpoints and stops gracefully, then resumes when you raise the limit or the next month starts.

### How do I disconnect an agent that misbehaves?

Delete its grant with `nodus delete oauthgrant <name>` or in Console, Settings, Connected agents. The client stops working within 30 seconds, even with a token it already holds.

### Do finished Jobs keep costing anything?

Compute billing stops when a Job finishes. Jobs from `nodus run` are deleted after 30 days by default, and deleting a Job deletes its outputs, so download results first.