docs: document local simulator port/host configuration (#688)

website/content/cli.mdx

@@ -155,6 +155,11 @@ donkey mock --port 8080 --host 127.0.0.1 \
 | `--host` | `127.0.0.1` | Host/interface to bind. |
 | `--scenario` | none | Fault-injection rule, repeatable. See [Scenario scripting](/simulator#scenario-scripting). |
 
+The port isn't read from an environment variable or `.donkey-kit.toml`; these
+flags (or the `serve()` keyword arguments) are the only way to change it. See
+[Choosing a port or host](/simulator#choosing-a-port-or-host) for the
+programmatic entry point and the `0.0.0.0` caveat.
+
 An invalid `--scenario` exits with code `2`.
 
 ### `donkey test`

website/content/quickstart.mdx

@@ -56,6 +56,9 @@ The simulator listens on `127.0.0.1:8080` and replays real gateway responses,
 including every refusal shape. It enforces no policy and ignores
 credentials, and every response carries `x-donkey-simulator: true`.
 
+Port `8080` already taken? Run `donkey mock --port 9000` — see
+[Choosing a port or host](/simulator#choosing-a-port-or-host).
+
 <Callout type="info">
   "Local gateway" here means DDK's pure-Python simulator, not Omni/Flex
   Gateway running in Local Mode — that deployment target isn't supported

website/content/simulator.mdx

@@ -50,6 +50,55 @@ Because each body is the *same fixture* the SDK's error classifier is tested
 against, a sentinel request surfaces in your agent as the typed exception — a
 [`PIIDetected`](/errors), not a raw `403`.
 
+## Choosing a port or host
+
+`donkey mock` binds `127.0.0.1:8080` by default. Two flags move it:
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--port` | `8080` | TCP port to bind. Pass another value if `8080` is in use. |
+| `--host` | `127.0.0.1` | Interface to bind. `0.0.0.0` exposes it beyond localhost. |
+
+```bash
+donkey mock --port 9000 --host 0.0.0.0
+```
+
+<Callout type="warning">
+  Binding `0.0.0.0` makes the simulator reachable from other machines on your
+  network. It is a fixture replay that enforces no policy and ignores
+  credentials, so only expose it on a network you trust.
+</Callout>
+
+Whatever you choose, point your client at the same address: set
+`DONKEY_LLM_PROXY_URL=http://<host>:<port>` to match (for the example above,
+`http://127.0.0.1:9000`). The simulator's port is **not** read from an
+environment variable or `.donkey-kit.toml` — the `--port`/`--host` flags (or the
+`serve()` keyword arguments below) are the only way to change it.
+
+<Callout type="info">
+  If you run the simulator's ASGI app under `uvicorn` yourself instead of
+  through `donkey mock`, remember uvicorn's own default port is `8000`, not
+  `8080`. Using `donkey mock` (or `serve()`) gives you the documented `8080`
+  default.
+</Callout>
+
+### Running the simulator from Python
+
+`donkey mock` is a thin wrapper over `serve()`. To boot the simulator from your
+own code, call it directly (the `[local]` extra must be installed):
+
+```python
+from donkey_kit.simulator import serve
+
+serve(host="127.0.0.1", port=9000)
+```
+
+`serve(*, host="127.0.0.1", port=8080, config=None)` is keyword-only and blocks
+until the process is stopped. Pass a `SimulatorConfig` (also importable from
+`donkey_kit.simulator`) as `config=` to script the same fault-injection
+scenarios the `--scenario` flag builds. If the `[local]` extra is missing,
+`serve()` raises `ImportError`.
+
 ## Budget windows on the happy path
 
 Happy-path `200` responses carry a synthesised `x-llm-proxy-ratelimit` budget

website/public/cli.md

@@ -146,6 +146,11 @@ donkey mock --port 8080 --host 127.0.0.1 \
 | `--host` | `127.0.0.1` | Host/interface to bind. |
 | `--scenario` | none | Fault-injection rule, repeatable. See [Scenario scripting](https://donkey-development-kit.github.io/donkey-development-kit/simulator.md#scenario-scripting). |
 
+The port isn't read from an environment variable or `.donkey-kit.toml`; these
+flags (or the `serve()` keyword arguments) are the only way to change it. See
+[Choosing a port or host](https://donkey-development-kit.github.io/donkey-development-kit/simulator.md#choosing-a-port-or-host) for the
+programmatic entry point and the `0.0.0.0` caveat.
+
 An invalid `--scenario` exits with code `2`.
 
 ### `donkey test`

website/public/llms-full.txt

@@ -315,6 +315,9 @@ The simulator listens on `127.0.0.1:8080` and replays real gateway responses,
 including every refusal shape. It enforces no policy and ignores
 credentials, and every response carries `x-donkey-simulator: true`.
 
+Port `8080` already taken? Run `donkey mock --port 9000` — see
+[Choosing a port or host](https://donkey-development-kit.github.io/donkey-development-kit/simulator.md#choosing-a-port-or-host).
+
   "Local gateway" here means DDK's pure-Python simulator, not Omni/Flex
   Gateway running in Local Mode — that deployment target isn't supported
   (see the [unsupported boundary](https://donkey-development-kit.github.io/donkey-development-kit/reference/unsupported-boundary.md)).
@@ -3100,6 +3103,51 @@ Because each body is the *same fixture* the SDK's error classifier is tested
 against, a sentinel request surfaces in your agent as the typed exception — a
 [`PIIDetected`](https://donkey-development-kit.github.io/donkey-development-kit/errors.md), not a raw `403`.
 
+## Choosing a port or host
+
+`donkey mock` binds `127.0.0.1:8080` by default. Two flags move it:
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--port` | `8080` | TCP port to bind. Pass another value if `8080` is in use. |
+| `--host` | `127.0.0.1` | Interface to bind. `0.0.0.0` exposes it beyond localhost. |
+
+```bash
+donkey mock --port 9000 --host 0.0.0.0
+```
+
+  Binding `0.0.0.0` makes the simulator reachable from other machines on your
+  network. It is a fixture replay that enforces no policy and ignores
+  credentials, so only expose it on a network you trust.
+
+Whatever you choose, point your client at the same address: set
+`DONKEY_LLM_PROXY_URL=http://<host>:<port>` to match (for the example above,
+`http://127.0.0.1:9000`). The simulator's port is **not** read from an
+environment variable or `.donkey-kit.toml` — the `--port`/`--host` flags (or the
+`serve()` keyword arguments below) are the only way to change it.
+
+  If you run the simulator's ASGI app under `uvicorn` yourself instead of
+  through `donkey mock`, remember uvicorn's own default port is `8000`, not
+  `8080`. Using `donkey mock` (or `serve()`) gives you the documented `8080`
+  default.
+
+### Running the simulator from Python
+
+`donkey mock` is a thin wrapper over `serve()`. To boot the simulator from your
+own code, call it directly (the `[local]` extra must be installed):
+
+```python
+from donkey_kit.simulator import serve
+
+serve(host="127.0.0.1", port=9000)
+```
+
+`serve(*, host="127.0.0.1", port=8080, config=None)` is keyword-only and blocks
+until the process is stopped. Pass a `SimulatorConfig` (also importable from
+`donkey_kit.simulator`) as `config=` to script the same fault-injection
+scenarios the `--scenario` flag builds. If the `[local]` extra is missing,
+`serve()` raises `ImportError`.
+
 ## Budget windows on the happy path
 
 Happy-path `200` responses carry a synthesised `x-llm-proxy-ratelimit` budget
@@ -3506,6 +3554,11 @@ donkey mock --port 8080 --host 127.0.0.1 \
 | `--host` | `127.0.0.1` | Host/interface to bind. |
 | `--scenario` | none | Fault-injection rule, repeatable. See [Scenario scripting](https://donkey-development-kit.github.io/donkey-development-kit/simulator.md#scenario-scripting). |
 
+The port isn't read from an environment variable or `.donkey-kit.toml`; these
+flags (or the `serve()` keyword arguments) are the only way to change it. See
+[Choosing a port or host](https://donkey-development-kit.github.io/donkey-development-kit/simulator.md#choosing-a-port-or-host) for the
+programmatic entry point and the `0.0.0.0` caveat.
+
 An invalid `--scenario` exits with code `2`.
 
 ### `donkey test`

website/public/quickstart.md

@@ -47,6 +47,9 @@ The simulator listens on `127.0.0.1:8080` and replays real gateway responses,
 including every refusal shape. It enforces no policy and ignores
 credentials, and every response carries `x-donkey-simulator: true`.
 
+Port `8080` already taken? Run `donkey mock --port 9000` — see
+[Choosing a port or host](https://donkey-development-kit.github.io/donkey-development-kit/simulator.md#choosing-a-port-or-host).
+
   "Local gateway" here means DDK's pure-Python simulator, not Omni/Flex
   Gateway running in Local Mode — that deployment target isn't supported
   (see the [unsupported boundary](https://donkey-development-kit.github.io/donkey-development-kit/reference/unsupported-boundary.md)).

website/public/simulator.md

@@ -43,6 +43,51 @@ Because each body is the *same fixture* the SDK's error classifier is tested
 against, a sentinel request surfaces in your agent as the typed exception — a
 [`PIIDetected`](https://donkey-development-kit.github.io/donkey-development-kit/errors.md), not a raw `403`.
 
+## Choosing a port or host
+
+`donkey mock` binds `127.0.0.1:8080` by default. Two flags move it:
+
+| Flag | Default | Meaning |
+|---|---|---|
+| `--port` | `8080` | TCP port to bind. Pass another value if `8080` is in use. |
+| `--host` | `127.0.0.1` | Interface to bind. `0.0.0.0` exposes it beyond localhost. |
+
+```bash
+donkey mock --port 9000 --host 0.0.0.0
+```
+
+  Binding `0.0.0.0` makes the simulator reachable from other machines on your
+  network. It is a fixture replay that enforces no policy and ignores
+  credentials, so only expose it on a network you trust.
+
+Whatever you choose, point your client at the same address: set
+`DONKEY_LLM_PROXY_URL=http://<host>:<port>` to match (for the example above,
+`http://127.0.0.1:9000`). The simulator's port is **not** read from an
+environment variable or `.donkey-kit.toml` — the `--port`/`--host` flags (or the
+`serve()` keyword arguments below) are the only way to change it.
+
+  If you run the simulator's ASGI app under `uvicorn` yourself instead of
+  through `donkey mock`, remember uvicorn's own default port is `8000`, not
+  `8080`. Using `donkey mock` (or `serve()`) gives you the documented `8080`
+  default.
+
+### Running the simulator from Python
+
+`donkey mock` is a thin wrapper over `serve()`. To boot the simulator from your
+own code, call it directly (the `[local]` extra must be installed):
+
+```python
+from donkey_kit.simulator import serve
+
+serve(host="127.0.0.1", port=9000)
+```
+
+`serve(*, host="127.0.0.1", port=8080, config=None)` is keyword-only and blocks
+until the process is stopped. Pass a `SimulatorConfig` (also importable from
+`donkey_kit.simulator`) as `config=` to script the same fault-injection
+scenarios the `--scenario` flag builds. If the `[local]` extra is missing,
+`serve()` raises `ImportError`.
+
 ## Budget windows on the happy path
 
 Happy-path `200` responses carry a synthesised `x-llm-proxy-ratelimit` budget