guanyang/open-agent-hub / skills/hosted-agents
hosted-agents
VerifiedThis skill should be used when designing hosted or background agent infrastructure: sandboxed execution, remote coding environments, warm pools, session persistence, multiplayer collaboration, self-spawning agents, or Modal-style sandboxes.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 17.3 KB |
| references/infrastructure-patterns.md | markdown | 20.0 KB |
| scripts/sandbox_manager.py | script | 18.5 KB |
scripts/sandbox_manager.py
View on GitHub"""
Sandbox Manager for Hosted Agent Infrastructure.
Use when: building background coding agents that need sandboxed execution
environments with pre-built images, warm pools, and session snapshots.
This module provides composable building blocks for sandbox lifecycle
management. Each class handles one concern (image building, warm pools,
session coordination) and can be used independently or combined via
SandboxManager.
Note: This is pseudocode demonstrating architectural patterns.
Adapt for your specific infrastructure (Modal, Fly.io, etc.).
"""
from dataclasses import dataclass, field
from datetime import datetime, timedelta
from typing import Optional, Callable, Any
from enum import Enum
import asyncio
__all__ = [
"SandboxState",
"UserIdentity",
"SandboxConfig",
"Sandbox",
"RepositoryImage",
"ImageBuilder",
"WarmSandbox",
"WarmPoolManager",
"SandboxManager",
"AgentSession",
]
class SandboxState(Enum):
"""Sandbox lifecycle states."""
CREATING = "creating"
SYNCING = "syncing"
READY = "ready"
EXECUTING = "executing"
SNAPSHOTTING = "snapshotting"
TERMINATED = "terminated"
@dataclass
class UserIdentity:
"""User identity for commit attribution.
Use when: configuring sandbox git identity so commits are
attributed to the prompting user, not the app.
"""
id: str
name: str
email: str
github_token: str
@dataclass
class SandboxConfig:
"""Configuration for sandbox creation.
Use when: defining resource limits and timeouts for a new sandbox
to prevent cost runaway and resource exhaustion.
"""
repo_url: str
base_image: str
memory_mb: int = 4096
cpu_cores: int = 2
disk_gb: int = 10
timeout_hours: int = 4
@dataclass
class Sandbox:
"""Represents a sandboxed execution environment.
Use when: interacting with a running sandbox to execute commands,
read/write files, or take snapshots for session continuity.
"""
id: str
config: SandboxConfig
state: SandboxState
created_at: datetime
snapshot_id: Optional[str] = None
current_user: Optional[UserIdentity] = None
# Event handlers
on_state_change: Optional[Callable[[SandboxState], None]] = None
async def execute_command(self, command: str) -> dict[str, Any]:
"""Execute a command in the sandbox.
Use when: running shell commands (git, build tools, tests)
inside the isolated environment.
Returns:
dict with keys "stdout", "stderr", "exit_code".
"""
# Implementation depends on infrastructure
pass
async def read_file(self, path: str) -> str:
"""Read a file from the sandbox filesystem.
Use when: agent needs to inspect source code or config files.
Safe to call before git sync completes.
"""
pass
async def write_file(self, path: str, content: str) -> None:
"""Write a file to the sandbox filesystem.
Use when: agent needs to modify source code. Block this
until git sync completes to avoid write conflicts.
"""
pass
async def snapshot(self) -> str:
"""Create a snapshot of current filesystem state.
Use when: preserving session state before sandbox termination
so follow-up prompts can restore instantly.
"""
self.state = SandboxState.SNAPSHOTTING
snapshot_id = await self._create_snapshot()
self.snapshot_id = snapshot_id
self.state = SandboxState.READY
return snapshot_id
async def _create_snapshot(self) -> str:
"""Create snapshot (infrastructure-specific)."""
pass
async def restore(self, snapshot_id: str) -> None:
"""Restore sandbox to a previous snapshot."""
pass
async def terminate(self) -> None:
"""Terminate the sandbox."""
self.state = SandboxState.TERMINATED
@dataclass
class RepositoryImage:
"""Pre-built image for a repository.
Use when: checking whether a cached environment image exists
and whether it is recent enough to use.
"""
repo_url: str
image_id: str
commit_sha: str
built_at: datetime
def is_stale(self, max_age: timedelta = timedelta(minutes=30)) -> bool:
"""Check if image is older than max age."""
return datetime.utcnow() - self.built_at > max_age
class ImageBuilder:
"""Builds and manages repository images.
Use when: setting up the periodic image build loop that
pre-bakes development environments for fast sandbox spin-up.
"""
def __init__(self, github_app_token_provider: Callable[[], str]) -> None:
self.token_provider = github_app_token_provider
self.images: dict[str, RepositoryImage] = {}
async def build_image(self, repo_url: str) -> RepositoryImage:
"""Build a new image for a repository.
Use when: the current image is stale or no image exists yet.
Runs clone, dependency install, build, and cache warming.
"""
print(f"Building image for {repo_url}...")
# Get fresh token for clone
token = self.token_provider()
# These operations run in build environment
build_steps: list[str] = [
# Clone repository
f"git clone https://x-access-token:{token}@github.com/{repo_url} /workspace",
# Install dependencies
"cd /workspace && npm install",
# Run build
"cd /workspace && npm run build",
# Warm caches by running once
"cd /workspace && npm run dev &",
"sleep 5", # Let dev server start
"cd /workspace && npm test -- --run || true", # Run tests to warm cache
]
# Execute build steps (infrastructure-specific)
for step in build_steps:
await self._execute_build_step(step)
# Get current commit
commit_sha: str = await self._get_commit_sha()
# Create and store image
image = RepositoryImage(
repo_url=repo_url,
image_id=await self._finalize_image(),
commit_sha=commit_sha,
built_at=datetime.utcnow()
)
self.images[repo_url] = image
return image
def get_latest_image(self, repo_url: str) -> Optional[RepositoryImage]:
"""Get the most recent image for a repository."""
return self.images.get(repo_url)
async def _execute_build_step(self, command: str) -> None:
"""Execute a build step (infrastructure-specific)."""
pass
async def _get_commit_sha(self) -> str:
"""Get current HEAD commit SHA."""
pass
async def _finalize_image(self) -> str:
"""Finalize and store the image, return image ID."""
pass
@dataclass
class WarmSandbox:
"""A pre-warmed sandbox ready for use.
Use when: tracking warm pool inventory and claiming a sandbox
for an incoming user session.
"""
sandbox: Sandbox
repo_url: str
created_at: datetime
image_version: str
is_claimed: bool = False
sync_complete: bool = False
class WarmPoolManager:
"""Manages pools of pre-warmed sandboxes.
Use when: reducing cold start latency by maintaining ready-to-use
sandboxes that are pre-synced to the latest code.
"""
def __init__(
self,
image_builder: ImageBuilder,
target_pool_size: int = 3,
max_age: timedelta = timedelta(minutes=25)
) -> None:
self.image_builder = image_builder
self.target_size = target_pool_size
self.max_age = max_age
self.pools: dict[str, list[WarmSandbox]] = {}
async def get_warm_sandbox(self, repo_url: str) -> Optional[WarmSandbox]:
"""Get a pre-warmed sandbox if available.
Use when: a user submits a prompt and needs a sandbox immediately.
Returns None if no valid warm sandbox is available.
"""
if repo_url not in self.pools:
return None
for warm in self.pools[repo_url]:
if not warm.is_claimed and self._is_valid(warm):
warm.is_claimed = True
return warm
return None
def _is_valid(self, warm: WarmSandbox) -> bool:
"""Check if a warm sandbox is still valid."""
age: timedelta = datetime.utcnow() - warm.created_at
if age > self.max_age:
return False
# Check if image is still current
current = self.image_builder.get_latest_image(warm.repo_url)
if not current or current.image_id != warm.image_version:
return False
return True
async def maintain_pool(self, repo_url: str) -> None:
"""Ensure pool has target number of warm sandboxes.
Use when: called periodically or after an image rebuild to
keep the warm pool populated.
"""
if repo_url not in self.pools:
self.pools[repo_url] = []
# Remove invalid sandboxes
valid: list[WarmSandbox] = [w for w in self.pools[repo_url] if self._is_valid(w)]
self.pools[repo_url] = valid
# Count available (unclaimed) sandboxes
available: int = len([w for w in valid if not w.is_claimed])
needed: int = self.target_size - available
# Create new warm sandboxes
for _ in range(max(0, needed)):
warm = await self._create_warm_sandbox(repo_url)
self.pools[repo_url].append(warm)
async def _create_warm_sandbox(self, repo_url: str) -> WarmSandbox:
"""Create a new warm sandbox."""
image: Optional[RepositoryImage] = self.image_builder.get_latest_image(repo_url)
if not image:
raise ValueError(f"No image available for {repo_url}")
# Create sandbox from image
sandbox: Sandbox = await self._create_sandbox_from_image(image)
warm = WarmSandbox(
sandbox=sandbox,
repo_url=repo_url,
created_at=datetime.utcnow(),
image_version=image.image_id,
sync_complete=False
)
# Start syncing to latest in background
asyncio.create_task(self._sync_to_latest(warm))
return warm
async def _sync_to_latest(self, warm: WarmSandbox) -> None:
"""Sync sandbox to latest commit on base branch."""
await warm.sandbox.execute_command("git fetch origin main")
await warm.sandbox.execute_command("git reset --hard origin/main")
warm.sync_complete = True
async def _create_sandbox_from_image(self, image: RepositoryImage) -> Sandbox:
"""Create a sandbox from an image (infrastructure-specific)."""
pass
class SandboxManager:
"""Main manager for sandbox lifecycle.
Use when: orchestrating the full sandbox lifecycle including
image building, warm pools, and session management. This is the
top-level entry point that composes ImageBuilder and WarmPoolManager.
"""
def __init__(
self,
repositories: list[str],
github_app_token_provider: Callable[[], str],
build_interval: timedelta = timedelta(minutes=30)
) -> None:
self.repositories = repositories
self.image_builder = ImageBuilder(github_app_token_provider)
self.warm_pool = WarmPoolManager(self.image_builder)
self.build_interval = build_interval
self.active_sessions: dict[str, Sandbox] = {}
async def start_build_loop(self) -> None:
"""Start the background image build loop.
Use when: initializing the system. Runs indefinitely, rebuilding
images every build_interval to keep environments fresh.
"""
while True:
for repo in self.repositories:
try:
await self.image_builder.build_image(repo)
await self.warm_pool.maintain_pool(repo)
except Exception as e:
print(f"Failed to build {repo}: {e}")
await asyncio.sleep(self.build_interval.total_seconds())
async def start_session(
self,
repo_url: str,
user: UserIdentity,
snapshot_id: Optional[str] = None
) -> Sandbox:
"""Start a new session for a user.
Use when: a user submits a prompt. Tries warm pool first,
then snapshot restore, then cold start as fallback.
"""
# Try to get from warm pool first
warm: Optional[WarmSandbox] = await self.warm_pool.get_warm_sandbox(repo_url)
if warm:
sandbox = warm.sandbox
# Wait for sync if not complete
if not warm.sync_complete:
await self._wait_for_sync(warm)
elif snapshot_id:
# Restore from previous session snapshot
sandbox = await self._restore_from_snapshot(snapshot_id)
else:
# Cold start from latest image
sandbox = await self._cold_start(repo_url)
# Configure for user
await self._configure_for_user(sandbox, user)
# Track session
session_id: str = f"{user.id}_{datetime.utcnow().isoformat()}"
self.active_sessions[session_id] = sandbox
return sandbox
async def on_user_typing(self, user: UserIdentity, repo_url: str) -> None:
"""Called when user starts typing a prompt.
Use when: implementing predictive warm-up. Starts preparing a
sandbox so it is ready by the time the user submits.
"""
warm: Optional[WarmSandbox] = await self.warm_pool.get_warm_sandbox(repo_url)
if not warm:
# Start warming one now
asyncio.create_task(self.warm_pool.maintain_pool(repo_url))
async def end_session(self, session_id: str) -> Optional[str]:
"""End a session and return snapshot ID for potential follow-up.
Use when: a session completes. Always snapshots before termination
to prevent state loss.
"""
if session_id not in self.active_sessions:
return None
sandbox: Sandbox = self.active_sessions[session_id]
# Create snapshot before terminating
snapshot_id: str = await sandbox.snapshot()
# Terminate sandbox
await sandbox.terminate()
del self.active_sessions[session_id]
return snapshot_id
async def _configure_for_user(
self,
sandbox: Sandbox,
user: UserIdentity
) -> None:
"""Configure sandbox for a specific user."""
sandbox.current_user = user
# Set git identity
await sandbox.execute_command(
f'git config user.name "{user.name}"'
)
await sandbox.execute_command(
f'git config user.email "{user.email}"'
)
async def _wait_for_sync(self, warm: WarmSandbox) -> None:
"""Wait for sync to complete."""
while not warm.sync_complete:
await asyncio.sleep(0.1)
async def _restore_from_snapshot(self, snapshot_id: str) -> Sandbox:
"""Restore a sandbox from a snapshot."""
pass
async def _cold_start(self, repo_url: str) -> Sandbox:
"""Start a sandbox from cold (no warm pool available)."""
pass
class AgentSession:
"""Agent session with file read/write coordination.
Use when: wrapping a Sandbox to enforce the pattern where reads
are allowed before sync completes but writes are blocked until
sync finishes, preventing write conflicts.
"""
def __init__(self, sandbox: Sandbox) -> None:
self.sandbox = sandbox
self.sync_complete: bool = False
self.pending_writes: list[tuple[str, str]] = []
async def read_file(self, path: str) -> str:
"""Read a file -- allowed even before sync completes.
Use when: agent needs to research code immediately. Safe because
in large repos, files being worked on are unlikely to have
changed in the last 30 minutes since image build.
"""
return await self.sandbox.read_file(path)
async def write_file(self, path: str, content: str) -> None:
"""Write a file -- blocks until sync is complete.
Use when: agent needs to modify source code. Queues the write
and waits for git sync to finish to prevent conflicts.
"""
if not self.sync_complete:
# Queue the write
self.pending_writes.append((path, content))
await self._wait_for_sync()
await self.sandbox.write_file(path, content)
def mark_sync_complete(self) -> None:
"""Called when git sync is complete."""
self.sync_complete = True
async def _wait_for_sync(self) -> None:
"""Wait for sync to complete, then flush pending writes."""
while not self.sync_complete:
await asyncio.sleep(0.1)
# Flush pending writes
for path, content in self.pending_writes:
await self.sandbox.write_file(path, content)
self.pending_writes.clear()
if __name__ == "__main__":
async def _demo() -> None:
"""Demonstrate sandbox manager usage end-to-end."""
def get_github_token() -> str:
"""Get GitHub App installation token."""
# Implementation: call GitHub API to get installation token
return "ghs_xxxx"
# Initialize manager with target repositories
manager = SandboxManager(
repositories=[
"myorg/frontend",
"myorg/backend",
"myorg/shared-libs"
],
github_app_token_provider=get_github_token
)
# Start background build loop
asyncio.create_task(manager.start_build_loop())
# Simulate user session
user = UserIdentity(
id="user123",
name="Alice Developer",
email="alice@example.com",
github_token="gho_user_token"
)
# User starts typing -- predictively warm a sandbox
await manager.on_user_typing(user, "myorg/frontend")
# User submits prompt -- get sandbox
sandbox: Sandbox = await manager.start_session("myorg/frontend", user)
# Create session wrapper for read/write coordination
session = AgentSession(sandbox)
# Agent can read immediately (before sync completes)
readme: str = await session.read_file("/workspace/README.md")
# Agent work happens here...
# End session and get snapshot for follow-up
# Find the session_id that was generated during start_session
active_ids = list(manager.active_sessions.keys())
if active_ids:
session_id = active_ids[0]
snapshot_id: Optional[str] = await manager.end_session(session_id)
print(f"Session ended, snapshot: {snapshot_id}")
else:
print("No active session found")
asyncio.run(_demo())
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |