HybridInference Cloud Agent

Cloud Agent runs coding agents against a user’s repository inside retained sandbox containers. Users work from a web interface, while enrolled hosts run Claude Code, Codex, pi, OpenCode, or Kilo. The control plane coordinates jobs, sessions, and publication to source control. Model access and account identity come from a HybridInference gateway, over HTTP only.

This is the documentation for the software itself: running it locally, operating a deployment, understanding how it works, and contributing to it. The source is at github.com/HarvardMadSys/hybridInference-cloud-agent, under the MIT license; bugs and questions go to its issue tracker.

Where to start

If you want to	Start here
Run the browser, API, gateway fixture, hosts, and sandboxes on one machine	Local Docker stack
Set up a checkout, find the code that owns a change, and run checks	Developer guide
Find the module that owns a responsibility and follow its dependencies	Code structure
Send a change	Contributing
Configure credentials, enroll hosts, qualify Kata, deploy, and migrate	Operations runbook
Look up a configuration name, default, or owning component	Configuration reference
Build release artifacts and deploy them in the required order	Releases
Understand the sandbox trust model before deploying	Security
See which gateway APIs Cloud Agent consumes	Gateway contracts

Scope of this site

These pages document the software, not any one installation of it. How end users work with a particular deployment, which agents and models it offers, and how to get an account there are the operator’s to publish. Dated designs, plans, and acceptance records stay in the repository as engineering history and are linked from here where they explain a decision.

Getting started

• Complete local stack
  • Run
• Developer guide
  • Set up a checkout
  • Find the code that owns a change
  • Keep the dependency boundaries
  • Run the relevant checks
  • Changing an API
  • Packaging and documentation
• Code structure
  • Start with the deployment boundary
  • Follow a control-plane request
  • API schemas are organized by domain
  • Follow a host execution
  • Shared operation profiling
  • Follow a browser action
  • Add a feature without losing the structure
• Contributing
  • The short version
  • Checks before review
  • Continuous integration
  • Contracts

Concepts

• Native conversation recall
  • Context status
  • Native session identity at the shared boundary
  • Other native CLIs
  • Release scope and remaining findings
  • Verification before accepting a deployment
  • Current investigation evidence (2026-09-07)
  • Local verification update (2026-09-08)
• Agent admission policy
  • Permissions and request checks
  • Failure behavior
  • Infrastructure credentials
  • Verify the Gateway contract
  • Rollout
  • Local verification (2026-09-10)
• Minimal Agent identity
  • Tokens and sessions
  • Database identity boundary
  • Upgrade an existing deployment
  • Local verification (2026-09-10)
• The gateway contracts this service depends on
  • What these are, and what they are not
  • Source commits
  • What these do not cover
  • The one document here that is ours
  • Checking them
• Security
  • Reporting a vulnerability
  • What is in scope
  • What a deployment must not assume

Operations

• Cloud agent sandbox — operations
  • Admin Settings
  • Sandbox archive storage
  • Database browser
  • pgAdmin
  • What a job does
  • Who may run a job against which repository
  • Sandbox inventory, resource usage, and controls
  • Reading a task’s recorded events
  • MCP servers
  • Before a job can run for real
  • Running self-hosted
  • Runtime verification
  • Verified
  • Not verified
  • Known gateway findings
  • Model behaviour observed on the first real run
  • What changed when this moved
  • SSH servers
  • Reusable cloud environments
• Environment inventory
  • Settings and bootstrap configuration
  • The one rule
  • Provisioning status
  • Local development tools
  • Control plane (cloud_agent)
  • Host agent (cloud_agent_host)
  • Sandbox isolation (host agent reads, sandbox inherits)
  • Web (apps/frontend/)
  • Set on the HybridInference side — not here
  • Infrastructure (not environment variables)
  • Adding a variable
• Compute resources and the global sandbox location
  • What must remain on stable infrastructure
  • Supported initial deployment
  • Prepare a trusted deployment profile
  • Enable legacy file-backed profiles
  • Day-to-day workflow
  • Recovery and release boundaries
  • Automatic CloudLab node replacement
• Releases
  • What the generator checks, and what it deliberately does not
  • Producing one
  • Starting, not just building
  • Control-plane integration acceptance
  • Registry layout is not part of this contract
  • Where this differs from the design document
  • Deploying a recipe
  • What a downstream deployment still owns
• Deployment failure checks and queue monitoring
  • Drain through both activations
  • Before stopping a serving runner
  • Old process, candidate schema
  • Detection after deployment
  • Recovery boundaries
• Backup and recovery
  • Initial operating policy
  • What belongs in a recovery set
  • Capture a coordinated set
  • Restore and verify before reopening
  • Recover a previous artifact release
• Automatic session archiving after a PR merge
  • Components and integration points
  • Which sessions are archived
  • Archive actions
  • Configuration and rollout
  • Failure handling and recovery
  • Timing and acceptance
• Host runtime settings
• Host execution limits
• Runner lease failures
  • Lease timing and retries
  • Diagnose from positive evidence
  • Reporting and acknowledgement failures
  • When a retained conversation can continue
  • The safe release case: a child never accepted its turn
• Staging end-to-end smoke
  • What a passing run proves
  • 0. Before you start
  • 1. Configure
  • 2. Start the control plane
  • 3. Sign in — the identity flow end to end
  • 4. Enrol the host
  • 5. One job, all the way
  • 6. The parts that only fail later
  • 7. Tear down
  • Log
  • Partial run, 2026-08-04