How DockaShell Works

June 6, 2025 · View on GitHub

This document explains DockaShell's architecture, security model, and technical implementation.

Architecture Overview

AI Agent (Claude/GPT/...)
  ↔ DockaShell (MCP Server)
      └─ Docker Engine
          ├─ Container A (Project 1)
          │    └─ Persistent Volume
          ├─ Container B (Project 2)
          │    └─ Persistent Volume
          └─ Container C (Project 3)
               └─ Persistent Volume

Each project gets its own isolated Docker container with a persistent volume for data that survives container restarts.

Container Design

Default Development Image

DockaShell uses a standard development image (dockashell/default-dev:latest) based on Microsoft's DevContainer Python 3.12 base:

  • Python 3.12 with pip and development tools
  • Node.js 20 LTS with npm, yarn, pnpm via corepack
  • Essential CLI tools: ripgrep, jq, git-lfs, build-essential, curl
  • Non-root user: vscode (UID 1000) with sudo access
  • Working directory: /workspace (mounted from host)

Container Lifecycle

  1. Creation: Container created from default image with project-specific configuration
  2. Startup: Container starts with mounted volumes and configured ports
  3. Persistence: Container keeps running between command executions
  4. Restart: Container can be stopped/restarted without losing data
  5. Cleanup: Container can be removed while preserving data volumes

Security Model

DockaShell's security relies on Docker's proven container isolation rather than command filtering or sandboxing.

Isolation Boundaries

  • Process isolation: Container processes separated from host
  • Filesystem isolation: Container filesystem independent of host
  • Network isolation: Controlled network access via Docker networking
  • User isolation: Containers run as non-root user (UID 1000)
  • Resource limits: Memory and CPU constraints via Docker

Execution Controls

  • Command timeouts: All commands automatically terminated after configured limit
  • Audit logging: Every command execution logged with timestamps and exit codes
  • Containers management: Containers can be stopped, restarted, or destroyed
  • Volume persistence: Data persists in Docker volumes even when containers are removed

What's Protected

  • Host filesystem: Container cannot access files outside mounted volumes
  • Host processes: Container processes isolated from host processes
  • Network access: Container network access controlled by Docker
  • System resources: Resource usage limited by Docker constraints

What's Not Protected

  • Container contents: Agents have full control within their container
  • Mounted volumes: Agents can modify any files in mounted project directories
  • Network within limits: Agents can make network requests (if enabled)
  • Resource consumption: Agents can use resources up to configured limits

Trace System

DockaShell tracks all agent activity through structured trace files.

Trace Storage

  • Location: ~/.dockashell/projects/{project}/traces/current.jsonl
  • Format: JSON Lines (one JSON object per line)
  • Session rotation: New session starts after 4+ hours of inactivity
  • Persistence: Traces survive container restarts and DockaShell restarts

Trace Types

// Tool execution
{"id":"tr_123","tool":"bash","trace_type":"execution","command":"npm start","result":{"exitCode":0}}

// Agent reasoning
{"id":"tr_456","tool":"write_trace","trace_type":"observation","type":"agent","text":"Planning React app"}

// User input
{"id":"tr_789","tool":"write_trace","trace_type":"observation","type":"user","text":"Build a todo app"}

Trace Observability

  • Real-time TUI: dockashell logs shows live trace activity
  • Historical queries: read_traces tool lets agents query past activity
  • Searchable: Traces can be filtered by type, time range, or content

MCP Integration

DockaShell implements the Model Context Protocol (MCP) standard for AI tool integration.

Transport

  • Local: STDIO transport for local MCP clients
  • Remote (experimental): HTTP transport with OAuth2 authentication

Tool Categories

  • Project management: list_projects, start_project, stop_project
  • Shell execution: bash with full command line support
  • File operations: write_file, apply_patch with context matching
  • Trace operations: write_trace, read_traces for agent memory

Tool Design Philosophy

DockaShell favors general-purpose tools (like bash) over specialized tools. This lets agents use standard POSIX commands and build their own workflows rather than being limited to predefined operations.

Performance Considerations

Container Reuse

  • Containers stay running between commands to avoid startup overhead
  • Base image is cached and shared across all projects
  • Only project-specific data is unique per container

Resource Management

  • Containers can be stopped when not in use to save resources
  • Resource limits prevent runaway processes
  • Trace files are capped to prevent unlimited growth

Scaling

  • Each project is independent - supports multiple concurrent projects
  • No shared state between projects beyond the base image
  • Can run on any system with Docker support

Configuration

DockaShell uses layered configuration:

  1. Global defaults: System-wide settings in ~/.dockashell/config.json
  2. Project config: Per-project settings in project/config.json
  3. Runtime overrides: Command-line flags and environment variables

Key configuration areas:

  • Container settings: Image, ports, environment variables, resource limits
  • Trace settings: Session timeout, output truncation, storage location
  • Security settings: Network access, volume mounts, execution timeouts

See dockashell-configuration.md for complete configuration reference.