# How to run a coding agent in a sandbox with a mock API

> Run the agent's commands with no route off the machine, give its tests a mock it starts itself, and make any connection that escapes fail the suite.

Source: https://voxgig.com/howto/coding-agent-sandbox-with-a-mock-api

- Audience: platform-team
- Level: intermediate
- Languages: typescript
- Verified: 2026-11-20
- Published: 2026-11-20

## Short answer

Run the agent inside a boundary with no outbound network: a Docker container on the none network, Codex CLI with --sandbox workspace-write, or Claude Code's /sandbox with an empty domain list. Give its tests a mock the test process starts: Prism on 127.0.0.1, or sdkgen's test mode in process. Import a guard that refuses non-loopback connections, so an escaped call fails a test.

---
## You will need

Node 22 or later, an OpenAPI 3 document with response examples, and a coding agent that can run
shell commands. Verified 2026-11-20 against Node 22.23.5. The sample's `api.json` has three
operations, an example on each success, and a declared 404.

Pick the boundary before the mock. The Docker [`none` network driver](https://docs.docker.com/engine/network/drivers/none/)
gives a container a loopback device and nothing else.[^1] Codex documents that its default
`workspace-write` mode
[keeps network access off](https://learn.chatgpt.com/docs/agent-approvals-security) until
`network_access = true` appears under `[sandbox_workspace_write]`. Claude Code's
[Bash sandbox](https://code.claude.com/docs/en/sandboxing) routes commands through a proxy that
checks `network.allowedDomains`, which starts empty.

## Approaches compared

| Approach | When it fits | What it costs you | When to pick something else |
| --- | --- | --- | --- |
| [NSwag client with an in-memory fetch](https://github.com/RicoSuter/NSwag/wiki/TypeScriptClientGenerator) | The client is NSwag's Fetch template, and tests can pass the constructor an object with `fetch` | A fake transport you write and keep matching the document, because NSwag generates no mock | You want the mock to follow the document without code |
| [Prism mock](https://github.com/stoplightio/prism/blob/master/docs/getting-started/03-cli.md) | Any client in any language, and the document carries good examples | One fixed example per response, so pages and missing ids all look alike | The tests must reach pagination or error branches unprompted |
| [sdkgen test feature](https://github.com/voxgig/sdkgen/blob/main/docs/reference/features.md) | The client is an sdkgen SDK, and tests should run with no server or port | Only exists inside a generated SDK, so the SDK must exist before the agent's tests | The agent is writing the client itself |
| [Swagger Codegen WireMock tests](https://swagger.io/docs/open-source-tools/swagger-codegen/codegen-v3/generators-configuration/) | A Java client, and you want a test class that starts WireMock already written | Stubs that answer 200 with no body, in a class marked `@Ignore` | The client is TypeScript, or the stubs need real bodies |
| [WireMock stubs and faults](https://wiremock.org/docs/simulating-faults/) | You need scripted answers per request, delays, and connection resets | A JVM or container in the test setup, and every stub authored by hand | The document's examples already say what the tests need |

Voxgig maintains sdkgen. It is one of five options here, not the recommendation.

Prism costs nothing to author and returns the same example for every call, which hides branches.
WireMock reaches every branch, at the price of writing each stub. sdkgen's test mode needs no
process at all, but only an sdkgen SDK has one. NSwag and Swagger Codegen leave the mock to you.
NSwag takes it as a constructor argument; Swagger Codegen writes a Java test to fill in.

## Generate an sdkgen client that answers from a seed

An sdkgen SDK needs no mock server, because its `test` feature is an in-memory transport. Add
the feature when you scaffold, then generate and compile. `generate.sh` ran these commands once,
outside the gate, and kept the compiled `.js` files in `generated/`:

```bash title="generate.sh"
npx --yes @voxgig/create-sdkgen@0.31.9 bookshelf --def api.json --target ts --feature test
(cd bookshelf-sdk/.sdk && npm run generate)
(cd bookshelf-sdk/ts && npm install --no-audit --no-fund && npm run build)
(cd bookshelf-sdk/ts/dist && find . -name '*.js' -exec install -D {} ../../../generated/{} \;)
echo '{ "type": "commonjs" }' > generated/package.json
```

The scaffold writes `.sdk/model/feature/test.aontu`, whose `options: active: false` keeps a
client built with `new BookshelfSDK(options)` live. Write the records the tests need as a seed,
keyed by entity and then by id:

```js title="fixtures.mjs"
export const seed = {
  entity: {
    book: {
      b1: { id: 'b1', title: 'Dune', author: 'Frank Herbert' },
      b2: { id: 'b2', title: 'Emma', author: 'Jane Austen' },
    },
  },
}
```

Construct the client with `BookshelfSDK.test(seed)`. It sets `feature.test.active` and hands the
seed to the feature, and every entity call is answered from the seed in process:

```js title="offline.mjs"
// sdkgen: the test feature answers from the seed, in process.
const sdk = BookshelfSDK.test(seed)
console.log('sdkgen client mode'.padEnd(34), sdk._mode)
await show('sdkgen list', async () => (await sdk.Book().list()).map((b) => b.data().title))
await show('sdkgen load b2', async () => (await sdk.Book().load({ id: 'b2' })).data().title)
await show('sdkgen load nope', async () => (await sdk.Book().load({ id: 'nope' })).data())
```

## Give the tests a mock they start themselves

A mock running in another terminal is the first thing a sandbox breaks. On Linux, Claude Code's
documentation says, the `localhost` of a command inside the sandbox is private to that command.
It reaches the servers it started itself and not the ones on the host. Start the mock from the
test process.

An NSwag client takes an object with a `fetch` method as its second constructor argument, so its
tests pass an in-memory one, which answers only the two `GET` routes the document declares.
`offline.mjs` runs the sdkgen client and the NSwag client, then makes the mistake the guard exists
for, a client constructed with no base URL.

```bash
node --experimental-strip-types offline.mjs
```

```text output
sdkgen client mode                 test
sdkgen list                        ["Dune","Emma"]
sdkgen load b2                     "Emma"
sdkgen load nope                   error: BookshelfSDK: load: request: 404: Not found
nswag listBooks                    ["Dune","Emma"]
nswag getBook nope                 error: ErrorDto {"error":"not found"}
sdkgen live client, list           error: BookshelfSDK: list: fetch failed
connections refused                ["api.example.com:443"]
```

The seeded client reaches the 404 branch on an id nobody seeded. The NSwag client throws the
parsed 404 body, an `ErrorDto`, rather than an `Error`, which an agent's `catch` may not expect.
The last client fell back to the document's server URL, and the guard refused it.

## Make an escaped connection fail the test

The sandbox stops the packet, but the agent only sees a connection error it may retry or skip.
A guard inside the test process turns the attempt into a named failure. Node's `fetch` and its
`https` module open their sockets through one method, which the test checks for both:

```js title="no-network.mjs"
const connect = net.Socket.prototype.connect
net.Socket.prototype.connect = function (...args) {
  const t = target(args)
  if (t.path || LOOPBACK.has(t.host)) return connect.apply(this, args)
  refused.push(`${t.host}:${t.port}`)
  const err = new Error(`no-network: refused a connection to ${t.host}:${t.port}`)
  err.code = 'ENETUNREACH'
  process.nextTick(() => this.destroy(err))
  return this
}
```

Import it on the first line of each test file, and assert that `refused` did not grow. Loopback
stays open, so Prism or a `node:http` stand-in on 127.0.0.1 still answers. Put the rule in the
agent's instructions too: every test imports `no-network.mjs` and sets a loopback base URL.

## Mock the same API with NSwag and Swagger Codegen

NSwag 14.8.0 writes no mock and no test. Its TypeScript client's constructor is
`constructor(baseUrl?: string, http?: { fetch(url, init): Promise<Response> })`, the signature
the [NSwag wiki](https://github.com/RicoSuter/NSwag/wiki/TypeScriptClientGenerator) shows for the
Fetch template. Pass the in-memory fetch from `fixtures.mjs`, as `offline.mjs` does. NSwag beats
sdkgen when the client should be an Angular service or use jQuery for HTTP. The wiki lists a
template for each, and sdkgen's 23 targets are languages, not frameworks.

Swagger Codegen 3.0.85 has a mock option for its Java client. `config-help -l java` lists
`wiremock`, "Use wiremock to generate endpoint calls to mock on generated tests", as does the
hosted generator's
[Java option list](https://generator3.swagger.io/api/options?language=java&version=V3), and
`--additional-properties wiremock=true` writes a test that starts WireMock on a dynamic port.

```bash
node swagger-stubs.mjs
```

```text output
class is @Ignore: true
stubs with a body: 0
tests that assert: 0 of 3

stub                     answers    document declares
POST /books              200        201
GET /books/{bookId}      200        200, 404
GET /books               200        200
```

The class runs nothing until someone removes `@Ignore`, and then every stub answers 200 with an
empty body.[^2] Treat it as scaffolding for stubs you write. It beats sdkgen for a Java team that
wants WireMock's fault injection in the same harness.

## Check it worked

Run the suite with the guard imported. Eight tests cover the guard both ways, both offline
clients, the routes the in-memory fetch refuses, the Prism behavior below, and the Swagger Codegen
stubs.

```bash
node --experimental-strip-types --test sandbox.test.mjs
```

```text output
1..8
# tests 8
# suites 0
# pass 8
# fail 0
# cancelled 0
# skipped 0
# todo 0
```

Run the same command inside the agent's sandbox before you hand the task over.

## When it goes wrong

The agent's tests pass against fixed data and never reach a page two or a missing record. Prism
in its default static mode answers with the document's example, whatever the page or the id:

```bash
node pitfall.mjs
```

```text output
GET /books?page=1          200 [{"id":"b1","title":"Dune","author":"Frank Herbert","published":1965}]
GET /books?page=2          200 [{"id":"b1","title":"Dune","author":"Frank Herbert","published":1965}]
GET /books/no-such-book    200 {"id":"b1","title":"Dune","author":"Frank Herbert","published":1965}
same, Prefer: code=404     404 {"error":"not found"}
```

A paging loop that stops on an empty page never stops, and a 404 handler never runs. Ask for the
branch with the
[`Prefer` header](https://github.com/stoplightio/prism/blob/master/docs/getting-started/03-cli.md)
in a test of its own, or seed a stateful mock that holds real pages.

The mock starts but the tests cannot reach it under the sandbox. It was started outside the
command the sandbox wraps. Start it from the test, as `prism.mjs` does on a free port.

The guard reports nothing and calls still leave. Something connects outside Node's `net`
module: a native module, or a child process. The OS boundary still stops those, which is
why the guard sits inside a sandbox rather than replacing one.

## When not to do this

Do not treat a passing suite against Prism as evidence that error handling works. A static mock
answers the happy path for every request, so the agent's retry and 404 code may never run.

Do not reach for sdkgen's test feature when the agent is writing the client by hand. It exists
only inside an SDK sdkgen generated, so adopting it means generating that SDK first. Prism, or
WireMock when you need faults, fits a hand-written client with no generator in the loop.

Do not open the sandbox's domain list to the real API so the tests pass. That is the call the
sandbox exists to stop, with the agent holding your credentials.

Do not use NSwag's in-memory fetch as your only mock if the TypeScript client is all you ship
from NSwag. A Prism run catches a fake that has drifted from the document, which the fake
cannot.

## Related how-tos

- [Sandbox an agent's shell and code execution](/howto/sandbox-agent-shell-and-code-execution)

- [Serve your OpenAPI examples as mock responses](/howto/serve-openapi-examples-as-mock-responses)

- [Run an in-memory mock of your API inside SDK tests](/howto/run-an-in-memory-mock-inside-sdk-tests)

- [Run a coding agent headless in CI to keep a client current](/howto/run-a-coding-agent-headless-in-ci)

- [Inject network failures into an AI-written client](/howto/inject-failures-into-an-ai-written-client)

## Last verified

Verified 2026-11-20 against Node 22.23.5, `@voxgig/create-sdkgen` 0.31.9, `@voxgig/sdkgen` 4.44.3,
`@stoplight/prism-cli` 5.16.0, NSwag 14.8.0 and Swagger Codegen 3.0.85. Every output block is what
the command preceding it printed. NSwag and Swagger Codegen were run once and their output is
committed. Codex CLI, Claude Code's sandbox and Docker were not run; their behavior comes from
their documentation. WireMock was not run.

[^1]: Docker lists `none` among its
[network drivers](https://docs.docker.com/engine/network/drivers/none/), beside `bridge` and
`host`, and documents that with it only the loopback device is created. A driver whose job is to
provide no network is filed as a network driver all the same, and chosen with the same
`--network` flag as the others.

[^2]: The `pom.xml` Swagger Codegen writes beside that test asks for
`com.github.tomakehurst:wiremock` 2.27.2. Maven Central's
[index for `org.wiremock:wiremock-standalone`](https://repo1.maven.org/maven2/org/wiremock/wiremock-standalone/maven-metadata.xml)
starts at 3.0.0-beta-11 and lists 4.0.0-beta.44 as its latest release, under a group id the
generated build does not mention.