Documentation

Docs
/
Concepts

Core Concepts

Understanding AgentHub's architecture and terminology

Blueprints

A blueprint is your published agent template. When you deploy an agent from GitHub, you create a blueprint that others can instantiate. Usually one blueprint corresponds to one GitHub repository but you can have multiple blueprints per repository if needed.

Blueprints are the foundational templates in the AgentHub platform - they define what your agent is but not how it runs. Think of them as the "recipe" for your agent that can be used to create multiple running instances.

Key Properties

  • Source Repository - GitHub repo containing agent code
  • Organization Ownership - Each blueprint belongs to an organization and inherits access controls
  • Basic Metadata - Name, description, and summary for discoverability
  • GitHub Integration - Direct linking to repository with support for different branches per build
  • Lifecycle Management - Blueprints use soft deletion (deactivation) - once deleted, they cannot be reactivated

Blueprint Lifecycle

  1. Creation - Published from a GitHub repository via the deployment flow
  2. Active State - Available for creating builds and instances
  3. Soft Deletion - Marked with deactivation_date, hidden from listings but data preserved
  4. No Reactivation - Deleted blueprints cannot be restored (create a new one instead)

Configuration Philosophy

Blueprints themselves store minimal configuration - just metadata for identification and discovery. All deployment configuration (environment variables, ports, resource limits) is handled at the build and instance levels, enabling flexible deployment patterns from the same blueprint source.

Builds

A build represents a specific version of one blueprint. It is a snapshot of your agent code at a point in time, including all dependencies and configurations.

Builds are where the real deployment configuration lives. While blueprints are just templates, builds contain all the technical details needed to run your agent in production.

Build Components

  • Source Code - Snapshot from GitHub at build time with specific branch/commit
  • Dependencies - Locked versions of all packages detected by the containerization process
  • Deployment Configuration - Complete runtime settings including ports, health checks, and working directories
  • Environment Variables - Default values that will be inherited by instances (can be overridden per instance)
  • Container Image - Optimized Docker image generated through LLM-powered analysis

Technical Configuration

Builds store comprehensive deployment settings:

  • HTTP Configuration - Port number (default varies by framework) and health check endpoint path
  • Process Control - Whether the agent supports stdin commands and if it's designed for long-running operation
  • File System - Working directory and Dockerfile path within the repository
  • Branch Targeting - Specific GitHub branch to build from (enables multiple builds per blueprint)
  • Resource Templates - Base configuration that instances will inherit and can customize

Automated Containerization

The build process uses the agent-cloud-dockerizer service to automatically generate optimized Docker configurations:

  1. Repository Analysis - LLM analyzes codebase structure and identifies framework/language
  2. Dependency Detection - Automatically discovers package files and dependency requirements
  3. Entrypoint Discovery - Finds or generates appropriate startup commands and entry points
  4. Dockerfile Generation - Creates optimized multi-stage Docker build with caching
  5. Iterative Refinement - Up to 5 build attempts with error feedback for complex repositories

Build Lifecycle

  • Creation - Triggered via deployment flow or API with GitHub repository details
  • Processing - Containerization service analyzes code and generates Docker configuration
  • Building - Kubernetes builds the container image using generated Dockerfile
  • Ready - Build available for creating instances
  • Soft Deletion - Like blueprints, builds use deactivation_date for removal

Instances

An instance is a running copy of an agent blueprint. Each user who deploys your agent gets their own isolated instance.

Instances are the actual running agents that users interact with. They represent live, deployed applications with dedicated resources, URLs, and persistent state.

Instance Characteristics

  • Isolated Environment - Dedicated Kubernetes container for each user
  • Unique URL - https://[instance-id].useagenthub.com - globally unique and shareable
  • Persistent State - Continues running until explicitly stopped by user or system
  • Resource Allocation - Independent CPU/memory per instance with configurable limits
  • User Ownership - Each instance belongs to a specific user_id with optional organization association

Instances are designed to be single-user but can be shared across multiple users if needed through URL sharing.

Instance Status Lifecycle

Instances progress through a detailed status lifecycle:

  • CREATING - Initial provisioning and Kubernetes deployment setup
  • DNS_PENDING - URL routing configuration in progress
  • READY_TO_COLD_START - Container deployed but not yet started
  • RUNNING - Active and processing requests
  • READY_TO_RECEIVE_REQUESTS - Fully operational and ready for traffic
  • ERROR - Failed to start or encountered runtime errors
  • STOPPED - Manually stopped by user (can be restarted)
  • DELETED - Permanently removed with resources cleaned up
  • NOT_FOUND - Instance reference exists but container not found in cluster
  • UNKNOWN - Status cannot be determined (fallback state)

Resource Management

Each instance has dedicated resource allocation:

  • CPU Allocation - Base CPU units assigned (e.g., "500m" = 0.5 CPU cores)
  • Memory Allocation - Base memory assigned (e.g., "512Mi")
  • CPU Limits - Maximum CPU the instance can use
  • Memory Limits - Maximum memory before container restart
  • Storage - Persistent disk storage for stateful applications
  • Network - Isolated networking with ingress routing

Environment Customization

Instances can override build-level defaults:

  • Environment Variables - Instance-specific values override build and blueprint defaults
  • Runtime Configuration - Custom settings per deployment
  • User Context - Access to user identity and organization information
  • API Keys - Automatic LLM provider API key injection for seamless model access

Command Interface

For agents that support it:

  • Stdin Commands - Send commands directly to running instance
  • Interactive Sessions - Real-time communication with agent process
  • Output Streaming - Live logs and response streaming
  • Process Control - Restart, stop, and manage agent lifecycle

Organizations

Organizations enable team collaboration and resource management. They provide the foundational structure for multi-user access and resource ownership in the AgentHub platform.

Organization Structure

Organizations follow a simple but effective model:

  • Owner-based Leadership - Each organization has a single owner_id who created it
  • Member Management - Additional users can be added through the organizations_users relationship
  • Resource Ownership - All blueprints belong to an organization, instances optionally do
  • Billing Scope - Usage and costs are tracked at the organizational level

Organization Features

  • Blueprint Ownership - All blueprints must belong to an organization
  • Collaborative Development - Team members can work together on agent templates
  • Instance Association - Instances can optionally be associated with an organization for billing/management
  • Access Control - Organization membership determines blueprint and resource access
  • Unified Billing - All usage within an organization is consolidated for cost tracking

Membership Model

Organizations use a straightforward membership approach:

  • Owner - The user who created the organization (owner_id field)
  • Members - Additional users added via organizations_users junction table
  • Automatic Membership - Users can have multiple organization associations
  • Simple Permissions - Access is based on membership rather than complex role hierarchies

Resource Hierarchy

Organization
├── Blueprints (required association)
│   └── Builds (inherit from blueprint)
│       └── Instances (optional org association)
└── API Keys (organization-scoped)

Multi-Organization Support

Users can belong to multiple organizations:

  • Default Organization - Used when org_id not specified in requests
  • Context Switching - Users can work within different organizational contexts
  • Resource Isolation - Resources are partitioned by organization boundaries
  • Billing Separation - Each organization tracks usage independently

Deployment Flow

The AgentHub platform supports flexible deployment patterns through the unified host agent endpoint, enabling one-click deployment from GitHub repositories to running instances.

Unified Deployment Endpoint

The /host-agent API endpoint provides a streamlined deployment experience:

{
  "github_repo": "https://github.com/user/agent-repo",
  "github_branch": "main",
  "organization_id": "optional-for-multi-org-users",
  "name": "My Agent",
  "create_agent": true,
  "create_build": true, 
  "create_instance": true,
  "env_vars": {
    "API_KEY": "override-value"
  }
}

Deployment Options

Full Stack Deployment (most common):

  • Creates blueprint → build → instance in one operation
  • Immediate deployment from GitHub repository
  • Default environment variables from dockerizer analysis

Selective Creation:

  • create_agent: false - Use existing blueprint
  • create_build: false - Use existing build
  • create_instance: false - Just prepare blueprint/build for later

Environment Variable Priority:

  1. AgentHostRequest.env_vars (highest priority)
  2. Build-level environment variables
  3. Dockerizer-detected variables (lowest priority)

Technical Architecture

Component Integration:

GitHub Repository
       ↓
[Agent Hosting API] ← User Request
       ↓
[Agent Cloud Dockerizer] ← Repository Analysis
       ↓ (Dockerfile + Config)
[Kubernetes Cluster] ← Container Build
       ↓
[Running Instance] ← Unique URL

Data Flow:

  1. Repository Ingestion - GitHub repo URL and branch specification
  2. LLM Analysis - Automated framework detection and containerization
  3. Container Building - Kubernetes builds optimized Docker images
  4. Instance Provisioning - Dedicated resources and URL allocation
  5. Status Tracking - Real-time deployment progress and health monitoring

Monitoring and Analytics

Automatic Observability:

  • Instance Events - Detailed lifecycle tracking with timestamps and metadata
  • Resource Metrics - CPU, memory, and network usage monitoring
  • Cost Attribution - Per-instance, per-build, and per-organization billing
  • Error Tracking - Failed deployments, runtime errors, and system issues
  • Usage Analytics - Access patterns, performance metrics, and user behavior

Developer Dashboard:

  • Real-time build logs and deployment status
  • Instance health and performance metrics
  • Cost breakdown and usage trends
  • Team collaboration and access analytics

Ready to deploy? Check our Getting Started Guide