diff --git a/gitea-runner.md b/gitea-runner.md
new file mode 100644
index 0000000..787228b
--- /dev/null
+++ b/gitea-runner.md
@@ -0,0 +1,39 @@
+# Gitea Act Runner — Configuring Worker Capacity (TrueNAS)
+
+## Problem
+
+The default Gitea Act Runner (`gitea/act_runner`) runs with `capacity: 1`, meaning only one job at a time. Setting `GITEA_RUNNER_RUNNER__CAPACITY` env var or placing a `config.yaml` in the app data directory does **not** work on its own.
+
+## Root Cause
+
+The runner's entrypoint (`run.sh`) only passes `--config` to `act_runner daemon` when the `CONFIG_FILE` environment variable is explicitly set. Without it, the runner ignores any config file, even if it exists at `/data/config.yaml`.
+
+## Solution
+
+1. **Create the config file** in the app data directory (mounted as `/data` inside the container):
+
+   ```yaml
+   # /mnt/system_pool/app_data/gitea-runner/config.yaml
+   runner:
+     capacity: 6
+   ```
+
+2. **Set the `CONFIG_FILE` environment variable** in TrueNAS:
+
+   Go to **TrueNAS UI → Apps → Gitea Act Runner → Edit → Extra Environment Variables** and add:
+
+   ```
+   CONFIG_FILE=/data/config.yaml
+   ```
+
+3. **Restart the app.**
+
+## Verification
+
+Check the runner logs after restart — concurrent jobs should now show `maxParallel` matching your capacity, and multiple tasks should run simultaneously.
+
+## Notes
+
+- `capacity` controls how many **separate jobs** the runner handles concurrently
+- `maxParallel` in logs refers to parallelism within a single job's matrix strategy, not the runner capacity
+- To generate a full default config for reference: `act_runner generate-config`