DOCSEARCHbyAlgolia
Submit Docs

Open-Inspect Documentation

repository·main·Indexed 25 days ago

https://github.com/colemurray/background-agents

An open-source background coding agent system for single-tenant organizational use. It features a Control Plane built on Cloudflare Workers and Durable Objects for session management, real-time WebSocket streaming, and sandboxed environment execution. The system supports GitHub, Slack, and Linear integrations, allowing agents to perform complex development tasks, manage secrets, and automate pull requests.

Tokens
83.3K
Snippets
115
Records
377
Agent score
83%

What's inside open-inspect

  1. Overview of Open-Inspect Control Plane

    main

    The Open-Inspect Control Plane is a management layer built on Cloudflare Workers and Durable Objects. It is designed for session management and real-time streaming across multiple client types (Web, Slack, and browser extensions).

    Key capabilities include:

    • Session Management: Uses SQLite-backed Durable Objects to maintain state for individual sessions.
    • Real-time Streaming: Provides WebSocket connections with hibernation support to sync state across all connected clients.
    • GitHub Integration: Utilizes a GitHub App for repository access.
    • Secure Secret Management: Stores encrypted secrets (global, repo-scoped, and environment-scoped) in D1, which are then injected into sandboxes as environment variables.
    • Environment Management: Manages named repository sets, each with its own secrets and prebuilt images, stored in D1.

  2. Overview of the GitHub Bot

    main

    The GitHub Bot is a stateless Cloudflare Worker that acts as a webhook-to-session translator. It converts GitHub webhook events into Open-Inspect coding agent sessions.

    It provides two primary capabilities:

    1. Code Review: Automatically reviews newly opened PRs (when enabled) and submits structured feedback.
    2. Comment-Triggered Actions: Responds to @mentions of the bot in PR comments with analysis, summaries, or thread replies.

    Key Architectural Concepts:

    • Unidirectional Flow: The bot calls the Control Plane to create sessions, but the agent in the sandbox interacts with GitHub directly via the gh CLI to post reviews and comments.
    • Deduplication: Uses Cloudflare KV and the X-GitHub-Delivery header to prevent duplicate sessions from GitHub retries.
    • Statelessness: Every non-duplicate webhook creates a fresh session; the bot does not reuse sessions.
    • Context Gathering: The bot only uses metadata from the webhook payload. The agent itself is responsible for fetching diffs, file contents, and prior comments using the gh CLI.

  3. Overview of Open-Inspect Web Client

    main
    The Open-Inspect Web Client is a Next.js application designed for interacting with Open-Inspect coding sessions. It provides a dashboard for managing sessions, real-time streaming of session events via WebSockets, and a message timeline that displays tool calls and results. It supports GitHub and optional Google authentication via a Control Plane.

  4. Overview of Open-Inspect Background Agents

    main

    Open-Inspect is an open-source background coding agent system. It allows developers to delegate coding tasks to an agent that operates in a full development environment (including Node.js, Python, git, and browser automation).

    Key capabilities include:

    • Background Execution: Work on tasks while focusing on other activities.
    • Multi-channel Access: Connect via Web UI, Slack, GitHub PRs, Linear issues, or webhooks.
    • Collaboration: Supports multiplayer sessions for real-time collaboration.
    • Automated Workflows: Run on schedules (cron), Sentry alerts, or webhook triggers.
    • Parallelism: Spawn sub-tasks in separate sandboxes simultaneously.
    • Model Flexibility: Supports Anthropic Claude, OpenAI Codex (via ChatGPT), and OpenCode Zen.

  5. How the Inspect background agent works

    main

    Inspect is a background coding agent designed to close the loop on verifying work. Unlike standard agents, it has access to a full development environment and tools to prove its work (e.g., running tests, reviewing telemetry, querying feature flags, and visual verification for frontend work).

    Key Characteristics:

    • Sandboxed Execution: Each session runs in a sandboxed VM (using Modal) containing a full stack (Vite, Postgres, Temporal, etc.).
    • High Concurrency: Sessions are fast to start and can run concurrently without using local machine resources.
    • Multiplayer Support: Sessions are collaborative; multiple users can interact with the same session, and code changes are attributed to the specific user who prompted them.
    • Integrated Workflows: Supports interaction via Slack, Chrome extensions, web interfaces, Pull Request comments, and web-based VS Code editors.

  6. Understand the Multi-Repository Automation Model

    main

    Multi-repository automations allow you to run recurring maintenance across a set of up to ten repositories. Instead of a single execution, a single 'firing' (triggered by a schedule, manual trigger, or event) fans out into one independent 'run' per selected repository. Each run operates within its own sandbox session, owning its own branch, artifacts, and pull request flow.

    Hierarchy

    • Automation: The top-level configuration containing the repository selection.
    • Invocation: A single firing (e.g., a weekly schedule tick). It carries the scope and skip reasons.
    • Run: One per repository in the selection. Each run is linked to a specific session.
    • Session: An ordinary sandbox session that manages the actual work (checkout, sync, PRs).
    automation ── repositories (0..10, the live selection)
    │
    └── invocation                 one per firing (schedule tick, Trigger Now, or event)
          │                        carries the firing-scoped keys and skip reason
          └── runs (0..10)         one per repository, each linked to one session
                └── session        ordinary sandbox session; owns branch, artifacts, PR

  7. Configure Access Control for Open-Inspect

    main

    Access control is managed via allowlists in terraform.tfvars. A user is admitted if they match ANY of the following (OR semantics):

    • allowed_users: Comma-separated GitHub usernames.
    • allowed_email_domains: Comma-separated domains (e.g., example.com).
    • allowed_emails: Exact email addresses (recommended for users on shared domains like gmail.com).
    • allowed_github_orgs: Comma-separated GitHub organizations.

    Note: Terraform will fail if all allowlists are empty unless you set unsafe_allow_all_users = true.

  8. How OpenAI Token Management Works

    main

    Open-Inspect uses a secure token architecture for OpenAI access:

    1. Storage: The refresh token is stored securely in the control plane and is never exposed to sandboxes.
    2. Access: When a sandbox requires an OpenAI API call, it requests a short-lived access token from the control plane.
    3. Rotation: The control plane handles token refresh and rotation automatically. Only the temporary access token exists within the sandbox environment.
    4. Scoping: Credentials are scoped per repository, allowing different repositories to use different OpenAI accounts.

  9. Understand the Open-Inspect Web Client Architecture

    main

    The application is built using Next.js App Router and is organized into three main layers:

    1. App Router (Pages):

      • /: Dashboard (session list)
      • /session/new: Create new session
      • /session/[id]: Session view with streaming
      • /settings: Settings (secrets management)

    2. API Routes:

      • /api/auth/[...auth]: Signed auth proxy
      • /api/sessions: Session CRUD
      • /api/repos: Repository list
      • /api/repos/:owner/:name/secrets: Secrets CRUD

    3. Hooks:

      • useSessionSocket: Manages WebSocket connection and state.

    All API and WebSocket traffic is directed to the Control Plane.

  10. Determine Invocation Status for Multi-Repo Automations

    main

    In multi-repository automations, the status of an automation_invocation is derived from the terminal states of its child automation_runs. Use the following logic to determine the aggregate status:

    • skipped: No children exist.
    • starting / running: At least one child is currently in a starting or running state.
    • Terminal States (all children finished):
      • skipped: All children are skipped.
      • completed: All children finished successfully (none failed).
      • failed: No children reached a completed state (and none are running).
      • partial_failed: A mix of successful and failed children (e.g., 9 completed, 1 failed).

  11. Understand Slack Message Automation Feedback and Threading

    main

    When a Slack Message automation is triggered, the following lifecycle occurs:

    1. In-flight: The triggering message is marked with a 👀 reaction.
    2. Completion: The agent's final response is posted as a reply in the message's thread, including links to any opened pull requests and the full web session. The 👀 reaction is then cleared.
    3. Failure: If the run fails, a short failure notice is posted in the thread.

    Threaded Conversations: Every reply in a thread continues the same session for up to 7 days after the initial trigger.

    • Replies are enqueued as follow-up turns on the existing session (re-spawning it from a snapshot if it was idle).
    • Follow-up replies do not need to match the original trigger conditions.
    • If a reply occurs more than 7 days after the first trigger, it starts a fresh run.
    • If a reply occurs while a run is already active, it may return a concurrent_run_active notice.
    • Note: Follow-up replies also forward text only; attachments are not delivered to the session.

  12. How GitHub Bot workflows work

    main

    Open-Inspect supports several automated and manual workflows via GitHub:

    WorkflowHow it works
    Auto-review new PRsAutomatically reviews non-draft PRs when they are opened (if enabled).
    Respond to PR commentsThe bot responds when mentioned in a PR conversation comment.
    Respond to review threadsThe bot responds when mentioned in an inline review comment.
    Post back to GitHubThe agent can submit PR reviews, reply to threads, or post summary comments.
    Customize behaviorYou can configure repository scope, trigger users, models, and custom instructions.

    Note: Open-Inspect does not currently support GitHub slash commands or requesting the bot via the PR reviewer picker. Use @mention instead.