Docker Containment

Docker-based containment and isolation strategies for Quox services.

Overview

Run potentially dangerous agentic tools (Gemini, Codex, GetShitDone, etc.) in isolated Docker containers. Data flows in, operations execute, results flow out - keeping the core QUOX system safe.

Architecture

                    QUOX Core (Safe Zone)
                           │
                    ┌──────┴──────┐
                    │  Container  │
                    │ Orchestrator│
                    └──────┬──────┘
          ┌────────────────┼────────────────┐
          │                │                │
    ┌─────▼─────┐   ┌─────▼─────┐   ┌─────▼─────┐
    │  Gemini   │   │   Codex   │   │GetShitDone│
    │ Container │   │ Container │   │ Container │
    └───────────┘   └───────────┘   └───────────┘

Container Types

1. Code Execution Container

Purpose: Run untrusted code, scripts, tests
Image: quox/code-runner
Capabilities:
- Execute bash, python, node
- Build/compile projects
- Run tests
Restrictions:
- No network access (default)
- No access to host filesystem (except mounted volumes)
- Resource limits (CPU, memory)
- Read-only root filesystem

2. AI Agent Container

Purpose: Run LLM-powered agents (Gemini, Claude tools)
Image: quox/ai-agent
Capabilities:
- API calls to AI services
- File manipulation in workspace
- Code generation
Restrictions:
- Allowlisted network endpoints only
- No shell access to host
- Workspace-only file access

3. Research Container

Purpose: Web scraping, data gathering
Image: quox/researcher
Capabilities:
- Network access
- Browser automation
- Data extraction
Restrictions:
- Rate limiting
- Domain allowlisting
- Output sanitization

Data Flow Protocol

Input

┌─────────────────────────────────────────┐
│ Task Envelope                           │
├─────────────────────────────────────────┤
│ task_id: "uuid-1234"                    │
│ task_type: "code_review"                │
│ input_files: [                          │
│   { path: "/workspace/main.py", ...}    │
│ ]                                       │
│ parameters: {                           │
│   timeout: 300,                         │
│   model: "gemini-pro"                   │
│ }                                       │
│ callback_url: "/webhook/task-complete"  │
└─────────────────────────────────────────┘

Output

┌─────────────────────────────────────────┐
│ Result Envelope                         │
├─────────────────────────────────────────┤
│ task_id: "uuid-1234"                    │
│ status: "completed" | "failed"          │
│ output_files: [                         │
│   { path: "/workspace/result.json", ...}│
│ ]                                       │
│ logs: "..."                             │
│ metrics: {                              │
│   duration_ms: 4500,                    │
│   tokens_used: 1200                     │
│ }                                       │
└─────────────────────────────────────────┘

Container Specifications

quox/code-runner

dockerfile

FROM python:3.11-slim
RUN apt-get update && apt-get install -y \
    nodejs npm git curl jq && \
    rm -rf /var/lib/apt/lists/*

WORKDIR /workspace
USER nobody

# No network by default
# Mount: /workspace (rw), /input (ro), /output (rw)

quox/ai-agent

dockerfile

FROM python:3.11-slim
RUN pip install anthropic google-generativeai openai

WORKDIR /agent
USER agent

# Network: allowlisted endpoints only
# Mount: /workspace (rw), /config (ro)

Orchestrator API

POST /api/containers/run

json

{
  "image": "quox/code-runner",
  "task": {
    "type": "execute_script",
    "script": "python analyze.py",
    "files": [{"name": "analyze.py", "content": "..."}]
  },
  "limits": {
    "memory": "512m",
    "cpu": 0.5,
    "timeout": 60
  }
}

Response

json

{
  "container_id": "abc123",
  "status": "running",
  "stream_url": "/api/containers/abc123/logs"
}

GET /api/containers/{id}/result

json

{
  "status": "completed",
  "exit_code": 0,
  "stdout": "...",
  "stderr": "",
  "files": [
    {"name": "output.json", "size": 1234}
  ]
}

Security Policies

Network Policy

yaml

apiVersion: networking.k8s.io/v1
kind: NetworkPolicy
metadata:
  name: ai-agent-egress
spec:
  podSelector:
    matchLabels:
      type: ai-agent
  policyTypes:
  - Egress
  egress:
  - to:
    - ipBlock:
        cidr: 0.0.0.0/0
    ports:
    - protocol: TCP
      port: 443
  - to:
    # Only allowed AI APIs
    - ipBlock:
        cidr: 142.250.0.0/16  # Google
    - ipBlock:
        cidr: 104.18.0.0/16   # Anthropic

Resource Policy

yaml

resources:
  limits:
    memory: "1Gi"
    cpu: "1"
  requests:
    memory: "256Mi"
    cpu: "0.25"

Volume Policy

Input: Read-only, task-specific files only
Output: Write-only, size-limited
Workspace: Ephemeral, destroyed after task

Implementation Phases

Phase 1: Basic Containment

Create base Docker images
Implement container orchestrator service
Add task queue with Redis
Basic input/output file handling

Phase 2: Security Hardening

Network policies per container type
Resource limits and monitoring
Output sanitization
Container signing/verification

Phase 3: Agent Integration

Integrate Gemini agent container
Integrate Codex container
Add streaming logs support
Implement approval gates for outputs

Phase 4: Advanced Features

Persistent workspaces for projects
Container caching for faster starts
Multi-container workflows
Result verification with cross-checking

Example Workflows

Code Review with Gemini

1. User: "Review this PR"
2. QUOX extracts PR files
3. Orchestrator starts quox/ai-agent
4. Container runs Gemini review
5. Results validated by core
6. Response shown to user

Script Execution with Codex

1. User: "Generate and run a disk report script"
2. QUOX routes to Codex
3. quox/ai-agent generates script
4. Script transferred to quox/code-runner
5. code-runner executes in isolation
6. Output sanitized and returned

Configuration

docker-compose.yml addition

yaml

services:
  container-orchestrator:
    build: ./services/orchestrator
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - ./workspaces:/workspaces
    environment:
      - REDIS_URL=redis://redis:6379
      - MAX_CONCURRENT=5
    depends_on:
      - redis

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

Orchestrator config

json

{
  "images": {
    "code-runner": {
      "image": "quox/code-runner:latest",
      "default_limits": {
        "memory": "512m",
        "cpu": 0.5,
        "timeout": 60
      },
      "network": "none"
    },
    "ai-agent": {
      "image": "quox/ai-agent:latest",
      "default_limits": {
        "memory": "1g",
        "cpu": 1,
        "timeout": 300
      },
      "network": "ai-apis"
    }
  },
  "workspace_path": "/workspaces",
  "max_concurrent": 5,
  "cleanup_interval": 300
}

Notes

All container outputs are logged to audit trail
Containers auto-terminate on timeout
Failed containers trigger alerts
Container images are rebuilt weekly with security patches
Consider using gVisor for enhanced isolation