{"id":51712300,"url":"https://github.com/ColeMurray/background-agents","last_synced_at":"2026-07-29T13:00:34.715Z","repository":{"id":334590414,"uuid":"1141974122","full_name":"ColeMurray/background-agents","owner":"ColeMurray","description":"An open-source background agents coding system","archived":false,"fork":false,"pushed_at":"2026-07-29T06:56:14.000Z","size":9402,"stargazers_count":2582,"open_issues_count":63,"forks_count":372,"subscribers_count":12,"default_branch":"main","last_synced_at":"2026-07-29T08:04:44.030Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://backgroundagents.dev","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ColeMurray.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-25T18:45:47.000Z","updated_at":"2026-07-29T07:40:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"f936014d-5010-4466-b1bb-1a38bddb37c2","html_url":"https://github.com/ColeMurray/background-agents","commit_stats":null,"previous_names":["colemurray/background-agents"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ColeMurray/background-agents","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColeMurray%2Fbackground-agents","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColeMurray%2Fbackground-agents/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColeMurray%2Fbackground-agents/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColeMurray%2Fbackground-agents/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ColeMurray","download_url":"https://codeload.github.com/ColeMurray/background-agents/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ColeMurray%2Fbackground-agents/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36032918,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-29T02:00:04.910Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-16T23:00:32.919Z","updated_at":"2026-07-29T13:00:34.708Z","avatar_url":"https://github.com/ColeMurray.png","language":"TypeScript","funding_links":[],"categories":["4. Agentic AI \u0026 Multi-Agent Systems","Ranked AI Coding Agents","Autonomous Task Runners","Repos"],"sub_categories":[],"readme":"# Background Agents: Open-Inspect\n\nAn open-source background agents coding system inspired by\n[Ramp's Inspect](https://builders.ramp.com/post/why-we-built-our-background-agent).\n\n## Overview\n\nOpen-Inspect provides a hosted background coding agent that can:\n\n- Work on tasks in the background while you focus on other things\n- Access full development environments (Node.js, Python, git, browser automation, VS Code)\n- Connect from anywhere — web UI, Slack, GitHub PRs, Linear issues, or webhooks\n- Enable multiplayer sessions where multiple people can collaborate in real time\n- Create PRs with proper commit attribution to the prompting user\n- Run on a schedule — cron jobs, Sentry alerts, and webhook-triggered automations\n- Spawn parallel sub-tasks that work in separate sandboxes simultaneously\n- Use your choice of AI model — Anthropic Claude, OpenAI Codex (via ChatGPT subscription), or\n  OpenCode Zen\n\n## Security Model (Single-Tenant Only)\n\n\u003e **Important**: This system is designed for **single-tenant deployment only**, where all users are\n\u003e trusted members of the same organization with access to the same repositories.\n\n### How It Works\n\nThe system uses a shared GitHub App installation for git operations (clone, fetch, push). The\ncontrol plane mints short-lived installation tokens server-side and brokers them to sandboxes\nthrough the git credential helper on demand. This means:\n\n- **All users share the same GitHub App credentials** - The GitHub App must be installed on your\n  organization's repositories, and any user of the system can access any repo the App has access to\n- **No per-user repository access validation** - The system does not verify that a user has\n  permission to access a specific repository before creating a session\n- **GitHub users' OAuth tokens are used for PR creation** - For GitHub logins, PRs are created using\n  the user's GitHub OAuth token, ensuring proper attribution and that they can only create PRs on\n  repos they have write access to. Users who sign in another way (e.g. Google) carry no SCM token,\n  so their PRs fall back to the shared GitHub App bot\n\n### Token Architecture\n\n| Token Type         | Purpose                                | Scope                            |\n| ------------------ | -------------------------------------- | -------------------------------- |\n| GitHub App Token   | Brokered git clone/fetch/push auth     | All repos where App is installed |\n| User OAuth Token   | Create PRs, user info                  | Repos user has access to         |\n| Sandbox Auth Token | Sandbox-to-control-plane session calls | Single session                   |\n| WebSocket Token    | Real-time session auth                 | Single session                   |\n\n### Why Single-Tenant Only\n\nThis architecture follows\n[Ramp's Inspect design](https://builders.ramp.com/post/why-we-built-our-background-agent), which was\nbuilt for internal use where all employees are trusted and have access to company repositories.\n\n**For multi-tenant deployment**, you would need:\n\n- Per-tenant GitHub App installations\n- Access validation at session creation\n- Tenant isolation in the data model\n\n### Deployment Recommendations\n\n1. **Deploy behind your organization's SSO/VPN** - Ensure only authorized employees can access the\n   web interface\n2. **Install GitHub App only on intended repositories** - The App's installation scope defines what\n   the system can access\n3. **Restrict sign-in** - Configure allowed GitHub users, email domains, or active GitHub\n   organization membership (`ALLOWED_GITHUB_ORGS`)\n4. **Use GitHub's repository selection** - When installing the App, select specific repositories\n   rather than \"All repositories\"\n\n## Architecture\n\n```\n                                    ┌──────────────────┐\n                                    │     Clients      │\n                                    │ ┌──────────────┐ │\n                                    │ │  Web / Slack │ │\n                                    │ │ GitHub / Lin.│ │\n                                    │ │   Webhooks   │ │\n                                    │ └──────────────┘ │\n                                    └────────┬─────────┘\n                                             │\n                                             ▼\n┌────────────────────────────────────────────────────────────────────┐\n│                     Control Plane (Cloudflare)                     │\n│  ┌──────────────────────────────────────────────────────────────┐  │\n│  │                   Durable Objects (per session)              │  │\n│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐  ┌───────────────┐    │  │\n│  │  │ SQLite  │  │WebSocket│  │  Event  │  │   GitHub      │    │  │\n│  │  │   DB    │  │   Hub   │  │ Stream  │  │ Integration   │    │  │\n│  │  └─────────┘  └─────────┘  └─────────┘  └───────────────┘    │  │\n│  └──────────────────────────────────────────────────────────────┘  │\n│  ┌──────────────────────────────────────────────────────────────┐  │\n│  │              D1 Database (repo-scoped secrets)               │  │\n│  └──────────────────────────────────────────────────────────────┘  │\n└────────────────────────────────┬───────────────────────────────────┘\n                                 │\n                                 ▼\n┌────────────────────────────────────────────────────────────────────┐\n│                 Data Plane (Sandbox Backend)                       │\n│  ┌──────────────────────────────────────────────────────────────┐  │\n│  │                     Session Sandbox                          │  │\n│  │  ┌───────────┐  ┌───────────┐  ┌───────────┐                 │  │\n│  │  │ Supervisor│──│  OpenCode │──│   Bridge  │─────────────────┼──┼──▶ Control Plane\n│  │  └───────────┘  └───────────┘  └───────────┘                 │  │\n│  │                      │                                       │  │\n│  │              Full Dev Environment                            │  │\n│  │      (Node.js, Python, git, agent-browser)                   │  │\n│  └──────────────────────────────────────────────────────────────┘  │\n└────────────────────────────────────────────────────────────────────┘\n```\n\n## Packages\n\n| Package                                           | Description                                 |\n| ------------------------------------------------- | ------------------------------------------- |\n| [control-plane](packages/control-plane)           | Cloudflare Workers + Durable Objects        |\n| [web](packages/web)                               | Next.js web client                          |\n| [sandbox-runtime](packages/sandbox-runtime)       | Shared in-sandbox agent runtime             |\n| [modal-infra](packages/modal-infra)               | Modal sandbox infrastructure                |\n| [daytona-infra](packages/daytona-infra)           | Daytona snapshot infrastructure             |\n| [e2b-infra](packages/e2b-infra)                   | E2B sandbox template infrastructure         |\n| [opencomputer-infra](packages/opencomputer-infra) | OpenComputer template infrastructure        |\n| [slack-bot](packages/slack-bot)                   | Slack integration (sessions from messages)  |\n| [github-bot](packages/github-bot)                 | GitHub integration (auto-review, @mention)  |\n| [linear-bot](packages/linear-bot)                 | Linear integration (issue → coding session) |\n| [shared](packages/shared)                         | Shared types and utilities                  |\n\n## Getting Started\n\nFor a practical setup guide (local + contributor + deployment paths), start with\n**[docs/SETUP_GUIDE.md](docs/SETUP_GUIDE.md)**.\n\nSee **[docs/GETTING_STARTED.md](docs/GETTING_STARTED.md)** for deployment instructions.\n\nTo understand the architecture and core concepts, read\n**[docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md)**.\n\nTo set up recurring scheduled tasks, see **[docs/AUTOMATIONS.md](docs/AUTOMATIONS.md)**.\n\n## Key Features\n\n### Fast Startup\n\nSessions start near-instantly through multiple layers of warming:\n\n- **Filesystem snapshots** — After each prompt, sandbox state is saved; follow-up sessions restore\n  instead of re-cloning\n- **Pre-built images** — Toggle per-repo (Settings \u003e Images) or per-environment (Settings \u003e\n  Environments); rebuilt every 30 minutes with latest commits and dependencies\n- **Proactive warming** — Sandbox begins spinning up as soon as you start typing, before you hit\n  Enter\n\n### Multi-Repository Sessions \u0026 Environments\n\nOne session can work across several repositories in a single sandbox:\n\n- **Ad-hoc sets** — Pick up to 10 repositories in the new-session picker; each is cloned side by\n  side and the agent can make coordinated changes and open a PR per repository\n- **Environments** — Save a repository set as a named environment with its own secrets scope and\n  optional prebuilt images, then launch it from the picker like any repository\n- See [docs/HOW_IT_WORKS.md](docs/HOW_IT_WORKS.md#environments) for the model and\n  [docs/IMAGE_PREBUILD.md](docs/IMAGE_PREBUILD.md) for environment prebuilds\n\n### Multiplayer Sessions\n\nMultiple users can collaborate in the same session:\n\n- Presence indicators show who's active\n- Prompts are attributed to their authors in git commits\n- Real-time streaming to all connected clients\n\n### Commit Attribution\n\nCommits are attributed to the user who sent the prompt:\n\n```typescript\n// Configure git identity per prompt\nawait configureGitIdentity({\n  name: author.scmName,\n  email: author.scmEmail,\n});\n```\n\n### Multi-Provider Model Support\n\nChoose the AI model that fits your task, with per-session reasoning effort controls:\n\n| Provider         | Models                                                            |\n| ---------------- | ----------------------------------------------------------------- |\n| Anthropic        | Claude Haiku 4.5, Sonnet 4.5/4.6, Opus 4.5/4.6/4.7/4.8/5, Fable 5 |\n| OpenAI           | GPT 5.4, GPT 5.5, 5.3 Codex, 5.3 Codex Spark                      |\n| OpenCode Zen     | Kimi K2.5/K2.6, MiniMax M2.5, Qwen3.7 Max, GLM 5/5.1 (opt-in)     |\n| Z.AI Coding Plan | GLM 5.2 (opt-in)                                                  |\n\nOpenAI models work with your existing ChatGPT subscription via OAuth — no separate API key needed.\nSee **[docs/AVAILABLE_MODELS.md](docs/AVAILABLE_MODELS.md)** for the full model list and\n**[docs/OPENAI_MODELS.md](docs/OPENAI_MODELS.md)** for OpenAI setup instructions.\n\n### Client Integrations\n\nInteract with agents from wherever your team already works:\n\n- **Web UI** — Full session management with real-time streaming, model/reasoning selectors, terminal\n  panel, and multiplayer presence\n- **Slack Bot** — @mention or DM to start a session, with PNG, JPEG, WebP, and GIF prompt\n  attachments; replies thread back with results. Per-user model and branch preferences via App Home.\n  See [Slack integration](docs/integrations/SLACK.md)\n- **GitHub Bot** — Auto-review on PR open or respond to @mentions in PR comments. Configurable\n  per-repo. See [GitHub integration](docs/integrations/GITHUB.md)\n- **Linear Bot** — Mention or assign the agent on an issue to start a coding session, post progress\n  activities, and link the resulting PR. See [Linear integration](docs/integrations/LINEAR.md)\n- **Webhooks** — Trigger sessions from any external system via authenticated HTTP POST\n\n### Automations\n\nSchedule recurring tasks or react to external events — no human in the loop:\n\n- **Cron schedules** — Hourly, daily, weekly, monthly, or custom 5-field cron with timezone support\n- **Sentry alerts** — Auto-triage on new errors, regressions, or critical metric alerts\n- **Inbound webhooks** — JSONPath condition filters to gate which payloads spawn sessions\n- **Multi-repo fan-out** — One scheduled automation can run across up to 10 repositories, opening a\n  separate session and pull request for each\n- Auto-pause after 3 consecutive failures, manual trigger button, full run history\n\nSee **[docs/AUTOMATIONS.md](docs/AUTOMATIONS.md)** for setup instructions.\n\n### Sandbox Environment\n\nEvery session runs in an isolated sandbox backend with a full development environment:\n\n- **Pre-installed:** Node.js 22, Python 3.12, Bun, git, GitHub CLI, build-essential\n- **Browser automation:** agent-browser CLI with headless Chromium for screenshots, visual diffs,\n  and UI verification\n- **Code-server:** Optional browser-based VS Code connected to the session workspace\n- **Web terminal:** ttyd-powered terminal accessible from the session UI\n- **Port tunneling:** Expose up to 10 dev server ports via encrypted tunnels. URLs are available\n  in-sandbox at `/workspace/.tunnels.env` before `.openinspect/start.sh` runs\n  ([details](docs/HOW_IT_WORKS.md#tunnel-urls-inside-the-sandbox))\n- **Secrets:** AES-256-GCM encrypted, scoped globally, per-repo, or per-environment, injected as env\n  vars at spawn time. Supports bulk `.env` paste import\n\n### Sub-Task Spawning\n\nAgents can decompose work into parallel child sessions:\n\n- `spawn-task` creates a child session in its own sandbox and returns immediately\n- Parent continues working while children run in parallel on separate branches\n- `get-task-status` and `cancel-task` for coordination\n- Depth limits and per-repo guardrails enforced\n\n### Repository Lifecycle Scripts\n\nRepositories can define two optional startup scripts under `.openinspect/`:\n\n```bash\n# .openinspect/setup.sh (provisioning)\n#!/bin/bash\nnpm install\npip install -r requirements.txt\n```\n\n```bash\n# .openinspect/start.sh (runtime startup)\n#!/bin/bash\ndocker compose up -d postgres redis\n```\n\n- `setup.sh` runs for image builds and fresh sessions\n- `setup.sh` is skipped for prebuilt-image and snapshot-restore starts\n- `setup.sh` failures are non-fatal for fresh sessions, but fatal in image build mode\n- `start.sh` runs for every non-build session startup (fresh, prebuilt-image, snapshot-restore)\n- `start.sh` failures are strict: if present and it fails, session startup fails\n- Default timeouts:\n  - `SETUP_TIMEOUT_SECONDS` (default `300`)\n  - `START_TIMEOUT_SECONDS` (default `120`)\n- Both hooks receive `OPENINSPECT_BOOT_MODE` (`build`, `fresh`, `repo_image`, `snapshot_restore`)\n- Git operations in hooks can authenticate to other private repos on the configured SCM host when\n  the shared installation has access\n\n## License\n\nMIT\n\n## Credits\n\nInspired by [Ramp's Inspect](https://builders.ramp.com/post/why-we-built-our-background-agent) and\nbuilt with:\n\n- [Modal](https://modal.com) - Cloud sandbox infrastructure\n- [Daytona](https://www.daytona.io) - Cloud development sandboxes\n- [Vercel Sandbox](https://vercel.com/docs/vercel-sandbox) - Cloud sandbox infrastructure\n- [OpenComputer](https://www.opencomputer.dev) - Cloud sandbox infrastructure\n- [E2B](https://e2b.dev) - Cloud sandbox infrastructure\n- [Cloudflare Workers](https://workers.cloudflare.com) - Edge computing\n- [OpenCode](https://opencode.ai) - Coding agent runtime\n- [Next.js](https://nextjs.org) - Web framework\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FColeMurray%2Fbackground-agents","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FColeMurray%2Fbackground-agents","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FColeMurray%2Fbackground-agents/lists"}