diff --git a/website/content/cli.mdx b/website/content/cli.mdx index dd4104ef..5da92b3d 100644 --- a/website/content/cli.mdx +++ b/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` diff --git a/website/content/quickstart.mdx b/website/content/quickstart.mdx index 6cedd4a0..1d59fe85 100644 --- a/website/content/quickstart.mdx +++ b/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). + "Local gateway" here means DDK's pure-Python simulator, not Omni/Flex Gateway running in Local Mode — that deployment target isn't supported diff --git a/website/content/simulator.mdx b/website/content/simulator.mdx index e6d76498..5cdd32d1 100644 --- a/website/content/simulator.mdx +++ b/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 +``` + + + 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://:` 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 diff --git a/website/public/cli.md b/website/public/cli.md index a266dbc3..c6fb739f 100644 --- a/website/public/cli.md +++ b/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` diff --git a/website/public/llms-full.txt b/website/public/llms-full.txt index 336ced1f..a83bf680 100644 --- a/website/public/llms-full.txt +++ b/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://:` 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` diff --git a/website/public/quickstart.md b/website/public/quickstart.md index 2beb0d9b..8ee24560 100644 --- a/website/public/quickstart.md +++ b/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)). diff --git a/website/public/simulator.md b/website/public/simulator.md index 85173497..4ca0cfcc 100644 --- a/website/public/simulator.md +++ b/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://:` 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