# Local Runner

> Run tests from a lightweight desktop agent on your own machine so you can reach private or internal endpoints the central engine can't, then report results back to the platform.

Source: https://totalshiftleft.ai/help-center/product-documentation/local-runner

## Overview

The **Local Runner** — surfaced in the app as the **Shift-Left Agent** — is a small desktop agent that runs API tests on your own machine and reports results back to the platform. Use it when tests must reach endpoints the central engine can't: private networks, internal services, or `localhost`. It runs a local HTTP server on **`127.0.0.1:5004`** and is selected per run as the **Shift-Left Agent** execution mode. Explore the related capability at [shift-left agent](/features/test-execution/shift-left-agent).

**Availability:** all editions.

## Before you begin

- Any signed-in user can check status, install, start, stop, and select the runner — there's no separate edition gate. Test execution itself still respects your license status.
- The runner listens only on the loopback address `127.0.0.1:5004`, so it's reachable from your machine, not the network.
- Keep it running while local executions are in progress; if it's down, local runs can't complete.

## Step 1 — Find the runner controls

The runner status and controls appear inline on the **Execution Mode** selector wherever you launch a run (for example in the Test Workbench and when starting a workflow). You'll see two cards:

- **Shift-Left Engine** — runs tests on the server; labeled **Always Available**.
- **Shift-Left Agent** — the Local Runner. Its card shows a live status line and small action buttons.

The status line reads one of:

- **Available** (green check) — the runner is up; the card also shows its **Version**.
- **Not Running** (warning icon) — the runner isn't responding on `127.0.0.1:5004`.
- **Checking…** — a status check is in progress.

## Step 2 — Check, start, and stop the runner

On the **Shift-Left Agent** card, the small icon buttons do the following:

| Control | What it does |
|---------|--------------|
| **Start (play icon)** | Shown when the runner is **Not Running**. Launches the agent; it comes up on `127.0.0.1:5004`. If it's already running, the app reports it's already up. |
| **Stop (stop icon)** | Shown when the runner is **Available**. Shuts the agent down (gracefully first, then by stopping the process). |
| **Refresh status (circular-arrow icon)** | Re-checks whether the runner is responding and updates the status line. |
| **Open status (open-in-new-tab icon)** | Opens `http://127.0.0.1:5004/status` in a new tab so you can see the runner's raw health JSON. |

## Step 3 — Install the runner

If the runner has never been set up on this machine, install it before starting:

- From the app, the **Install** action installs the agent's dependencies and registers it globally on your machine.
- You can also install it outside the app using its bundled installer/executable (Windows, macOS Intel, and macOS Apple Silicon builds are provided).

Once installed, use **Start** (Step 2) to bring it up.

## Step 4 — Run tests on the Local Runner

1. On the **Execution Mode** selector, choose the **Shift-Left Agent** card (its description reads *"Execute tests locally. Best for development and private APIs."*).
2. Confirm the status line shows **Available** — if not, click **Start** and then **Refresh status**.
3. Launch your test or [workflow](/help-center/product-documentation/creating-and-running-workflows) as usual. Execution runs on your machine and results report back to the platform.
4. Keep the runner running until the execution finishes.

For CI/CD and scheduled runs, use **Shift-Left Engine** instead; the Local Runner is for reaching endpoints only your machine can see.

## Troubleshooting / Notes

- **Status stays "Not Running" after Start** — give it a moment and click **Refresh status**; the app waits for the agent to come up on port 5004 before confirming. If it still fails, the `local-runner` directory or its entry point may be missing on the host — reinstall (Step 3).
- **Port 5004 in use** — another process may hold the port; stop it, or stop and restart the runner.
- **Local runs blocked** — check the runner's license status via **Open status**; an expired or invalid backend license can block execution.
- The runner is loopback-only (`127.0.0.1:5004`) and can't be reached from other machines by design.

## Related articles

- [Execution mode](/help-center/product-documentation/execution-mode)
- [Creating and running workflows](/help-center/product-documentation/creating-and-running-workflows)
- [Test execution](/help-center/product-documentation/test-execution)
- [Proxy Settings](/help-center/product-documentation/proxy-settings)