diff --git a/README.md b/README.md
index 9230297f..fab2832b 100644
--- a/README.md
+++ b/README.md
@@ -140,6 +140,32 @@ You can use the embedded live view to monitor and control the browser. The live
 - The live view is read/write by default. You can set it to read-only by adding `-e ENABLE_READONLY_VIEW=true \` in `docker run`.
 - Replays are currently a work in progress. There is some source code for it throughout the repo.
 
+## Replay Capture
+
+You can use the embedded recording server to capture recordings of the entire screen in our headful images. It allows for one recording at a time and can be enabled with `WITH_KERNEL_IMAGES_API=true`
+
+For example:
+
+```bash
+cd images/chromium-headful
+export IMAGE=kernel-docker
+./build-docker.sh
+WITH_KERNEL_IMAGES_API=true ENABLE_WEBRTC=true ./run-docker.sh
+
+# 1. Start a new recording
+curl http://localhost:10001/recording/start -d {}
+
+# recording in progress - run your agent
+
+# 2. Stop recording
+curl http://localhost:10001/recording/stop -d {}
+
+# 3. Download the recorded file
+curl http://localhost:10001/recording/download --output recording.mp4
+```
+
+Note: the recording file is encoded into a H.264/MPEG-4 AVC video file. [QuickTime has known issues with playback](https://discussions.apple.com/thread/254851789?sortBy=rank) so please make sure to use a compatible media player!
+
 ## Documentation
 
 This repo powers our managed [browser infrastructure](https://docs.onkernel.com).
diff --git a/images/chromium-headful/run-docker.sh b/images/chromium-headful/run-docker.sh
index 1d713f3d..b9962299 100755
--- a/images/chromium-headful/run-docker.sh
+++ b/images/chromium-headful/run-docker.sh
@@ -27,7 +27,7 @@ RUN_ARGS=(
 )
 
 if [[ "${WITH_KERNEL_IMAGES_API:-}" == "true" ]]; then
-  RUN_ARGS+=( -p 444:10001 )
+  RUN_ARGS+=( -p 10001:10001 )
   RUN_ARGS+=( -e WITH_KERNEL_IMAGES_API=true )
 fi
 
diff --git a/server/Makefile b/server/Makefile
index 606ab870..f4fc5d8f 100644
--- a/server/Makefile
+++ b/server/Makefile
@@ -28,7 +28,7 @@ build: | $(BIN_DIR)
 	go build -o $(BIN_DIR)/api ./cmd/api
 
 dev: build $(RECORDING_DIR)
-	OUTPUT_DIR=$(RECORDING_DIR) ./bin/api
+	OUTPUT_DIR=$(RECORDING_DIR) DISPLAY_NUM=$(DISPLAY_NUM) ./bin/api
 
 test:
 	go vet ./...
@@ -38,3 +38,12 @@ clean:
 	@rm -rf $(BIN_DIR)
 	@rm -f openapi-3.0.yaml
 	@echo "Clean complete"
+
+DISPLAY_NUM := $(shell \
+	if [ "$$(uname)" = "Linux" ]; then \
+		echo "1"; \
+	elif [ "$$(uname)" = "Darwin" ]; then \
+		ffmpeg -f avfoundation -list_devices true -i "" 2>&1 | grep "Capture screen" | head -1 | sed 's/.*\[\([0-9]*\)\].*/\1/' 2>/dev/null || echo "2"; \
+	else \
+		echo "0"; \
+	fi)
diff --git a/server/README.md b/server/README.md
index 6da30768..9eef65d7 100644
--- a/server/README.md
+++ b/server/README.md
@@ -7,10 +7,10 @@ A REST API server to start, stop, and download screen recordings.
 ### Required Software
 
 - **Go 1.24.3+** - Programming language runtime
-- **FFmpeg** - Video recording engine
+- **ffmpeg** - Video recording engine
   - macOS: `brew install ffmpeg`
   - Linux: `sudo apt install ffmpeg` or `sudo yum install ffmpeg`
-- **Node.js/pnpm** - For OpenAPI code generation
+- **pnpm** - For OpenAPI code generation
   - `npm install -g pnpm`
 
 ### System Requirements
@@ -33,28 +33,29 @@ The server will start on port 10001 by default and log its configuration.
 
 ```bash
 # 1. Start a new recording
-curl http://localhost:10001/recording/start
+curl http://localhost:10001/recording/start -d {}
 
 # (recording in progress)
 
-# 2. Stop recording and clean up resources
-curl http://localhost:10001/recording/stop
+# 2. Stop recording
+curl http://localhost:10001/recording/stop -d {}
 
 # 3. Download the recorded file
-curl http://localhost:10001/recording/download --output foo.mp4
+curl http://localhost:10001/recording/download --output recording.mp4
 ```
 
 ### ⚙️ Configuration
 
 Configure the server using environment variables:
 
-| Variable      | Default | Description                       |
-| ------------- | ------- | --------------------------------- |
-| `PORT`        | `10001` | HTTP server port                  |
-| `FRAME_RATE`  | `10`    | Default recording framerate (fps) |
-| `DISPLAY_NUM` | `1`     | Display/screen number to capture  |
-| `MAX_SIZE_MB` | `500`   | Default maximum file size (MB)    |
-| `OUTPUT_DIR`  | `.`     | Directory to save recordings      |
+| Variable       | Default   | Description                                 |
+| -------------- | --------- | ------------------------------------------- |
+| `PORT`         | `10001`   | HTTP server port                            |
+| `FRAME_RATE`   | `10`      | Default recording framerate (fps)           |
+| `DISPLAY_NUM`  | `1`       | Display/screen number to capture            |
+| `MAX_SIZE_MB`  | `500`     | Default maximum file size (MB)              |
+| `OUTPUT_DIR`   | `.`       | Directory to save recordings                |
+| `FFMPEG_PATH`  | `ffmpeg`  | Path to the ffmpeg binary                   |
 
 #### Example Configuration