AI工作流沙盒

Requirements

A compatible Docker image must include: - supervisord – 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 - Core utilities – bash, coreutils, iproute2, iputils-ping, jq, net-tools, passwd, procps, sed, util-linux

Docker Images

Shai can work with any Docker image that follows Linux standards and has the required system utilities installed. The bootstrap process automatically starts supervisord and loads any additional service configurations defined in /etc/supervisor/conf.d/*.conf, making it easy to extend containers with custom background services.

Quick Start

1. Install shai: 2.

   npm install -g @colony2/shai
   

or

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

   # minimal invocation – read-only workspace sandbox
   shai

   # mark specific directories as writable
   shai -rw app/component1

   # run a command after bootstrap
   shai -rw app/component1 -- codex --dangerously-bypass-approvals-and-sandbox

   # inspect generated bootstrap script and resource decisions
   shai -rw app/component1 src --verbose

   # override the Docker image explicitly
   shai -rw app/component1 --image ghcr.io/example/dev:latest

   # force a specific image platform
   shai -rw app/component1 --platform linux/amd64
   

Example

```yaml

`.shai/config.yaml` Reference

Generating a default config

You can generate a default config file (optional):

shai generate

Shai automatically loads <workspace>/.shai/config.yaml unless --config overrides it. Missing configs fall back to the embedded default config, which primarily enables a permissive HTTP allow-list and open-source registries.

.shai/config.yaml

type: shai-sandbox version: 1 image: ghcr.io/colony-2/shai-mega

Optional: set when you need a non-default image platform

platform: linux/amd64

user and workspace are optional - defaults are user: shai, workspace: /src

resources: base-allowlist: http: [openai.com, api.openai.com] agent-dev: vars: - source: OPENAI_API_KEY mounts: - source: ${{ env.HOME }}/.cache/agents target: /home/${{ conf.TARGET_USER }}/.cache/agents mode: rw calls: - name: refresh-plan description: Refresh cached plans on the host command: ${{ env.REPO_ROOT }}/scripts/refresh-plan.sh ports: - host: github.com port: 22 apply: - path: ./ resources: [base-allowlist] - path: agents resources: [agent-dev] ```

Embedding the Go API

Advanced users can embed Shai inside Go binaries using pkg/shai:

import (
    "context"
    shai "github.com/colony-2/shai/pkg/shai"
)

func runAgent(ctx context.Context, repoRoot string) error {
    cfg, err := shai.LoadSandboxConfig(repoRoot,
        shai.WithReadWritePaths([]string{"agents/cache"}),
        shai.WithResourceSets([]string{"gpu"}),
        shai.WithPlatformOverride("linux/amd64"),
        shai.WithTemplateVars(map[string]string{"BRANCH": "main"}),
    )
    if err != nil {
        return err
    }
    cfg.PostSetupExec = &shai.SandboxExec{
        Command: []string{"python", "-m", "agent"},
        Workdir: "/src/agents",
        UseTTY: false,
    }
    sandbox, err := shai.NewSandbox(cfg)
    if err != nil {
        return err
    }
    defer sandbox.Close()
    return sandbox.Run(ctx)
}

Use the Go API when you need to orchestrate multiple sandboxes, integrate with supervisors, or reuse Shai as the execution backend inside unit/integration tests.