Troubleshooting

Common issues and solutions.

Installation Issues

Docker Not Running

Error:

Error: Cannot connect to the Docker daemon

Solution: Start Docker Desktop or the Docker daemon:

1# macOS
2open -a Docker
3
4# Linux (systemd)
5sudo systemctl start docker
6
7# Check status
8docker ps

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.

npm Install Fails

Error:

npm ERR! code EACCES

Solution: Don’t use sudo with npm global installs. Fix npm permissions:

1mkdir ~/.npm-global
2npm config set prefix '~/.npm-global'
3echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
4source ~/.bashrc
5npm install -g @colony2/shai

Runtime Issues

Path Not Writable

Error:

Error: path does not exist: src/components

Solution: The path must exist before running shai:

1# Check path exists
2ls src/components
3
4# Create if missing
5mkdir -p src/components
6
7# Then run shai
8shai -rw src/components

Config Validation Error

Error:

Error: Failed to load config
Cause: Template variable not found: env.API_KEY

Solution: Set the required environment variable:

1export API_KEY=your-key-here
2shai -rw src

Or remove the reference from config if not needed.

Network Access Blocked

Error:

curl: (6) Could not resolve host: example.com

Solution: Add the domain to your resource set’s HTTP allowlist:

1resources:
2  my-tools:
3    http:
4      - example.com

View active rules inside the sandbox:

1cat /var/log/shai/iptables.out

Image Pull Fails

Error:

Error: Failed to pull image ghcr.io/colony-2/shai-mega:latest

Solutions:

Check network connectivity:
```
1ping github.com
```

Authenticate if using private images:

1echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin

Use a different image:

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

Container Won’t Start

Error:

Error: Container exited with code 1

Debug:

Check Docker logs:

1docker ps -a  # Find container ID
2docker logs <container-id>

Run with verbose:
```
1shai -rw src --verbose
```

Verify image works:

1docker run --rm ghcr.io/colony-2/shai-mega:latest which supervisord

Configuration Issues

Resource Set Not Applied

Problem: Resource set doesn’t seem to work

Debug:

Use verbose mode:
```
1shai -rw src --verbose
```

Check apply rules match your path:

1apply:
2  - path: src  # Matches src/**/*
3    resources: [my-tools]

Verify resource set name is correct (case-sensitive)

Call Not Available

Error:

shai-remote: command not found: my-call

Solutions:

Check call is defined in a resource set that’s applied
Verify call name (case-sensitive)
List available calls:
```
1shai-remote --list
```

Template Expansion Fails

Error:

Template variable not found: vars.TAG

Solution: Provide the variable:

1shai --var TAG=v1.0.0 -rw src

Performance Issues

Slow Startup

Problem: Shai takes a long time to start

Solutions:

Pre-pull the image:

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

Use shai-base instead of shai-mega:

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

Build a custom minimal image

High Memory Usage

Problem: Container uses too much memory

Solutions:

Limit container memory:
```
1docker run --memory=2g ...
```
Use shai-base (lighter image)
Check what’s running:
```
1# Inside sandbox
2htop
```

Disk Space Issues

Problem: Running out of disk space

Solutions:

Clean up old containers:
```
1docker container prune
```
Remove unused images:
```
1docker image prune -a
```
Check Docker disk usage:
```
1docker system df
```

Agent-Specific Issues

Claude Code Sandbox Warning

Warning:

Warning: Running outside of sandbox

Solution: Use the bypass flag since Shai provides sandboxing:

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

Agent Can’t Install Packages

Problem: npm/pip install fails

Solutions:

Add package registry to HTTP allowlist:

1http:
2  - npmjs.org
3  - registry.npmjs.org
4  - pypi.org

Mount package cache:

1mounts:
2  - source: ${{ env.HOME }}/.npm
3    target: /home/${{ conf.TARGET_USER }}/.npm
4    mode: rw

Agent Can’t Access Git

Problem: git clone/push fails

Solutions:

Add git SSH access:

1ports:
2  - host: github.com
3    port: 22

Mount SSH keys:

1mounts:
2  - source: ${{ env.HOME }}/.ssh
3    target: /home/${{ conf.TARGET_USER }}/.ssh
4    mode: ro

Add HTTPS access:
```
1http:
2  - github.com
```

Debugging Techniques

Enable Verbose Mode

1shai -rw src --verbose

Shows:

Bootstrap script
Resource resolution
Network rules
Mount points

Inspect Container

 1# Start sandbox
 2shai -rw src
 3
 4# In another terminal
 5docker ps  # Find container name (shai-*)
 6docker exec -it <container-name> bash
 7
 8# Inside container
 9cat /var/log/shai/iptables.out
10ps aux
11env

Test Network Filtering

 1shai -- bash -c "
 2  # Should work (if in allowlist)
 3  curl -I https://github.com
 4
 5  # Should fail
 6  curl -I https://example.com
 7
 8  # Check DNS
 9  nslookup github.com
10"

Verify Mounts

1shai -rw src --verbose -- mount | grep /src

Getting Help

Check Documentation

Report Issues

GitHub Issues

Include:

Shai version (shai version)
Operating system
Docker version (docker version)
Config file (sanitized)
Full error message
Steps to reproduce

Community Support

GitHub Discussions
Discord (if available)

FAQ

Q: Can I run Docker inside Shai?

A: Yes, but requires privileged mode:

1resources:
2  docker:
3    mounts:
4      - source: /var/run/docker.sock
5        target: /var/run/docker.sock
6        mode: rw
7    options:
8      privileged: true

Q: Can I use Shai on Windows?

A: Yes, via WSL2 with Docker Desktop.

Q: How do I share data between sessions?

A: Mount a host directory:

1mounts:
2  - source: /path/to/shared
3    target: /shared
4    mode: rw

Q: Why is my workspace read-only?

A: This is intentional! Use -rw to grant write access:

1shai -rw src

Q: Can I modify .shai/config.yaml?

A: Not when workspace root is writable (security feature). It’s automatically remounted read-only.