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

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