This guide shows how to install Codex Autorunner on WSL2 Ubuntu and use it with Codex CLI. Codex Autorunner (CAR) gives coding agents a shared control panel for repositories, tasks, and long-running work.

Instead of opening a new terminal chat for every task, you can organize the work as tickets and monitor it from one web hub. The commands were checked with CAR 2.2.3 on WSL2 Ubuntu in Windows. They also work on a regular Ubuntu installation.

What Is Codex Autorunner?

CAR is a meta-harness, which means it coordinates coding agents rather than replacing them. You bring an agent such as Codex, Hermes, OMP, or OpenCode. CAR supplies the queue, shared context, browser interface, and run history around that agent.

The open-source project is published by Git-on-my-level on GitHub under the MIT License. At the time of writing, version 2.2.3 is the latest stable package on PyPI and requires Python 3.10 or newer.

Why Use CAR Instead of Codex CLI Alone?

Codex CLI is excellent for working directly in one repository from a terminal. Run codex, describe the change, review the result, and continue the conversation. For a small fix or a focused coding session, that is usually the shortest path.

CAR becomes useful when the work lasts longer, contains several steps, or spans multiple repositories. It keeps the task state on disk, so you can close the browser, return later, and inspect what happened.

Need	Codex CLI alone	CAR with Codex
Quick task in one repository	Simple and direct	More setup than you may need
Several planned tasks	You manage prompts and progress	Tickets keep the order and status
Multiple repositories	Separate terminal sessions	One hub lists each repository
Pause and resume	Resume a saved session	Resume the managed thread or ticket flow
Shared project context	Instructions and chat history	Contextspace files stored with the repository
Monitoring	Terminal output	Web UI, logs, run status, and inbox

In daily work, CAR reduces the mental bookkeeping around large changes. I can describe the target once, split it into clear tickets, and check the hub when a decision is needed. I still use Codex CLI directly for small, interactive fixes.

Prerequisites

• WSL2 Ubuntu. If you haven’t installed it yet, follow How to Install Ubuntu 22.04 in WSL2 on Windows.
• Python 3.10 or newer. The Python version management guide for WSL Ubuntu can help if your version is older.
• Git. Use the latest Git installation guide for Ubuntu if the command is missing.
• One supported coding agent. This tutorial uses Codex CLI, already installed and signed in.
• A folder for the CAR hub. A new empty folder is easiest for the first setup.

Install Codex Autorunner on WSL2 Ubuntu Step by Step

Step 1: Check Python, Git, and Codex

Open your WSL2 Ubuntu terminal and check the three required commands:

python3 --version
git --version
codex --version

Python must report version 3.10 or newer. Each command should print a version instead of command not found. Also run codex once and confirm that you can start a normal session before placing CAR around it.

Step 2: Install pipx

pipx installs Python command-line applications in isolated environments. This avoids mixing CAR’s dependencies with your application packages.

sudo apt update
sudo apt install -y pipx
pipx ensurepath
source ~/.profile

If car is not found later, close the WSL terminal and open it again. That reloads the PATH change made by pipx ensurepath.

Step 3: Install Codex Autorunner

Install the stable PyPI package, then print its version:

pipx install codex-autorunner
car --version

If CAR is already installed, use this instead:

pipx upgrade codex-autorunner
car --version

Step 4: Create and Initialize the Hub

A hub is the top-level folder that holds CAR’s configuration and its managed repositories. Think of it as the control room for your coding projects.

mkdir -p ~/car-hub
cd ~/car-hub
car init --mode hub

CAR creates .codex-autorunner/config.yml, a hub manifest, and local command shims. Use hub mode for normal work. Repo mode is mainly useful when developing CAR itself or when you intentionally want one repository to act as the whole CAR workspace.

Step 5: Run the Health Check

The doctor command checks the hub configuration and available agent adapters:

cd ~/car-hub
car doctor

Fix any failed requirement before continuing. For a machine-readable report, add --json. You can also inspect the CLI, Python, and server versions with:

car doctor versions

Step 6: Start the Web Hub

Start CAR on a fixed local address and port. Binding to 127.0.0.1 keeps the service available only on your computer.

cd ~/car-hub
car serve --host 127.0.0.1 --port 8765

Leave that terminal running. Open http://localhost:8765 in your Windows browser. WSL2 forwards the local port to Windows in a standard setup.

Do not bind CAR to 0.0.0.0 just to make the page reachable. That can expose the hub to your network. Use CAR’s documented authentication and a trusted private network if you later need remote access.

Step 7: Add Your First Repository

You can add a repository from the Web UI. For a clean practice project, the CLI can create and register one inside the hub:

car hub create sample-app --path ~/car-hub
car hub repos --path ~/car-hub

To clone an existing public or private Git repository, use its URL:

car hub clone --git-url https://github.com/example/sample-app.git --path ~/car-hub

Replace the example URL with your real repository. CAR places the clone under the hub’s configured repository root and registers it in the manifest. Keeping the repository inside the hub also prevents the path-scope error covered later in this guide.

Step 8: Use PMA for a Small Planning Session

PMA means Project Manager Agent. It is CAR’s hub-level coordinator. Open the PMA area in the Web UI, select sample-app, and start with a small request such as:

Inspect this repository and propose a three-ticket plan for adding a small health-check endpoint. Do not modify files yet.

This first prompt is intentionally read-only. It confirms that the repository, agent, and managed chat scope are connected before you allow implementation.

Step 9: Understand Tickets and Contextspace

A ticket is a Markdown task file with status information and acceptance criteria. CAR reads tickets in filename order and sends the next incomplete task to an agent. In plain language, tickets are a checklist that the worker can actually execute.

• .codex-autorunner/tickets/: ordered work items such as TICKET-001.md.
• .codex-autorunner/contextspace/active_context.md: current working notes.
• .codex-autorunner/contextspace/spec.md: requirements and expected behavior.
• .codex-autorunner/contextspace/decisions.md: decisions that should survive future sessions.

These files are CAR’s memory and control plane. Because they live on disk, you can open them in an editor, review changes with Git, and recover useful context even when a process stops.

Step 10: Start and Monitor a Ticket Flow

Create tickets through the Web UI or ask PMA to turn an approved plan into tickets. Once the queue is ready, start the flow for the repository:

car ticket-flow start --repo ~/car-hub/sample-app --path ~/car-hub

Check its health from another WSL terminal:

car ticket-flow status --repo ~/car-hub/sample-app --path ~/car-hub
car log --repo ~/car-hub/sample-app --path ~/car-hub --tail 100

If the repository has no tickets yet, car ticket-flow bootstrap can seed an initial ticket and start a run. For real work, I prefer reviewing the ticket text and acceptance criteria before starting the flow.

A Practical Daily Workflow

1. Open the hub and choose the repository.
2. Ask PMA to clarify the goal and prepare a short plan.
3. Review the plan, risks, and acceptance criteria.
4. Convert the approved plan into ordered tickets.
5. Start the ticket flow and let the agent work.
6. Check the inbox, run status, tests, and Git diff before accepting the result.

CAR makes long tasks easier to follow, but it does not remove the need for review. Keep tickets small enough to verify, require tests where appropriate, and inspect changes before committing or deploying them.

Fix “Resolved resource path is invalid”

This error usually means CAR resolved a file or repository outside the hub’s allowed workspace. CAR distinguishes four locations: the hub root, repository root, worktree root, and the agent’s current working directory. A prompt can fail when those paths point to unrelated folders.

Confirm the hub root

car hub endpoint --path ~/car-hub
car hub repos --path ~/car-hub
car hub scan --path ~/car-hub

Confirm that the repository shown by CAR is inside ~/car-hub/. With the default command in this guide, its path is ~/car-hub/sample-app. If it is elsewhere, clone or create it through the hub instead of manually pointing a repository-scoped chat at an unrelated folder.

Use CAR’s path-aware documentation

car docs search path --path ~/car-hub
car docs show car/path-model --path ~/car-hub
car docs show car/troubleshooting --path ~/car-hub

If a prompt refers to a hub document while the agent is running inside a repository, resolve the document through CAR instead of guessing a relative path:

car docs path pma/about --path ~/car-hub

Restart from the correct directory

cd ~/car-hub
car doctor
car serve --host 127.0.0.1 --port 8765

Then create a new repository-scoped chat and test it with a read-only prompt. Do not paste an internal absolute path from another project into a public ticket or reusable setup prompt.

Other Common CAR Problems

car: command not found

Reload your shell after installing with pipx:

pipx ensurepath
source ~/.profile
command -v car
car --version

Agent not found

Test the agent outside CAR first. For this tutorial, both commands must work:

codex --version
codex

Web UI does not load

Keep the car serve terminal open and verify the endpoint:

car hub endpoint --path ~/car-hub

If port 8765 is already used, stop the old process or choose another port, such as 8766, in both the command and browser address.

A ticket flow says another run is active

Inspect the active run before starting another one:

car ticket-flow status --json --repo ~/car-hub/sample-app --path ~/car-hub

Resume or stop a healthy run. Use --force-new only after confirming that the old worker is absent or its metadata is stale. Starting overlapping workers can make the repository state harder to understand.

Useful CAR Commands

Command	Purpose
car doctor	Check hub, repository, and agent health
car serve	Start the hub API and Web UI
car hub repos	List registered repositories
car hub scan	Discover repositories and worktrees on disk
car status	Show the current autorunner state
car log --tail 100	Read recent autorunner logs
car ticket-flow status	Inspect a ticket-flow run
car docs search path	Find CAR’s installed operational documentation

Does CAR Make Daily Coding Easier?

Yes, when the task has enough moving parts to justify a control layer. CAR is most helpful for multi-step features, migrations, long test cycles, and work spread across repositories. Tickets make progress visible, while contextspace files stop key decisions from disappearing inside one chat transcript.

It is not automatically better for every prompt. For a quick bug fix, I still open Codex CLI directly. For work that I need to plan, pause, resume, and audit, I use CAR as the coordinator and Codex as the coding agent.

Conclusion

You now have Codex Autorunner installed on WSL2 Ubuntu, a local hub running in the browser, and a repository ready for PMA and ticket flows. The key setup rule is simple: keep each managed repository within the hub’s known workspace and pass explicit --path and --repo values when a command could be ambiguous.

If you want another agent option for CAR, read How to Install Hermes Agent and Enable the Web UI Chat on WSL2 Ubuntu. You can also explore how custom Claude Code plugins organize reusable automation.