Documentation
Configuration Reference

Configuration Reference

Complete reference for .shai/config.yaml configuration file.

Overview

Shai configuration is stored in .shai/config.yaml at your workspace root. This file defines:

  • Which Docker image to use
  • Which optional image platform to target
  • Resource sets (network, mounts, env vars, etc.)
  • Apply rules (which paths get which resources)

Generating a Default Config

You can generate a default config file:

1shai generate

This creates .shai/config.yaml with sensible defaults.

Configuration is optional! If no config file exists, Shai uses embedded defaults that provide:

  • Common package registries (npm, PyPI, etc.)
  • Open-source container registries
  • Basic network allowlist

Config File Location

Shai automatically loads .shai/config.yaml from your workspace root.

Override with:

1shai --config /path/to/custom-config.yaml

Loading Behavior

  1. Check for .shai/config.yaml
  2. If not found, use embedded defaults
  3. If found, load and validate
  4. Fail if config is invalid

Configuration Sections

Schema Reference
Complete field documentation
Template Expansion
Using dynamic variables
Complete Example
Annotated full config

Quick Example 

 1type: shai-sandbox
 2version: 1
 3image: ghcr.io/colony-2/shai-mega
 4# Optional: set when you need a non-default image platform
 5platform: linux/amd64
 6
 7resources:
 8  base-allowlist:
 9    http:
10      - github.com
11      - npmjs.org
12
13  frontend-dev:
14    http:
15      - cdn.jsdelivr.net
16    mounts:
17      - source: ${{ env.HOME }}/.npm
18        target: /home/${{ conf.TARGET_USER }}/.npm
19        mode: rw
20
21apply:
22  - path: ./
23    resources: [base-allowlist]
24
25  - path: frontend
26    resources: [frontend-dev]

Next Steps