Comparison

How Shai compares to other tools and approaches.

Shai vs Devcontainers

Key Differences

When to Use Devcontainers

• Long-lived development environments
• Complex IDE integration (VS Code)
• Team standardization on development tools
• Rich feature ecosystem

When to Use Shai

• Running AI agents safely
• Cellular development workflows
• Ephemeral, task-specific environments
• Fine-grained network/filesystem controls
• Quick iteration cycles

Can They Work Together?

Yes! Use devcontainers for your development environment and Shai for running AI agents:

1# Inside your devcontainer
2shai -rw src -- claude-code

Shai vs Plain Docker

What Shai Adds

When to Use Plain Docker

• Building container images
• Production deployments
• Long-running services
• Maximum control and flexibility

When to Use Shai

• Running AI agents
• Development sandboxing
• Quick prototyping
• Configuration-driven workflows

Shai Uses Docker

Shai is built on top of Docker - it’s not a replacement:

┌─────────────────────┐
│       Shai          │  ← High-level API
├─────────────────────┤
│      Docker         │  ← Container runtime
├─────────────────────┤
│   Linux Kernel      │
└─────────────────────┘

Shai vs Virtual Machines

Comparison

When to Use VMs

• Strong isolation requirements (untrusted code)
• Different operating systems
• Kernel-level testing
• Legacy applications

When to Use Shai

• Fast iteration cycles
• Resource efficiency
• Modern development workflows
• AI agent sandboxing

Shai vs Firecracker/Kata

Lightweight VMs

Firecracker and Kata Containers provide VM-level isolation with container-like speed.

When to Use Firecracker/Kata

• Production multi-tenancy
• Untrusted code execution
• Strong isolation requirements
• Serverless platforms

When to Use Shai

• Development workflows
• AI agent sandboxing
• Quick iteration
• Standard Docker images

Shai vs nix/direnv

Environment Management

When to Use nix/direnv

• Pure development environments
• Reproducible builds
• No container overhead
• Shell-based workflows

When to Use Shai

• AI agent sandboxing
• Network isolation needed
• Filesystem protection required
• Container-based workflows

Summary

Use Shai When

✅ Running AI agents ✅ Need network filtering ✅ Want read-only workspace by default ✅ Cellular development workflows ✅ Quick, ephemeral environments ✅ Fine-grained resource control

Use Other Tools When

• Devcontainers - Long-lived dev environments, IDE integration
• Plain Docker - Building images, production deployments
• VMs - Strong isolation, different OSes
• Firecracker/Kata - Production multi-tenancy
• nix/direnv - Pure, reproducible shell environments

Migration Guides

From Devcontainers

1// .devcontainer/devcontainer.json
2{
3  "image": "mcr.microsoft.com/devcontainers/python:3.11",
4  "features": {
5    "ghcr.io/devcontainers/features/node:1": {}
6  }
7}

Becomes:

 1# .shai/config.yaml
 2type: shai-sandbox
 3version: 1
 4image: ghcr.io/colony-2/shai-mega  # Includes Node + Python
 5
 6resources:
 7  dev-tools:
 8    http:
 9      - npmjs.org
10      - pypi.org
11
12apply:
13  - path: ./
14    resources: [dev-tools]

From Docker Compose

1# docker-compose.yml
2services:
3  app:
4    image: node:20
5    volumes:
6      - .:/workspace
7    environment:
8      - API_KEY=${API_KEY}

Becomes:

 1# .shai/config.yaml
 2type: shai-sandbox
 3version: 1
 4image: ghcr.io/colony-2/shai-mega
 5
 6resources:
 7  app:
 8    vars:
 9      - source: API_KEY
10
11apply:
12  - path: ./
13    resources: [app]

Usage:

1# Instead of: docker-compose run app
2shai -rw . -- npm start

Best Practices

Use the Right Tool

Don’t force Shai where another tool fits better:

• Development environment: Devcontainers
• Production: Docker/Kubernetes
• Build pipelines: Plain Docker
• AI agents: Shai ✅

Combine Tools

Use multiple tools together:

1# Devcontainer for development
2devcontainer up
3
4# Shai for running agents inside devcontainer
5shai -rw src -- claude-code

Learn More

• Core Concepts - Understanding Shai’s design
• Quick Start - Get started with Shai
• Examples - Real-world patterns