ranbot-ai/hosted-agents

Hosted Agent Infrastructure

Hosted agents run in remote sandboxed environments rather than on local machines. When designed well, they provide unlimited concurrency, consistent execution environments, and multiplayer collaboration. The critical insight is that session speed should be limited only by model provider time-to-first-token, with all infrastructure setup completed before the user starts their session.

When to Use

Activate this skill when:

• Building background coding agents that run independently of user devices
• Designing sandboxed execution environments for agent workloads
• Implementing multiplayer agent sessions with shared state
• Creating multi-client agent interfaces (Slack, Web, Chrome extensions)
• Scaling agent infrastructure beyond local machine constraints
• Building systems where agents spawn sub-agents for parallel work

Core Concepts

Hosted agents address the fundamental limitation of local agent execution: resource contention, environment inconsistency, and single-user constraints. By moving agent execution to remote sandboxed environments, teams gain unlimited concurrency, reproducible environments, and collaborative workflows.

The architecture consists of three layers: sandbox infrastructure for isolated execution, API layer for state management and client coordination, and client interfaces for user interaction across platforms. Each layer has specific design requirements that enable the system to scale.

Detailed Topics

Sandbox Infrastructure

The Core Challenge Spinning up full development environments quickly is the primary technical challenge. Users expect near-instant session starts, but development environments require cloning repositories, installing dependencies, and running build steps.

Image Registry Pattern Pre-build environment images on a regular cadence (every 30 minutes works well). Each image contains:

• Cloned repository at a known commit
• All runtime dependencies installed
• Initial setup and build commands completed
• Cached files from running app and test suite once

When starting a session, spin up a sandbox from the most recent image. The repository is at most 30 minutes out of date, making synchronization with the latest code much faster.

Snapshot and Restore Take filesystem snapshots at key points:

• After initial image build (base snapshot)
• When agent finishes making changes (session snapshot)
• Before sandbox exit for potential follow-up

This enables instant restoration for follow-up prompts without re-running setup.

Git Configuration for Background Agents Since git operations are not tied to a specific user during image builds:

• Generate GitHub app installation tokens for repository access during clone
• Update git config's user.name and user.email when committing and pushing changes
• Use the prompting user's identity for commits, not the app identity

Warm Pool Strategy Maintain a pool of pre-warmed sandboxes for high-volume repositories:

• Sandboxes are ready before users start sessions
• Expire and recreate pool entries as new image builds complete
• Start warming sandbox as soon as user begins typing (predictive warm-up)

Agent Framework Selection

Server-First Architecture Choose an agent framework structured as a server first, with TUI and desktop apps as clients. This enables:

• Multiple custom clients without duplicating agent logic
• Consistent behavior across all interaction surfaces
• Plugin systems for extending functionality
• Event-driven architectures for real-time updates

Code as Source of Truth Select frameworks where the agent can read its own source code to understand behavior. This is underrated in AI development: having the code as source of truth prevents hallucination about the agent's own capabilities.

Plugin System Requirements The framework should support plugins that:

• Listen to tool execution events (e.g., tool.execute.before)
• Block or modify tool calls conditionally
• Inject context or state at runtime

Speed Optimizations

Predictive Warm-Up Start warming the sandbox as soon as a user begins typing their prompt:

• Clone latest changes in parallel with user typing
• Run initial setup before user hits enter
• For fast spin-up, sandbox can be ready before user finishes typing

Parallel File Reading Allow the agent to start reading files immediately, even if sync from latest base branch is not complete:

• In large repositories, incoming prompts rarely modify recently-changed files
• Agent can research immediately without waiting for git sync
• Block file edits (not reads) until synchronization completes

Maximize Build-Time Work Move everything possible to the image build step:

• Full dependency installation
• Database schema setup
• Initial app and test suite runs (populates caches)
• Build-time duration is invisible to users

Self-Spawning Agents

Agent-Spawned Sessions Create tools that allow agents to spawn new sessions: