Skip to main content

Agent Docker Developer Guide

Agent Docker Developer Guide

Separation of Duties: See Separation of Duties - agent-docker is responsible for Docker orchestration and Vast.ai Docker operations. It does NOT own agent manifests, execution, or OSSA spec.

Vast.ai Integration: See BULLETPROOF_VASTAI_PLAN.md - agent-docker provides complete Docker orchestration service for Vast.ai worker images with Tailscale + Cloudflared integration.

Overview

Package: @bluefly/agent-docker Version: 0.1.0 License: MIT

AI-powered Docker container orchestration and management platform with OSSA v0.1.9 compliance. Provides intelligent container lifecycle management, image operations, and multi-registry support.

Key Features

  • Container Lifecycle Management: Create, start, stop, restart, remove containers
  • Image Management: Build, pull, push, analyze Docker images
  • Network Orchestration: Container network management
  • Volume Management: Persistent storage handling
  • Docker Compose Support: Multi-container application deployment
  • Multi-Registry Integration: Docker Hub, ECR, Harbor, custom registries
  • AI-Powered Features: Intelligent orchestration, predictive scaling, security analysis
  • OSSA v0.1.9 Compliance: Full agent architecture with 11 specialized agents

Installation

npm install @bluefly/agent-docker

# Or globally for CLI
npm install -g @bluefly/agent-docker

Quick Start

CLI Usage

# List containers
agent-docker container list

# Create and start container
agent-docker container create nginx --name web-server -p 8080:80

# Build image
agent-docker image build -t my-app:latest .

# Deploy Compose stack
agent-docker compose deploy -f docker-compose.yml my-stack

# Check system health
agent-docker health

API Usage

import { DockerClient } from '@bluefly/agent-docker';

const client = new DockerClient({
  baseUrl: 'http://localhost:3000',
  apiKey: 'your-api-key'
});

// List containers
const containers = await client.listContainers({ all: true });

// Create container
const result = await client.createContainer({
  name: 'my-app',
  image: 'nginx:latest',
  ports: { '80/tcp': [{ HostPort: '8080' }] },
  environment: ['NODE_ENV=production']
});

// Start container
await client.startContainer(result.id);

API Reference

Container Operations

[object Object]

Create a new container.

Parameters:

  • name (string): Container name
  • image (string): Image to use
  • ports (object): Port mappings
  • environment (string[]): Environment variables
  • volumes (object): Volume mounts
  • command (string[]): Override default command

Returns: Promise<{id: string, warnings: string[]}>

[object Object]

Start a container.

[object Object]

Stop a container gracefully.

[object Object]

Remove a container.

Image Operations

[object Object]

Build Docker image from Dockerfile.

await client.buildImage({
  context: '/path/to/build/context',
  tag: 'my-app:latest',
  dockerfile: 'Dockerfile',
  buildArgs: {
    NODE_VERSION: '20'
  }
});

[object Object]

Pull image from registry.

[object Object]

Push image to registry.

Network Operations

[object Object]

Create Docker network.

await client.createNetwork({
  name: 'app-network',
  driver: 'bridge',
  ipam: {
    config: [{ subnet: '172.20.0.0/16' }]
  }
});

Volume Operations

[object Object]

Create Docker volume.

await client.createVolume({
  name: 'app-data',
  driver: 'local',
  driverOpts: {
    type: 'nfs',
    device: ':/path/to/dir'
  }
});

Configuration

Environment Variables

# API Server
NODE_ENV=production
API_PORT=3000
DOCKER_SOCKET_PATH=/var/run/docker.sock

# Database
POSTGRES_URL=postgresql://user:pass@localhost:5432/agent_docker
REDIS_URL=redis://localhost:6379

# Authentication
JWT_SECRET=your-jwt-secret
API_KEY=your-api-key

# Monitoring
PROMETHEUS_PORT=9090
GRAFANA_PORT=3002

OSSA Configuration

ossa.config.yaml:

ossa:
  version: '0.1.9'
  compliance_level: 'gold'
  namespace: 'agent-docker'
  agents:
    base_path: '.agents'
    auto_discover: true
  docker:
    socket: '/var/run/docker.sock'
    registries: [docker.io, ecr, harbor]

Examples

Multi-Container Application

// Deploy full stack
await client.composeUp({
  projectName: 'my-stack',
  services: {
    web: {
      image: 'nginx:latest',
      ports: ['80:80'],
      depends_on: ['api']
    },
    api: {
      build: './api',
      environment: ['DATABASE_URL=postgresql://db:5432/app'],
      depends_on: ['db']
    },
    db: {
      image: 'postgres:15',
      volumes: ['db-data:/var/lib/postgresql/data']
    }
  },
  volumes: {
    'db-data': {}
  }
});

Security Scanning

// Scan image for vulnerabilities
const scan = await client.scanImage('my-app:latest');

console.log('Vulnerabilities:', scan.vulnerabilities);
console.log('Risk Level:', scan.riskLevel);
console.log('Recommendations:', scan.recommendations);

Kubernetes Generation

# Generate Kubernetes manifests from Docker Compose
agent-docker k8s generate --project ./infrastructure

# Validate manifests
agent-docker k8s validate --manifest-dir ./infrastructure/generated

Agent Architecture

Agent Docker includes 11 specialized OSSA agents:

Orchestrators

  • Container Orchestrator: Manages container lifecycles
  • Compose Orchestrator: Handles multi-container deployments

Workers

  • Image Builder: Builds and optimizes Docker images
  • Container Manager: Executes container operations
  • Registry Integrator: Manages registry operations

Monitors

  • Resource Monitor: Tracks CPU, memory, I/O usage
  • Health Monitor: Container health checks

Critics

  • Security Analyzer: Scans for vulnerabilities
  • Compliance Checker: Validates against standards

Integrators

  • ECR Integrator: AWS Elastic Container Registry
  • Harbor Integrator: Enterprise registry integration

Observability

Metrics

# Prometheus metrics endpoint
curl http://localhost:9090/metrics

# Key metrics:
# - agent_docker_containers_total
# - agent_docker_images_total
# - agent_docker_build_duration_seconds
# - agent_docker_registry_operations_total

Grafana Dashboards

Pre-built dashboards available in infrastructure/grafana/:

  • Container Performance Overview
  • Image Build Metrics
  • Registry Operations
  • Security Scan Results

Testing

# Run tests
npm test

# Integration tests
npm run test:integration

# OSSA validation
ossa validate .agents/

# Agent orchestration test
npm run agents:orchestrate

Deployment

Docker

# Run via Docker Compose
npm run docker:up

Kubernetes

# Deploy
kubectl apply -f infrastructure/kubernetes/

# Check status
kubectl get pods -n agent-docker

Related Packages

Documentation