background-agents

Background Agents: Open-Inspect

An open-source background agents coding system inspired by Ramp's Inspect.

Overview

Open-Inspect provides a hosted background coding agent that can:

• Work on tasks in the background while you focus on other things
• Access full development environments (Node.js, Python, git, browser automation, VS Code)
• Connect from anywhere — web UI, Slack, GitHub PRs, Linear issues, or webhooks
• Enable multiplayer sessions where multiple people can collaborate in real time
• Create PRs with proper commit attribution to the prompting user
• Run scheduled automations for cron jobs, or event-driven automations for GitHub events, Sentry alerts, and webhooks
• Spawn parallel sub-tasks that work in separate sandboxes simultaneously
• Use your choice of AI model — Anthropic Claude (via API key or a connected Claude subscription on the Claude Agent harness), OpenAI Codex (via ChatGPT subscription), xAI Grok (via SuperGrok subscription), or OpenCode Zen

Security Model (Single-Tenant Only)

Important: This system is designed for single-tenant deployment only, where all users are trusted members of the same organization with access to the same repositories.

How It Works

The system uses a shared GitHub App installation for git operations (clone, fetch, push). The control plane mints short-lived installation tokens server-side and brokers them to sandboxes through the git credential helper on demand. This means:

• Authorized users share the same GitHub App credentials - The GitHub App must be installed on your organization's repositories, and active users whose role permits repository use can access any repo the App has access to
• No per-user repository access validation - The system does not verify that a user has permission to access a specific repository before creating a session
• GitHub users' OAuth tokens are used for PR creation - For GitHub logins, PRs are created using the user's GitHub OAuth token, ensuring proper attribution and that they can only create PRs on repos they have write access to. Users who sign in another way (e.g. Google) carry no SCM token, so their PRs fall back to the shared GitHub App bot

Token Architecture

Why Single-Tenant Only

This architecture follows Ramp's Inspect design, which was built for internal use where all employees are trusted and have access to company repositories.

For multi-tenant deployment, you would need:

• Per-tenant GitHub App installations
• Access validation at session creation
• Tenant isolation in the data model

Deployment Recommendations

1. Deploy behind your organization's SSO/VPN - Ensure only authorized employees can access the web interface
2. Install GitHub App only on intended repositories - The App's installation scope defines what the system can access
3. Restrict sign-in - Configure allowed GitHub users, email domains, or active GitHub organization membership (ALLOWED_GITHUB_ORGS)
4. Use GitHub's repository selection - When installing the App, select specific repositories rather than "All repositories"

See Authentication and Authorization for workspace roles, session access, automation ownership, bots, and member suspension.

Architecture

…

Packages

Getting Started

For a practical setup guide (local + contributor + deployment paths), start with docs/SETUP_GUIDE.md.

See docs/GETTING_STARTED.md for deployment instructions.

To understand the architecture and core concepts, read docs/HOW_IT_WORKS.md.

To set up recurring scheduled tasks, see docs/AUTOMATIONS.md.

To create and use reusable agent instructions, see docs/MANAGED_SKILLS.md.

Key Features

Fast Startup

Sessions start near-instantly through multiple layers of warming:

• Filesystem snapshots — After each prompt, sandbox state is saved; follow-up sessions restore instead of re-cloning
• Pre-built images — Toggle per-repo (Settings > Images) or per-environment (Settings > Environments); rebuilt every 30 minutes with latest commits and dependencies
• Proactive warming — Sandbox begins spinning up as soon as you start typing, before you hit Enter

Multi-Repository Sessions & Environments

One session can work across several repositories in a single sandbox:

• Ad-hoc sets — Pick up to 10 repositories in the new-session picker; each is cloned side by side and the agent can make coordinated changes and open a PR per repository
• Environments — Save a repository set as a named environment with its own secrets scope and optional prebuilt images, then launch it from the picker like any repository
• See docs/HOW_IT_WORKS.md for the model and docs/IMAGE_PREBUILD.md for environment prebuilds

Managed Skills

Create reusable instructions and supporting files that agents receive when a session starts:

• Assign shared skills globally or to selected repositories and environments
• Save personal profiles for frequently used skill sets
• Pin exact skill revisions to each session for repeatable behavior
• See docs/MANAGED_SKILLS.md for the user guide

Multiplayer Sessions

Multiple users can collaborate in the same session:

• Presence indicators show who's active
• Prompts are attributed to their authors in git commits
• Real-time streaming to all connected clients

Commit Attribution

Commits are attributed to the user who sent the prompt:

// Configure git identity per prompt
await configureGitIdentity({
  name: author.scmName,
  email: author.scmEmail,
});

Multi-Provider Model Support

Choose the AI model that fits your task, with per-session reasoning effort controls:

OpenAI models work with your existing ChatGPT subscription via OAuth — no separate API key needed. Anthropic models can run on the Claude Agent harness with a connected Claude subscription; see Using the Claude Agent Harness. Grok models work with an eligible SuperGrok subscription through control-plane-managed OAuth. See docs/AVAILABLE_MODELS.md for the full model list and docs/OPENAI_MODELS.md or docs/GROK_MODELS.md for subscription setup instructions.

Client Integrations

Interact with agents from wherever your team already works:

• Web UI — Full session management with real-time streaming, model/reasoning selectors, terminal panel, and multiplayer presence
• Slack Bot — @mention or DM to start a session, with PNG, JPEG, WebP, and GIF prompt attachments; replies thread back with results. Per-user model and branch preferences via App Home. See Slack integration
• GitHub Bot — Auto-review on PR open or respond to @mentions in PR comments. Configurable per-repo. See GitHub integration
• Linear Bot — Mention or assign the agent on an issue to start a coding session, post progress activities, and link the resulting PR. See Linear integration
• Webhooks — Trigger sessions from any external system via authenticated HTTP POST

Automations

Schedule recurring tasks or react to external events — no human in the loop:

• Cron schedules — Hourly, daily, weekly, monthly, or custom 5-field cron with timezone support
• Sentry alerts — Auto-triage on new errors, regressions, or critical metric alerts
• GitHub workflow runs — Start work when a GitHub Actions workflow finishes, with optional workflow-name and conclusion filters
• Inbound webhooks — JSONPath condition filters to gate which payloads spawn sessions
• Multi-repo fan-out — One scheduled automation can run across up to 10 repositories, opening a separate session and pull request for each
• Auto-pause after 3 consecutive failures, manual trigger button, full run history

See docs/AUTOMATIONS.md for setup instructions.

Sandbox Environment

Every session runs in an isolated sandbox backend with a full development environment:

• Pre-installed: Node.js 22, Python 3.12, Bun, git, GitHub CLI, build-essential
• Browser automation: agent-browser CLI with headless Chromium for screenshots, visual diffs, and UI verification
• Code-server: Optional browser-based VS Code connected to the session workspace
• Web terminal: ttyd-powered terminal accessible from the session UI
• Port tunneling: Expose up to 10 dev server ports via encrypted tunnels. URLs are available in-sandbox at /workspace/.tunnels.env before .openinspect/start.sh runs (details)
• Secrets: AES-256-GCM encrypted, scoped globally, per-repo, or per-environment, injected as env vars at spawn time. Supports bulk .env paste import

Child Sessions

Agents can decompose work into parallel child sessions:

• spawn-child creates a child session in its own sandbox and returns immediately
• Parent con