OperationsDynoSim

Simulate a Local Deployment with Mocker

Run a GPU-free frontend and simulated worker from the command line

View as Markdown

Mocker is a simulated Dynamo backend. Use it locally to test frontend discovery, routing, KV events, and worker behavior without loading a model or using GPUs. This is a live simulation: you start a frontend and workers, then send HTTP requests through the Dynamo runtime.

For a faster offline replay that drives simulated engines directly without a frontend, worker registration, or runtime services, see Run a DynoSim Simulation.

This tutorial uses file-based discovery so that the frontend and worker can run without etcd or NATS. For Kubernetes, see Simulate a Kubernetes Deployment. For every available flag, see the Mocker CLI Reference.

Prerequisites

Install Dynamo by following Install Dynamo. Verify that the local environment can import the frontend and Mocker modules:

$python -m dynamo.frontend --help >/dev/null
$python -m dynamo.mocker --help >/dev/null
1

Start the frontend

In the first terminal, start the OpenAI-compatible frontend:

$python -m dynamo.frontend --http-port 8000 --discovery-backend file

File-based discovery keeps this tutorial on one machine and selects the local event path.

2

Start a Mocker worker

In a second terminal, start one simulated worker with the same discovery backend:

$python -m dynamo.mocker \
>  --model-path Qwen/Qwen3-0.6B \
>  --discovery-backend file

Wait for the worker to register with the frontend.

3

Send a request

In a third terminal, send a request to the frontend:

$curl localhost:8000/v1/chat/completions \
>  -H 'Content-Type: application/json' \
>  -d '{
>    "model": "Qwen/Qwen3-0.6B",
>    "messages": [{"role": "user", "content": "Hello!"}],
>    "max_tokens": 32
>  }'

A successful response confirms that local discovery and request routing are working.

4

Run multiple simulated workers

Stop the Mocker process and restart it with four workers:

$python -m dynamo.mocker \
>  --model-path Qwen/Qwen3-0.6B \
>  --discovery-backend file \
>  --num-workers 4

Send several requests and compare the frontend and worker logs. For local scale tests, prefer --num-workers over launching many separate Mocker processes because the workers share one runtime and thread pool.

5

Simulate disaggregated serving

Stop the aggregated Mocker process. Start a prefill worker:

$python -m dynamo.mocker \
>  --model-path Qwen/Qwen3-0.6B \
>  --discovery-backend file \
>  --disaggregation-mode prefill \
>  --bootstrap-ports 50100

In another terminal, start a decode worker:

$python -m dynamo.mocker \
>  --model-path Qwen/Qwen3-0.6B \
>  --discovery-backend file \
>  --disaggregation-mode decode

Send another request and inspect both worker logs to confirm that the request moved through prefill and decode.

6

Tune the simulation

Restart the worker with settings that match the experiment you want to run. For example:

$python -m dynamo.mocker \
>  --model-path Qwen/Qwen3-0.6B \
>  --discovery-backend file \
>  --num-gpu-blocks-override 8192 \
>  --block-size 64 \
>  --max-num-seqs 256 \
>  --speedup-ratio 10.0

Use the Mocker CLI Reference for scheduling, KV-cache, timing, AIC, and transport settings. Use Run a DynoSim Simulation when you want to replay a complete trace without managing live frontend and worker processes.