shai

Overview

shai is an open-source CLI tool written in Go that sandboxes AI coding agents inside Docker containers with a restrictive-by-default security model. Where most agent sandboxes focus on keeping agents from destroying your home directory (the yolobox approach), shai starts from the opposite premise: agents get the minimum access necessary, and everything else is denied.

The project comes from Colony-2 and embodies a philosophy they call "cellular software development" — the idea that AI agents should get constrained access to individual components of a codebase, not carte blanche to the entire repo. It's a fundamentally different bet: that security-conscious teams will trade some setup friction for granular control over what their agents can read, write, and reach.

Attribute	Value
Maintainer	Colony-2
Created	November 19, 2025
Language	Go
License	MIT
GitHub Stars	~39
Install	npm install -g @colony2/shai or brew install --cask colony-2/tap/shai

---

How It Works

When you run shai from a project directory, it builds or pulls a container image, mounts your source code as read-only, and drops you (or your agent) into a non-root shell inside the container.

The key workflow:

1. Read-only by default — Your project is mounted at /src as a read-only filesystem. The agent can read everything but write nothing.
2. Opt-in write access — Use the -rw flag to grant writable overlays for specific subdirectories (e.g., shai -rw src/components). Only those paths become writable.
3. Apply rules — shai can auto-select resource sets, container images, and platforms based on the target path, so different parts of your monorepo get different security contexts.
4. Agent runs inside — Claude Code, Codex, Gemini CLI, Cline, or OpenHands runs inside the container with whatever permissions you've explicitly granted.

shai ships two container images: shai-base (minimal, fast) and shai-mega (batteries-included with common runtimes and tools pre-installed).

---

Resource Sets

Resource Sets are shai's core abstraction for access control. A Resource Set is a named collection that defines:

• HTTP destinations — Allowlisted URLs the agent can reach (e.g., registry.npmjs.org, api.openai.com)
• Host mounts — Additional directories from the host that get mounted into the container
• IP ports — Which ports the container can bind or connect to
• Environment variables — Which env vars get passed through to the agent
• Remote calls — Allowed outbound API endpoints

Resource Sets are defined in .shai/config.yaml and committed to the repository. This means security policy travels with the code — when a new developer clones the repo, they get the same access constraints as everyone else. No per-developer configuration drift.

The power is in composition: different parts of a codebase can reference different Resource Sets. A frontend component might get access to the npm registry and a CDN, while a backend service gets database credentials and internal API endpoints. Apply rules handle the mapping automatically based on file paths.

---

Security Model

shai's security model is defense-in-depth with multiple layers:

Filesystem Isolation

• Source code mounted read-only at /src
• Writable overlays only for explicitly -rw flagged paths
• Agent cannot modify files outside granted write paths

Network Restriction

• All network traffic is blocked by default
• Only allowlisted HTTP/HTTPS destinations (defined in Resource Sets) can be reached
• No arbitrary outbound connections — prevents data exfiltration to unexpected endpoints

Container Hardening

• Runs as a non-root user inside the container
• Standard Docker/OCI container isolation (namespaces, cgroups)
• No privileged mode, no host network access

Team Configuration

• .shai/config.yaml is version-controlled and shared
• Security policy is code-reviewed alongside application code
• No individual developer can silently weaken constraints

This is meaningfully more restrictive than competitors like yolobox (full sudo, no network filtering) or even yolo-cage (network filtering but permissive filesystem).

---

Strengths

• Principle of least privilege, actually applied — Most agent sandboxes protect against catastrophic mistakes (rm -rf). shai goes further by constraining what agents can access in normal operation. Read-only defaults with opt-in writes is how production systems work; it's unusual to see it in developer tooling.

• Resource Sets are a genuinely novel abstraction — Context-dependent access control for AI agents is an unsolved problem. shai's approach of named, composable permission bundles that auto-select based on file paths is thoughtful and team-friendly.

• Config-as-code — .shai/config.yaml living in the repo means security policy gets code review, version history, and team consistency. This is the right pattern for enterprise adoption.

• Agent-agnostic — Supporting Claude Code, Codex, Gemini CLI, Cline, and OpenHands means teams aren't locked into one agent. The sandbox is orthogonal to the agent choice.

---

Weaknesses

• Early and small — 39 stars and 4 forks suggest very early traction. The project is ~4 months old with a small community. Bus factor risk is real.

• Setup friction vs. competitors — yolobox is one command. shai requires understanding Resource Sets, configuring .shai/config.yaml, and thinking about which paths need write access. Teams that just want "run my agent safely" may find it over-engineered.

• "Cellular software development" is unproven — The philosophy of giving agents access to individual components rather than whole repos sounds principled, but it's unclear how well this maps to real agent workflows. Many coding agents need broad context to make good decisions.

• Network allowlisting maintenance burden — As projects add dependencies and integrations, keeping HTTP allowlists current becomes ongoing work. A missed allowlist entry means a broken agent session, which is worse UX than permissive defaults.

• Docker dependency — Like most tools in this space, shai requires Docker. No native macOS container support yet (unlike yolobox's Apple Containers support).

---

Bottom Line

shai represents the security-maximalist position in the AI agent sandboxing space. Where yolobox says "let agents go wild in a safe box," shai says "give agents exactly what they need and nothing more." The Resource Sets abstraction and config-as-code approach are genuinely differentiated — if this catches on, it could become the standard for teams that care about supply chain security and agent access control.

The risk is that it's solving a problem most developers don't yet feel. Today, the primary sandbox demand is "don't let Claude delete my files." shai is building for a future where the question is "which files should Claude be allowed to read, and which APIs should it be allowed to call?" That future is probably coming, but shai needs to survive until it arrives.

Worth watching for teams with security-sensitive codebases, monorepos with varied access requirements, or anyone who found yolobox too permissive.