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
  • 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
 5resources:
 6  base-allowlist:
 7    http:
 8      - github.com
 9      - npmjs.org
10
11  frontend-dev:
12    http:
13      - cdn.jsdelivr.net
14    mounts:
15      - source: ${{ env.HOME }}/.npm
16        target: /home/${{ conf.TARGET_USER }}/.npm
17        mode: rw
18
19apply:
20  - path: ./
21    resources: [base-allowlist]
22
23  - path: frontend
24    resources: [frontend-dev]

Next Steps