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.

Codex is the main agent in this tutorial. I also include an optional OpenCode Go setup for readers who want to use their Go subscription inside CAR.

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.
• Optional OpenCode Go subscription. You need the API key from your OpenCode Zen account if you want to follow the OpenCode Go section.
• 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.

Use One CAR Hub for Two Separate Projects

One CAR hub can manage more than one repository. For example, you can add Project 1 and Project 2 under the same hub, then open both from one Web Hub port such as 8765. The projects remain separate on disk and in Git. Their tickets, context files, and run state stay with the selected repository.

cd ~/car-hub
car hub create project-1 --repo-path project-1
car hub create project-2 --repo-path project-2
car hub repos

The two projects now appear as separate entries in the same repository list. Start the hub once, then open the shared address in your browser:

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

Use the repository selector or a repository-specific URL to work on the correct project. A ticket created for Project 1 does not become a ticket for Project 2, even though both use the same Web Hub port. When adding an existing repository, keep it inside the hub’s configured repository root and register it with its own repository ID.

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

Optional: Connect OpenCode Go Before Starting CAR

Skip this section if you only plan to use Codex. OpenCode Go is a separate provider, so a Go subscription does not automatically apply to Codex, Amazon Bedrock, or another provider shown in CAR’s model list.

Install OpenCode on WSL2 Ubuntu

Run the installer from the official OpenCode installation guide, then check that the command is available:

curl -fsSL https://opencode.ai/install | bash
opencode --version

If the command is still missing, close the WSL terminal and open a new one so your shell reloads its PATH.

Connect your OpenCode Go account

Sign in to OpenCode Zen, open your Go subscription, and copy its API key. Start the OpenCode terminal interface:

opencode

Enter /connect, select OpenCode Go, and paste the API key when prompted. Do not place the key in a Git repository, screenshot, shell command, or CAR ticket. OpenCode stores the credential for the current Linux user.

The official OpenCode Go documentation lists the current subscription setup and available models. The model list can change, so check it locally instead of copying an old model name from another tutorial.

Verify the Go provider and run a small test

Leave OpenCode, then confirm that the Go credential and model catalog are available:

opencode auth list
opencode models opencode-go

The credential list should include OpenCode Go. Every Go model uses the opencode-go/ provider prefix. Send a short request before returning to CAR:

opencode run -m opencode-go/mimo-v2.5 "Reply with GO_OK only."

This request uses a small amount of your Go allowance. A GO_OK reply confirms that the connection works from the command line. If that model is no longer listed, choose another entry returned by opencode models opencode-go.

Start CAR as the same WSL user who connected OpenCode Go. A CAR process owned by another user or running in a container will not automatically see this credential. If CAR was already running when you connected Go, restart the Web Hub before checking its model picker.

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 and select sample-app. For the Codex path, keep Codex as the agent and use its configured model.

To use the Go subscription, create a new chat with these settings:

Mode: PMA
Scope: REPO sample-app
Agent: OpenCode
Model: opencode-go/mimo-v2.5

You can replace mimo-v2.5 with another model returned by opencode models opencode-go. Check the full provider prefix before sending the first message.

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 you selected outside CAR first. Use the Codex commands for a Codex setup, or the OpenCode commands for an OpenCode Go setup:

codex --version
codex
opencode --version
opencode auth list

For an OpenCode Go setup, the credential list must contain OpenCode Go. Run opencode models opencode-go to confirm that the Go catalog is available before starting CAR again.

Runtime thread failed with an OpenCode model

Check the model label on the failed chat. A model beginning with opencode-go/ uses the Go subscription. A model beginning with amazon-bedrock/ uses your AWS credentials and AWS billing instead. Connecting Go does not redirect Bedrock requests through the subscription.

Create a new PMA chat, select OpenCode as the agent, and choose a model listed by opencode models opencode-go. Test it with a short reply before assigning a ticket or long-running task.

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.

Optional: Use an AI Prompt to Set Up CAR

If the CAR setup feels confusing, you can ask Claude Code, Codex, or another coding assistant to guide you through it. Paste the prompt below into a new chat. It tells the assistant to inspect your environment first, keep two projects separate, and ask before making changes.

I want to set up Codex Autorunner on WSL2 Ubuntu.

Please guide me one step at a time and explain each command before I run it.

My requirements:
- Use one CAR hub for two separate repositories named Project 1 and Project 2.
- Keep each repository's Git history, tickets, context files, and run state separate.
- Serve both projects from the same CAR Web Hub on 127.0.0.1 port 8765.
- Use generic project paths such as ~/projects/project-1 and ~/projects/project-2.

First, inspect and report:
1. My operating system and Ubuntu version.
2. Whether Python 3.10 or newer, Git, pipx, Codex, and the car command are installed.
3. Whether a CAR hub already exists and which port it uses.
4. Whether Project 1 and Project 2 are already Git repositories.

Then propose the smallest safe setup plan. Do not delete files, reset Git state,
overwrite an existing CAR database, or use a force option without explaining the
risk and asking for my approval first. Do not expose credentials, tokens, or
private paths in your response.

After I approve the plan, help me:
1. Install or upgrade only the missing tools.
2. Create or reuse one hub at ~/car-hub.
3. Register Project 1 and Project 2 as separate repositories in that hub.
4. Start the Web Hub on port 8765.
5. Verify the repository list and show me the correct browser URL.
6. Create a small test ticket only after I explicitly approve it.

If port 8765 is already in use, stop and explain the conflict. Do not kill a
process automatically. At the end, show the commands that were run and the
verification results.

This prompt is a guide, not a replacement for reviewing commands. The assistant should stop when it finds an existing hub, an uncommitted repository, a port conflict, or a command that could overwrite data. You can also adapt the project names and paths to match your own workspace.

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. You can keep Codex as the agent or connect OpenCode Go and select an opencode-go/... model for a new chat. 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.