# background-agents | Cole Murray | Knowledge Base | Instagit

An open-source background agents coding system

GitHub Stars: 2.4k

Repository: https://github.com/ColeMurray/background-agents

---

## Articles

### [How Execution and Inactivity Timeouts Are Handled in Background Agents](/ColeMurray/background-agents/execution-timeout-and-inactivity-timeout-handling)

Discover how background agents handle execution and inactivity timeouts with configurable settings managed by the SandboxSupervisor. Learn about asyncio wait_for and deadline checks.

- Tags: deep-dive
- Published: 2026-07-13

### [How Integration Webhooks (Slack, Linear, GitHub) Trigger Session Creation in Background Agents](/ColeMurray/background-agents/integration-webhook-handlers-slack-linear-github)

Learn how integration webhooks for Slack, Linear, and GitHub trigger background agent session creation. Understand the process from request validation to sandbox spawning.

- Tags: how-to-guide
- Published: 2026-07-13

### [D1 Database Schema for Session Index in Background Agents: Complete Reference](/ColeMurray/background-agents/d1-database-schema-for-session-index)

Explore the D1 database schema for session index in background agents. Understand the normalized tables and composite indexes for efficient repository-scoped session management and metadata retrieval.

- Tags: api-reference
- Published: 2026-07-13

### [When Background Agents Use User OAuth Tokens vs GitHub App Tokens for Pull Request Creation](/ColeMurray/background-agents/pull-request-creation-oauth-fallback)

Learn when background agents use user OAuth tokens versus GitHub App tokens for pull request creation. Understand authentication fallbacks and optimal token usage for your workflow.

- Tags: best-practices
- Published: 2026-07-13

### [How Git Branch Attribution Works Per Prompt in Background Agents](/ColeMurray/background-agents/git-branch-attribution-per-prompt)

Understand how background agents manage Git branch attribution using session-level WebSocket messages, with prompts automatically inheriting the branch state.

- Tags: internals
- Published: 2026-07-13

### [How Artifact Media Streaming and Upload Work in Background Agents](/ColeMurray/background-agents/artifact-media-streaming-and-upload)

Learn how background agents stream and upload artifact media using control-plane routes and React frontend utilities for seamless data handling. Explore the API endpoints for media management.

- Tags: how-to-guide
- Published: 2026-07-13

### [Repository Lifecycle Scripts in Background Agents: Understanding setup.sh and start.sh](/ColeMurray/background-agents/repository-lifecycle-scripts-setup-sh-and-start-sh)

Understand repository lifecycle scripts setup.sh and start.sh. Learn how these background agents scripts handle one-time provisioning and per-session runtime initialization for efficient deployments.

- Tags: internals
- Published: 2026-07-13

### [How the Callback Notification Delivery System Works in Background Agents](/ColeMurray/background-agents/callback-notification-delivery-system)

Understand how the callback notification delivery system works in background agents. Learn about secure HTTP callbacks signed JSON payloads and asynchronous processing for real-time notifications.

- Tags: how-to-guide
- Published: 2026-07-13

### [How Background-Agents Implements a Circuit Breaker Mechanism for Sandbox Failures](/ColeMurray/background-agents/circuit-breaker-for-sandbox-failures)

Learn how Background-Agents uses a circuit breaker mechanism to prevent sandbox failures. Discover the default thresholds and how it safeguards your system.

- Tags: deep-dive
- Published: 2026-07-13

### [How the Automation Scheduler Processes Cron Triggers in Background Agents](/ColeMurray/background-agents/automation-scheduler-cron-processing)

Discover how the automation scheduler processes cron triggers in background agents. Learn how it checks Git commits for changes to intelligently enqueue image rebuild jobs.

- Tags: internals
- Published: 2026-07-13

### [How Background Agents Handle Token Refresh for Model Providers and SCM Integrations](/ColeMurray/background-agents/model-provider-token-refresh-handling)

Discover how background agents manage token refresh for model providers and SCM integrations. Learn about static API keys and automated OAuth refresh flows.

- Tags: how-to-guide
- Published: 2026-07-13

### [How MCP Servers Are Integrated Per Repository in Background-Agents](/ColeMurray/background-agents/mcp-server-integration-per-repository)

Learn how Background-Agents integrates MCP servers per repository. Discover how scoped server definitions in D1 are resolved and configured for your runtime.

- Tags: internals
- Published: 2026-07-13

### [How Tunnel Ports Are Exposed Inside Sandboxes in Background Agents](/ColeMurray/background-agents/tunnel-port-exposure-inside-sandboxes)

Learn how Background Agents expose tunnel ports inside sandboxes. Discover the generated env file that maps ports to public URLs, ensuring fresh connections before your code runs.

- Tags: internals
- Published: 2026-07-13

### [How Child Session Spawning and Coordination Works in Background-Agents](/ColeMurray/background-agents/child-session-spawning-and-coordination)

Learn how the background agents library manages child session spawning and coordination using a three layer architecture. Discover its hierarchical limits and state propagation techniques.

- Tags: internals
- Published: 2026-07-13

### [Source Control Provider Abstraction Architecture in Background Agents](/ColeMurray/background-agents/source-control-provider-abstraction)

Explore the source control provider abstraction architecture in background agents. This pluggable interface isolates SCM operations for GitHub, GitLab, and Bitbucket via a single contract.

- Tags: architecture
- Published: 2026-07-13

### [How Background Agents Resolve Multi-Repository Session Targets: A Complete Technical Guide](/ColeMurray/background-agents/multi-repository-session-target-resolution)

Learn how background agents resolve multi-repository session targets using a two-phase validation pipeline. Ensure workspace integrity with all-or-nothing semantics.

- Tags: deep-dive
- Published: 2026-07-13

### [How the Image Prebuild System Workflow Operates in Background Agents](/ColeMurray/background-agents/image-prebuild-system-workflow)

Understand the image prebuild system workflow in background agents. Discover how this three-phase pipeline optimizes session start-up by caching environments.

- Tags: internals
- Published: 2026-07-13

### [Sandbox Lifecycle Manager Spawning Flow in Background‑Agents: A Complete Technical Guide](/ColeMurray/background-agents/sandbox-lifecycle-manager-spawning-flow)

Uncover the sandbox lifecycle manager spawning flow in BackgroundAgents. This guide details its six-stage pipeline from API request to container teardown for isolated coding environments.

- Tags: deep-dive
- Published: 2026-07-13

### [Session Lifecycle State Machine Transitions in Background-Agents: Complete Technical Guide](/ColeMurray/background-agents/session-lifecycle-state-machine-transitions)

Understand background agent session lifecycle state machine transitions. Explore active, archived, and terminal states and automatic reactivation with this technical guide.

- Tags: deep-dive
- Published: 2026-07-13

### [How Durable Object Hibernation Recovers Session State in Background Agents](/ColeMurray/background-agents/how-durable-object-hibernation-recovers-session-state)

Learn how Durable Object hibernation recovers session state by re-reading SQLite data upon waking, rebuilding WebSocket mappings and re-hydrating services.

- Tags: internals
- Published: 2026-07-13