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

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

Open http://localhost:3000.

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

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. An existing ~/.agentops or data/agentops.db is still used if the Open Run path is not there yet. Both locations are git-ignored and created on first use.

Configuration

Every setting has a working default; Open Run runs with no .env at all. Copy .env.example to .env to change anything.

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

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 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 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.6+.

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.