Installing Open Run

Open Run runs on your machine and drives coding-agent CLIs you already have installed and logged in. There is no account to create and no API key to paste. Sign in to the optional control plane is separate and not required.

Requirements

gh (GitHub CLI), logged in, is needed for Create pull request. Without it the button stays disabled and says why on hover.

Windows: run Open Run inside WSL2, not native Windows. PATH resolution, process spawning, and the file modes that protect stored secrets assume a POSIX environment. Native Windows is not tested.

Install

Packaged CLI

Install @dennisadriaans/openrun globally to use the openrun command from any project:

npm install -g @dennisadriaans/openrun

This includes the local background worker. Continue with your first CLI run to register a repository and start work. It needs no source checkout, pnpm, or web build.

From source

Use the source installation for the web app or development:

git clone https://github.com/dennisadriaans/openrun.git
cd openrun
pnpm install

pnpm install builds better-sqlite3 from source if there is no prebuilt binary, which needs a C++ toolchain (xcode-select --install on macOS; build-essential and python3 on Debian/Ubuntu). There is no npm lockfile — use pnpm. pnpm-workspace.yaml allows the better-sqlite3 build script, which pnpm otherwise blocks.

First run

Start from the terminal or open the web app. Both use your installed agent CLIs and save to the same local database.

From the terminal

For a source installation, run pnpm link --global from the Open Run directory. An npm global installation already provides the command. Switch to the Git repository you want to work on:

cd /path/to/your/repository
openrun init
openrun run "summarise the recent changes in this repository"

Open Run preselects your last-used agent, or an installed agent on first use. Press Enter to confirm it, then Enter again to run. Use the arrow keys to choose another agent, schedule for later, or edit the settings. It prints an openrun show <run-id> command to inspect the result.

You can also start with just openrun for the guided menu. An unregistered checkout leads into setup when you start a run.

The first application command starts a local background worker. It keeps running after the terminal closes; start it again with openrun worker start after a reboot. No web build or Open Run account is needed.

Continue with Command line for scheduling, run management, integrations, and worker controls.

In the browser

From the Open Run installation directory:

pnpm dev

Open http://localhost:3000. If you started the CLI worker above, run openrun worker stop first; stopping it cancels active runs. Both interfaces share your projects, automations, and history.

1. Add a project. From Automations, open Projects and point at a local git repository, or clone one. Automations need a workspace; without a project, New automation sends you here instead of a form that cannot save.
2. Automations → New automation. Pick the project — Open Run auto-selects a ready workspace and an installed runtime. Write the prompt under Agent Instructions. Create stays disabled until there is one.
3. Run now. Open the run to watch stdout stream in.

Start with something read-only ("summarise what changed this week") before you arm a schedule. See the security model.

Where things live

Override the home directory with OPENRUN_HOME. Use the same value for the CLI and web app to share state. Deleting the database removes saved history and configuration; deleting data-key makes its sealed secrets unreadable.

Older installs may have ~/.agentops/ or a database under data/openrun.db or data/agentops.db. On startup, Open Run adopts that data into the current location when appropriate. For an older checkout database, start from that Open Run installation directory so it can be found.

Configuration

Every setting has a working default; Open Run runs with no .env at all. For the web app, .env.example lists settings you can put in .env. Export environment variables in your shell when using the CLI; the worker inherits them when it starts.

Open Run binds 127.0.0.1 and refuses to start on a public interface without an access token, because a reachable Open Run is arbitrary command execution as you. Details: the bind address.

Production

The npm package includes a compiled CLI worker. A source checkout can also run the worker directly. For a production web build, stop any running worker first, then run:

pnpm build
pnpm start

pnpm start resolves the bind address, refuses an unsafe one, then serves the build. Set PORT to change the port.

Scripts

pnpm dev             # dev server on :3000 (loopback)
pnpm dev:mobile      # same, plus the iPhone pairing API on the LAN
pnpm build           # production build into dist/
pnpm start           # serve the build, with the bind guard
pnpm token:print     # print/create the access token + browser sign-in URL
pnpm cli --help      # local CLI commands and examples
pnpm typecheck       # tsc --noEmit
pnpm test            # unit tests (node:test)

Troubleshooting

"Runtime not on PATH" — Open Run looks up the binary in your login shell's PATH, not the one the dev server inherited. If which claude works in your terminal but Open Run disagrees, restart it from that same shell. Check the resolved name under Runtimes.

Nothing happens when a schedule fires — the automation must be enabled, have a valid cron expression (5- or 6-field), a ready workspace, an installed runtime, and a non-empty prompt. Hover the disabled control for the reason.

Native resume picker is empty — listing is keyed off the workspace folder, not the git remote. Point the project at the same cwd you ran the CLI in. Worktrees under ~/.openrun will not see chats started in your main checkout. Claude, Codex, Grok, and Antigravity (agy) chats are listed; Gemini CLI chats are not.

A "once at 03:01" automation did not fire — Open Run has to be running (laptop awake) at that time. This is local; the hosted Worker does not run your CLIs.

better-sqlite3 fails to build — install a C++ toolchain (above), then rm -rf node_modules && pnpm install. Confirm node -v is 22.12+.

Runs stuck "running" after a crash — Open Run reaps orphans on boot. Restart it.

A 401 on every request — an access token is configured (OPENRUN_ACCESS_TOKEN or ~/.openrun/access-token) and this browser has not been signed in. Run pnpm token:print and open the URL it prints (http://127.0.0.1:3000/?openrun_token=…) once. A loopback-only install does not need a token: delete the file or unset the env var.

Still stuck? Open a Discussion.