open-source agent runtime

Fire it.
Then forget it.

Hand oneshot a repo and a task. It plans, writes, reviews, and opens a PR in an isolated worktree, then hands you a receipt that proves the work held up. Detach it and walk away.

$ bun install -g oneshot-ship

Quick start

agent run

$ oneshot acme/api "fix auth timeout" --bg

run 1779090434-rxw89j  · detached
[1/8] validate     ok
[2/8] worktree     /tmp/oneshot-1779
[3/8] route        codex · deep
[4/8] plan         3 files
[5/8] execute      patched + tested
[6/8] draft PR     #142
[7/8] review       no major findings
[8/8] finalize     ready for review

ONESHOT RECEIPT

run 1779090434-rxw89j

shipped confidence: high

repo: acme/api
task: fix auth timeout
time: 4m 12s · 3 files
pr: #142 (ready)

✓ plan read the codebase
✓ review passed, deep mode
✓ policy gate clean
✓ base branch defaulted to main

Why it is different

Most agents can edit files. The hard part is trusting work you didn't watch.

Fire and forget

Detach with --bg, over SSH to a dev box, or in GitHub Actions. Close your laptop; it keeps going and pings you when it lands.

Proof-of-work receipts

Every run records its plan, review outcome, policy verdict, the defaults it assumed, and a confidence rating. Trust the result without re-reading the diff.

Durable anywhere

Run locally, over SSH, or in CI. Fresh git worktree per run, durable ledger, policy gates, and an MCP server. Same contract, same receipt.

Quick start

Three commands.

1
Install

Needs Bun, the GitHub CLI, and Codex or Claude Code.
```
bun install -g oneshot-ship
```
2
Configure

Pick a backend: this machine, SSH to a box, or GitHub Actions. Run oneshot doctor to check it.
```
oneshot init
```
3
Ship

Repo and task in. Add --bg to detach. Read the receipt when it lands.
```
oneshot acme/api "fix the login timeout" --bg
```

Run it anywhere

One contract, three executors.

Local

Runs on this machine. Detaches with --bg and survives a closed terminal.

oneshot acme/api "task" --bg

SSH

Ship to a 24/7 dev box over SSH so runs survive your laptop entirely.

host: "user@your-box"

GitHub Actions

Zero-infra durable runs. Scaffolds a workflow that uploads the receipt.

oneshot gha init

Commands

The ones you'll reach for.

oneshot <repo> "<task>": Ship a task. Add --bg to detach, --workflow for a preset.
oneshot receipt <run-id>: Read a run's proof-of-work. Add --json or --html.
oneshot runs: The durable ledger of every run, newest first.
oneshot eval: Success rate and timing across recent runs.
oneshot doctor: Check tools, config, SSH, and a specific checkout with --repo.
oneshot policy init: Add .oneshot/policy.json: protected paths, secret and gate checks.
oneshot gha init: Scaffold a GitHub Actions workflow for detached CI runs.
oneshot mcp serve: Expose run, receipt, status, policy, and eval as MCP tools.

Full flags, configuration, and workflow presets live in the README.

Configuration

A small file in `~/.oneshot/config.json`.

Set host to local to run here, an SSH target to use a box, or scaffold Actions with oneshot gha init. Repos resolve as owner/repo in either a nested or flat layout. Codex and Claude each stay on their configured frontier model; routing only varies effort.

Add a notify webhook or command and a detached run will ping you the moment its receipt is ready.

{
  "host": "local",
  "basePath": "~/projects",
  "provider": "codex",
  "routing": { "enabled": true },
  "notify": {
    "webhook": "https://..."
  },
  "codex": {
    "model": "gpt-5.5",
    "reviewModel": "gpt-5.5",
    "reasoningEffort": "xhigh"
  }
}

Fire it.Then forget it.