Complete Example

  1# ==============================================================================
  2# Shai Configuration File
  3# ==============================================================================
  4
  5# Required: Schema type identifier
  6type: shai-sandbox
  7
  8# Required: Schema version
  9version: 1
 10
 11# Required: Base container image
 12# Use shai-mega for kitchen-sink dev environment
 13# or shai-base for minimal footprint
 14image: ghcr.io/colony-2/shai-mega
 15
 16# Optional: Default user inside container (default: shai)
 17# This user is created if it doesn't exist, with UID/GID matched to host user
 18user: shai
 19
 20# Optional: Workspace path inside container (default: /src)
 21# Most configs should stick with /src
 22workspace: /src
 23
 24# ==============================================================================
 25# Resource Sets
 26# ==============================================================================
 27# Define named collections of resources that can be applied via apply rules
 28
 29resources:
 30  # --------------------------------------------------------------------------
 31  # Base Allowlist
 32  # --------------------------------------------------------------------------
 33  # Common package registries and APIs - applied to all paths
 34  base-allowlist:
 35    http:
 36      - github.com
 37      - npmjs.org
 38      - registry.npmjs.org
 39      - pypi.org
 40      - files.pythonhosted.org
 41      - crates.io
 42      - golang.org
 43      - proxy.golang.org
 44
 45  # --------------------------------------------------------------------------
 46  # Git SSH Access
 47  # --------------------------------------------------------------------------
 48  # SSH access to git servers for cloning/pushing
 49  git-ssh:
 50    ports:
 51      - host: github.com
 52        port: 22
 53      - host: gitlab.com
 54        port: 22
 55
 56  # --------------------------------------------------------------------------
 57  # Frontend Development
 58  # --------------------------------------------------------------------------
 59  # Resources for React/Vue/Svelte development
 60  frontend-dev:
 61    http:
 62      - cdn.jsdelivr.net
 63      - unpkg.com
 64      - fonts.googleapis.com
 65      - fonts.gstatic.com
 66
 67    mounts:
 68      # npm cache (read-write)
 69      - source: ${{ env.HOME }}/.npm
 70        target: /home/${{ conf.TARGET_USER }}/.npm
 71        mode: rw
 72
 73      # playwright browsers (read-write for installs)
 74      - source: ${{ env.HOME }}/.cache/playwright
 75        target: /home/${{ conf.TARGET_USER }}/.cache/playwright
 76        mode: rw
 77
 78  # --------------------------------------------------------------------------
 79  # Backend Development
 80  # --------------------------------------------------------------------------
 81  # Resources for Go/Rust/Node backend services
 82  backend-dev:
 83    http:
 84      - pkg.go.dev
 85      - sum.golang.org
 86
 87    mounts:
 88      # Go module cache
 89      - source: ${{ env.HOME }}/go/pkg/mod
 90        target: /home/${{ conf.TARGET_USER }}/go/pkg/mod
 91        mode: rw
 92
 93      # Cargo registry cache
 94      - source: ${{ env.HOME }}/.cargo/registry
 95        target: /home/${{ conf.TARGET_USER }}/.cargo/registry
 96        mode: rw
 97
 98  # --------------------------------------------------------------------------
 99  # Database Access
100  # --------------------------------------------------------------------------
101  # For services that need database connectivity
102  database-access:
103    vars:
104      # Map database URL from host environment
105      - source: DATABASE_URL
106
107    ports:
108      # PostgreSQL
109      - host: localhost
110        port: 5432
111
112      # Redis
113      - host: localhost
114        port: 6379
115
116  # --------------------------------------------------------------------------
117  # ML/AI Development
118  # --------------------------------------------------------------------------
119  # Resources for machine learning workflows
120  ml-dev:
121    http:
122      - huggingface.co
123      - cdn.huggingface.co
124      - pypi.org
125      - files.pythonhosted.org
126
127    vars:
128      # Hugging Face token for model downloads
129      - source: HUGGINGFACE_TOKEN
130
131    mounts:
132      # Model cache (can be very large)
133      - source: ${{ env.HOME }}/.cache/huggingface
134        target: /home/${{ conf.TARGET_USER }}/.cache/huggingface
135        mode: rw
136
137      # pip cache
138      - source: ${{ env.HOME }}/.cache/pip
139        target: /home/${{ conf.TARGET_USER }}/.cache/pip
140        mode: rw
141
142  # --------------------------------------------------------------------------
143  # Cloud Deployment
144  # --------------------------------------------------------------------------
145  # For Pulumi, Terraform, and cloud CLI tools
146  cloud-deployment:
147    http:
148      - api.pulumi.com
149      - amazonaws.com
150      - s3.amazonaws.com
151      - cloudfront.net
152
153    vars:
154      # AWS credentials
155      - source: AWS_ACCESS_KEY_ID
156      - source: AWS_SECRET_ACCESS_KEY
157      - source: AWS_REGION
158
159      # Pulumi access token
160      - source: PULUMI_ACCESS_TOKEN
161
162    mounts:
163      # AWS config (read-only)
164      - source: ${{ env.HOME }}/.aws
165        target: /home/${{ conf.TARGET_USER }}/.aws
166        mode: ro
167
168    calls:
169      # Remote call to verify deployment
170      - name: verify-deployment
171        description: Verify deployment succeeded
172        command: /usr/local/bin/verify-deployment.sh
173        allowed-args: '^--stack=[\w-]+ --env=(staging|production)$'
174
175  # --------------------------------------------------------------------------
176  # Kubernetes Access
177  # --------------------------------------------------------------------------
178  # For kubectl, helm, and k8s deployments
179  k8s-access:
180    vars:
181      - source: KUBECONFIG
182
183    mounts:
184      # Kubernetes config (read-only to prevent accidental modifications)
185      - source: ${{ env.HOME }}/.kube
186        target: /home/${{ conf.TARGET_USER }}/.kube
187        mode: ro
188
189    http:
190      - kubernetes.default.svc
191
192  # --------------------------------------------------------------------------
193  # Docker-in-Docker
194  # --------------------------------------------------------------------------
195  # For agents that need to build/run Docker containers
196  docker-in-docker:
197    mounts:
198      # Docker socket (allows controlling host Docker)
199      - source: /var/run/docker.sock
200        target: /var/run/docker.sock
201        mode: rw
202
203    root-commands:
204      # Ensure Docker service is running
205      - "systemctl start docker || true"
206
207    options:
208      # Required for Docker-in-Docker
209      privileged: true
210
211  # --------------------------------------------------------------------------
212  # Embedded Development
213  # --------------------------------------------------------------------------
214  # For embedded systems and firmware development
215  embedded-dev:
216    http:
217      - developer.arm.com
218
219    mounts:
220      # USB device access
221      - source: /dev
222        target: /dev
223        mode: rw
224
225    calls:
226      # Flash firmware to connected device
227      - name: flash-device
228        description: Flash compiled firmware to USB device
229        command: /usr/local/bin/flash-firmware.sh
230        allowed-args: '^--device=/dev/ttyUSB[0-9]+ --firmware=/tmp/[\w-]+\.hex$'
231
232    options:
233      # Required for device access
234      privileged: true
235
236# ==============================================================================
237# Apply Rules
238# ==============================================================================
239# Map workspace paths to resource sets
240# Rules are evaluated top-to-bottom; all matching rules are aggregated
241
242apply:
243  # --------------------------------------------------------------------------
244  # Root - Applies to Everything
245  # --------------------------------------------------------------------------
246  - path: ./
247    resources:
248      - base-allowlist
249      - git-ssh
250
251  # --------------------------------------------------------------------------
252  # Frontend Applications
253  # --------------------------------------------------------------------------
254  - path: packages/web-app
255    resources:
256      - frontend-dev
257
258  - path: packages/mobile-app
259    resources:
260      - frontend-dev
261
262  - path: packages/marketing-site
263    resources:
264      - frontend-dev
265
266  # --------------------------------------------------------------------------
267  # Backend Services
268  # --------------------------------------------------------------------------
269  - path: services/api
270    resources:
271      - backend-dev
272      - database-access
273
274  - path: services/auth
275    resources:
276      - backend-dev
277      - database-access
278
279  - path: services/workers
280    resources:
281      - backend-dev
282      - database-access
283
284  # --------------------------------------------------------------------------
285  # Machine Learning
286  # --------------------------------------------------------------------------
287  - path: ml/training
288    resources:
289      - ml-dev
290    # Use GPU-enabled image for training
291    image: ghcr.io/my-org/pytorch-gpu:latest
292
293  - path: ml/inference
294    resources:
295      - ml-dev
296
297  # --------------------------------------------------------------------------
298  # Infrastructure
299  # --------------------------------------------------------------------------
300  - path: infrastructure/staging
301    resources:
302      - cloud-deployment
303      - k8s-access
304    # Use DevOps image with cloud CLI tools
305    image: ghcr.io/my-org/devops:latest
306
307  - path: infrastructure/production
308    resources:
309      - cloud-deployment
310      - k8s-access
311    image: ghcr.io/my-org/devops:latest
312
313  # --------------------------------------------------------------------------
314  # Container Builds
315  # --------------------------------------------------------------------------
316  - path: docker
317    resources:
318      - docker-in-docker
319
320  # --------------------------------------------------------------------------
321  # Embedded Firmware
322  # --------------------------------------------------------------------------
323  - path: firmware
324    resources:
325      - embedded-dev
326    # Use embedded toolchain image
327    image: ghcr.io/my-org/embedded-toolchain:latest

1# Work on web app
2shai -rw packages/web-app
3
4# Automatic resources: base-allowlist, git-ssh, frontend-dev
5# Can access: npm, CDNs, fonts, etc.
6# npm cache is shared with host

1# Work on API service
2shai -rw services/api
3
4# Automatic resources: base-allowlist, git-ssh, backend-dev, database-access
5# Can access: Go modules, databases, etc.
6# Database credentials from environment

1# Train models (uses GPU image)
2shai -rw ml/training
3
4# Automatic resources: base-allowlist, git-ssh, ml-dev
5# Uses: pytorch-gpu:latest image
6# Hugging Face cache shared with host

1# Deploy to staging
2shai -rw infrastructure/staging
3
4# Automatic resources: base-allowlist, git-ssh, cloud-deployment, k8s-access
5# Uses: devops:latest image
6# AWS credentials from environment
7# Can call: verify-deployment remote command

1# Build Docker images
2shai -rw docker
3
4# Automatic resources: base-allowlist, git-ssh, docker-in-docker
5# Has access to host Docker daemon
6# Runs in privileged mode

1# Flash firmware
2shai -rw firmware
3
4# Automatic resources: base-allowlist, git-ssh, embedded-dev
5# Uses: embedded-toolchain:latest image
6# Can call: flash-device remote command
7# Has access to USB devices

1shai -rw services/api --resource-set ml-dev
2# Gets: backend-dev, database-access, AND ml-dev

1shai -rw ml/training --image ghcr.io/my-org/custom:latest

1shai --var ENV=staging --var REGION=us-east-1 -rw infrastructure