How-to › Use AI to do the integration

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.

Audience
Platform team
Level
intermediate
Topic
Write an integration with a coding agent
Languages
TypeScript
Verified

The agent writes a Bookshelf client, runs its tests, and the tests call api.example.com with the key from your shell. A create test leaves a record in production. When you cut the network, every test fails on a connection error, because nothing local answers the calls the agent wrote.

What you get

You will end up with an agent whose commands cannot leave the machine and tests that start their own mock. A guard fails any test that opens a connection to a real host. This is for you if you let an agent run tests against code that talks to a paid or shared API.

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 gives a container a loopback device and nothing else.1 Codex documents that its default workspace-write mode keeps network access off until network_access = true appears under [sandbox_workspace_write]. Claude Code’s Bash sandbox routes commands through a proxy that checks network.allowedDomains, which starts empty.

Approaches compared

ApproachWhen it fitsWhat it costs youWhen to pick something else
NSwag client with an in-memory fetchThe client is NSwag’s Fetch template, and tests can pass the constructor an object with fetchA fake transport you write and keep matching the document, because NSwag generates no mockYou want the mock to follow the document without code
Prism mockAny client in any language, and the document carries good examplesOne fixed example per response, so pages and missing ids all look alikeThe tests must reach pagination or error branches unprompted
sdkgen test featureThe client is an sdkgen SDK, and tests should run with no server or portOnly exists inside a generated SDK, so the SDK must exist before the agent’s testsThe agent is writing the client itself
Swagger Codegen WireMock testsA Java client, and you want a test class that starts WireMock already writtenStubs that answer 200 with no body, in a class marked @IgnoreThe client is TypeScript, or the stubs need real bodies
WireMock stubs and faultsYou need scripted answers per request, delays, and connection resetsA JVM or container in the test setup, and every stub authored by handThe 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/:

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:

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:

// 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.

node --experimental-strip-types offline.mjs
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:

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 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, and --additional-properties wiremock=true writes a test that starts WireMock on a dynamic port.

node swagger-stubs.mjs
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.

node --experimental-strip-types --test sandbox.test.mjs
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:

node pitfall.mjs
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 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.

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.

Footnotes

  1. Docker lists none among its network drivers, 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. ↩︎ Back to text

  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 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. ↩︎ Back to text

Read this page as markdown · All how-to guides

Generate the client instead of writing it#

Retries, timeouts, pagination and auth are the same problems in every client. Voxgig generates them from your OpenAPI description, in 23 languages, from one model.

Listen to Fireside, the Voxgig podcast

Since 2018, Richard Rodger has talked with developer advocates, event organizers, and the people who build developer-facing companies about the specifics of the work.