Documentation
Docker Images
shai-base

shai-base

Minimal Debian-based image containing only the essential packages required for Shai sandboxing.

Overview

shai-base provides the bare minimum infrastructure needed for Shai to function:

  • Sandboxing utilities (supervisord, dnsmasq, iptables, tinyproxy)
  • Core system utilities
  • No language runtimes
  • No development tools

Registry: ghcr.io/colony-2/shai-base:latest

Base: debian:bookworm-slim

Size: ~200 MB

What’s Included

Sandboxing Tools

  • supervisor - Process supervisor for managing background services
  • dnsmasq - DNS server for domain filtering
  • iptables - Firewall for network egress control
  • tinyproxy - HTTP/HTTPS proxy for allow-listed traffic

System Utilities

  • bash - Shell
  • ca-certificates - SSL/TLS certificates
  • coreutils - Core Unix utilities (ls, cp, mv, etc.)
  • curl - HTTP client
  • iproute2 - Network configuration (ip command)
  • iputils-ping - Network testing (ping)
  • jq - JSON processor
  • net-tools - Network utilities (netstat, etc.)
  • passwd - User management
  • procps - Process utilities (ps, top, etc.)
  • sed - Stream editor
  • util-linux - System utilities (mount, etc.)

Use Cases

1. Building Custom Images

shai-base is ideal as a foundation for custom development images:

 1FROM ghcr.io/colony-2/shai-base:latest
 2
 3# Install Python
 4RUN apt-get update && apt-get install -y \
 5    python3 \
 6    python3-pip \
 7    && rm -rf /var/lib/apt/lists/*
 8
 9# Install Python tools
10RUN pip3 install --no-cache-dir \
11    black \
12    mypy \
13    pytest

2. Fast CI/CD

Smaller images mean faster pulls and startup:

1# .github/workflows/test.yaml
2jobs:
3  test:
4    runs-on: ubuntu-latest
5    steps:
6      - uses: actions/checkout@v4
7      - run: |
8          shai --image ghcr.io/colony-2/shai-base:latest -- ./run-tests.sh

3. Minimal Overhead

When you need the lightest possible container:

1# .shai/config.yaml
2image: ghcr.io/colony-2/shai-base:latest

4. Security-Sensitive Environments

Fewer packages mean smaller attack surface:

  • No unnecessary tools installed
  • Minimal dependencies
  • Easier to audit

Configuration Example 

 1# .shai/config.yaml
 2type: shai-sandbox
 3version: 1
 4
 5# Use shai-base
 6image: ghcr.io/colony-2/shai-base:latest
 7
 8resources:
 9  base-allowlist:
10    http:
11      - github.com
12      - npmjs.org
13
14apply:
15  - path: ./
16    resources: [base-allowlist]

Extending shai-base

Example: Python Development 

 1FROM ghcr.io/colony-2/shai-base:latest
 2
 3# Install Python and common tools
 4RUN apt-get update && apt-get install -y --no-install-recommends \
 5    python3.11 \
 6    python3-pip \
 7    python3-venv \
 8    git \
 9    && rm -rf /var/lib/apt/lists/*
10
11# Install Python development tools
12RUN pip3 install --no-cache-dir \
13    black \
14    ruff \
15    mypy \
16    pytest \
17    ipython
18
19WORKDIR /src

Example: Node.js Development 

 1FROM ghcr.io/colony-2/shai-base:latest
 2
 3# Install Node.js 20
 4RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - && \
 5    apt-get install -y --no-install-recommends nodejs && \
 6    rm -rf /var/lib/apt/lists/*
 7
 8# Install global npm tools
 9RUN npm install -g \
10    typescript \
11    eslint \
12    prettier
13
14WORKDIR /src

Example: Go Development 

 1FROM ghcr.io/colony-2/shai-base:latest
 2
 3# Install Go 1.21
 4RUN curl -fsSL https://go.dev/dl/go1.21.6.linux-amd64.tar.gz | \
 5    tar -C /usr/local -xzf -
 6
 7ENV PATH="/usr/local/go/bin:${PATH}"
 8ENV GOPATH="/home/shai/go"
 9
10# Install Go tools
11RUN go install golang.org/x/tools/gopls@latest && \
12    go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
13
14WORKDIR /src

Building Custom Images

Basic Build 

 1# Create Dockerfile
 2cat > Dockerfile.custom <<'EOF'
 3FROM ghcr.io/colony-2/shai-base:latest
 4RUN apt-get update && apt-get install -y python3
 5EOF
 6
 7# Build
 8docker build -f Dockerfile.custom -t my-shai-image:latest .
 9
10# Use with Shai
11shai --image my-shai-image:latest -rw src

Multi-Stage Build 

 1FROM ghcr.io/colony-2/shai-base:latest as builder
 2
 3# Build dependencies
 4RUN apt-get update && apt-get install -y build-essential
 5# ... build steps ...
 6
 7FROM ghcr.io/colony-2/shai-base:latest
 8
 9# Copy built artifacts
10COPY --from=builder /build/output /usr/local/bin/
11
12WORKDIR /src

Limitations

What’s NOT Included

  • Language runtimes (Go, Rust, Node, Python, Java)
  • Development tools (git, vim, etc.)
  • AI CLI tools (claude-code, codex, etc.)
  • Build tools (make, gcc, etc.)
  • Package managers beyond system apt

When shai-base Isn’t Enough

If you need:

Performance

Startup Time

  • Cold start (first pull): ~30 seconds
  • Warm start (cached): ~1 second

Resource Usage

  • Disk: ~200 MB
  • Memory: ~50 MB (sandboxing overhead only)
  • CPU: Minimal overhead

Maintenance

Updating

Pull the latest version:

1docker pull ghcr.io/colony-2/shai-base:latest

Versioning

Tags available:

  • latest - Latest stable release (recommended)
  • v1.0.0 - Specific version (when pinning is needed)

Troubleshooting

Missing Tools

Problem: Tool not found in shai-base

Solution: Extend the image or use shai-mega

1FROM ghcr.io/colony-2/shai-base:latest
2RUN apt-get update && apt-get install -y <your-tool>

Slow Builds

Problem: Building custom image is slow

Solution: Use BuildKit and layer caching

1DOCKER_BUILDKIT=1 docker build --cache-from ghcr.io/colony-2/shai-base:latest ...

Best Practices

✅ Do

  • Use as a base for custom images
  • Keep custom images minimal
  • Cache apt packages properly
  • Document required tools in Dockerfile
  • Version your custom images

❌ Don’t

  • Install everything into shai-base manually
  • Skip cleanup steps (rm -rf /var/lib/apt/lists/*)
  • Forget to update package lists before install
  • Use latest tag in production (pin versions instead)

Next Steps

shai-mega