Quick Start

Get up and running with Shai in minutes.

Installation

Choose your preferred installation method:

npm

1npm install -g @colony2/shai

Homebrew

1brew install --cask colony-2/tap/shai

Verify Installation

1shai --version

You should see the version number printed to the console.

Your First Sandbox

Let’s start a basic sandbox to understand how Shai works.

1. Navigate to Your Project

1cd ~/projects/my-app

2. Start Shai

1shai

This opens a sandboxed shell with:

Your workspace mounted read-only at /src
Network access restricted to common package registries and APIs
Running as non-root user shai

3. Explore the Sandbox

Inside the sandbox, try these commands:

 1# View your code (read-only)
 2ls /src
 3
 4# Try to create a file (this will fail)
 5echo "test" > /src/file.txt
 6# Output: cannot create /src/file.txt: Read-only file system
 7
 8# Check network restrictions
 9curl https://github.com
10# Works! (GitHub is in the default allowlist)
11
12# Exit the sandbox
13exit

By default, the entire workspace is read-only. This prevents unintended modifications to your code.

Making Directories Writable

To allow modifications to specific directories, use the -rw (or --read-write) flag:

Single Directory

1shai -rw src/components

This mounts src/components as writable while keeping the rest of your workspace read-only.

Multiple Directories

1shai -rw src/components -rw tests/unit

You can specify multiple -rw flags to make multiple directories writable.

Paths must exist! Shai will error if you specify a path that doesn’t exist in your workspace.

Running AI Agents

The real power of Shai comes from running AI agents inside the sandbox.

Launch an Agent After Bootstrap

1shai -rw src/auth -- claude-code --dangerously-bypass-approvals-and-sandbox

What this does:

Creates a sandbox with src/auth writable
After sandbox setup completes, launches claude-code
The agent runs inside the controlled environment

Without a Command

If you don’t specify a command after --, Shai drops you into an interactive shell where you can manually run agents:

1shai -rw src/components
2# Now inside sandbox
3claude-code

Why --dangerously-bypass-approvals-and-sandbox?

Many AI agents have their own sandboxing. When running inside Shai, you can disable the agent’s built-in sandbox since Shai provides superior isolation that is consistent across agents.

Common Workflows

Frontend Development

1shai -rw src -rw public -- claude-code

Backend Development

1shai -rw internal/api -rw tests -- codex

Running Tests

1shai -- npm test

Tests can read your code but won’t modify it.

Inspecting the Sandbox

Want to see what Shai is doing? Use verbose mode:

1shai -rw src/components --verbose

This shows:

Bootstrap script details
Resource decisions (which resource sets are applied)
Network firewall rules
Mount points

Next Steps

Now that you’ve got Shai running, dive deeper:

Core Concepts

Learn about cellular development, resource sets, and apply rules

Configuration

Create a custom .shai/config.yaml for your project

Examples

See real-world configuration examples

Troubleshooting

Docker Not Running

Error: Cannot connect to Docker daemon

Solution: Start Docker Desktop or the Docker daemon.

Permission Denied

Error: permission denied while trying to connect to the Docker daemon socket

Solution: Add your user to the docker group:

1sudo usermod -aG docker $USER

Then log out and back in.

More Help

See the Troubleshooting guide for more common issues and solutions.