silo.schema.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://raw.githubusercontent.com/leighmcculloch/silo/main/silo.schema.json",
  "title": "Silo Configuration",
  "description": "Configuration file for silo - run AI coding tools in isolated containers",
  "type": "object",
  "properties": {
    "$schema": {
      "type": "string",
      "description": "JSON Schema reference for editor autocompletion and validation"
    },
    "backend": {
      "type": "string",
      "enum": ["docker", "container", "fly", "namespace"],
      "description": "Backend to use for running containers. 'docker' uses Docker, 'container' uses Apple's lightweight VMs, 'fly' uses Fly.io remote machines, 'namespace' uses Namespace devboxes (https://namespace.so/devbox). Default: 'container' if installed, else 'docker'",
      "examples": ["docker", "container", "fly", "namespace"]
    },
    "tool": {
      "type": "string",
      "enum": ["claude", "cline", "codex", "opencode", "paperclipai", "copilot", "vibe", "kilo"],
      "description": "Default tool to run. If not set, an interactive prompt is shown.",
      "examples": ["claude", "cline", "codex", "opencode", "paperclipai", "copilot", "vibe", "kilo"]
    },
    "mounts_ro": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Read-only directories or files to mount into the container. Paths starting with ~ are expanded to home directory.",
      "examples": [["~/.gitconfig", "~/.ssh/known_hosts"]]
    },
    "mounts_rw": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Read-write directories or files to mount into the container. Paths starting with ~ are expanded to home directory.",
      "examples": [["~/.cache/myapp"]]
    },
    "env": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Environment variables. Names without '=' pass through from host, names with '=' set explicitly (e.g., 'FOO=bar').",
      "examples": [["MY_API_KEY", "DEBUG=1"]]
    },
    "pre_run_hooks": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Shell commands to run inside the container before the tool starts. Useful for dynamic setup that depends on the mounted working directory.",
      "examples": [["cd /workspace && npm install"]]
    },
    "post_build_hooks": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Shell commands to run inside the container after building the image. These are baked into the image and cached.",
      "examples": [["apt-get update && apt-get install -y ripgrep", "npm install -g typescript"]]
    },
    "ports": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Host:container port mappings to publish from the container. Format: 'hostPort:containerPort' or just 'containerPort' (maps to same host port).",
      "examples": [["3484:3484", "8080:8080"]]
    },
    "backends": {
      "type": "object",
      "description": "Backend-specific configuration.",
      "properties": {
        "fly": {
          "type": "object",
          "description": "Configuration for the Fly.io backend.",
          "properties": {
            "app": {
              "type": "string",
              "description": "Fly.io app name. Required when using the fly backend. App names are globally unique on Fly.io — create one with 'fly apps create <name>'.",
              "examples": ["my-silo-app"]
            },
            "region": {
              "type": "string",
              "description": "Fly.io region for new machines. Default: 'syd'. See https://fly.io/docs/reference/regions/ for available regions.",
              "examples": ["syd", "sjc", "iad", "lhr"]
            }
          },
          "additionalProperties": false
        },
        "namespace": {
          "type": "object",
          "description": "Configuration for the Namespace devbox backend (https://namespace.so/devbox).",
          "properties": {
            "size": {
              "type": "string",
              "enum": ["s", "m", "l", "xl"],
              "description": "Namespace devbox machine size. Default: 'm'.",
              "examples": ["s", "m", "l", "xl"]
            },
            "site": {
              "type": "string",
              "description": "Namespace site to optimize built images for and run devboxes in. Default: 'sjc1'. Common sites: 'sjc1' (Bay Area), 'iad' (North Virginia), 'ord' (Illinois), 'zrh' (Switzerland).",
              "examples": ["sjc1", "iad", "ord", "zrh"]
            },
            "idle_timeout": {
              "type": "string",
              "enum": ["15m", "30m", "1h", "2h", "4h", "6h", "8h", "12h"],
              "description": "How long the devbox can be idle before it is automatically stopped. Default: '15m'.",
              "examples": ["15m", "30m", "1h", "2h", "4h", "6h", "8h", "12h"]
            },
            "volume_size_gb": {
              "type": "integer",
              "minimum": 1,
              "description": "Override the default persistent volume size, in GiB. When omitted, the devbox default is used.",
              "examples": [50, 100, 300]
            }
          },
          "additionalProperties": false
        }
      },
      "additionalProperties": false
    },
    "tools": {
      "type": "object",
      "description": "Tool-specific configuration. Each key is a tool name (e.g., 'claude', 'cline', 'codex', 'opencode', 'paperclipai', 'copilot', 'vibe', 'kilo').",
      "additionalProperties": {
        "$ref": "#/$defs/toolConfig"
      },
      "examples": [{
        "claude": {
          "env": ["CLAUDE_SPECIFIC_VAR"]
        }
      }]
    },
    "repos": {
      "type": "object",
      "description": "Repository-specific configuration. Each key is a substring to match against git remote URLs (prefix matching). When the current directory is a git repository and any remote URL contains the key as a substring, that configuration is applied. Multiple patterns can match the same repo; they are applied in order of specificity (shortest pattern first), so more specific patterns extend or override less specific ones.",
      "additionalProperties": {
        "$ref": "#/$defs/repoConfig"
      },
      "examples": [{
        "github.com/myorg": {
          "tool": "opencode",
          "env": ["ORG_API_KEY"],
          "post_build_hooks": ["npm install -g @myorg/cli"]
        },
        "github.com/myorg/specific-repo": {
          "tool": "claude",
          "env": ["REPO_SPECIFIC_VAR"],
          "pre_run_hooks": ["echo 'Setting up specific-repo'"]
        }
      }]
    }
  },
  "$defs": {
    "toolConfig": {
      "type": "object",
      "description": "Configuration specific to a single tool. These settings are merged with global config when running that tool.",
      "properties": {
        "mounts_ro": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Read-only directories or files to mount for this tool only."
        },
        "mounts_rw": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Read-write directories or files to mount for this tool only."
        },
        "env": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Environment variables for this tool only. Same format as global env."
        },
        "pre_run_hooks": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Shell commands to run inside the container before this tool starts."
        },
        "post_build_hooks": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Shell commands to run in the Dockerfile for this tool's build stage."
        },
        "ports": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Host:container port mappings to publish for this tool."
        }
      },
      "additionalProperties": false
    },
    "repoConfig": {
      "type": "object",
      "description": "Configuration specific to a git repository. Applied when any git remote URL contains the key as a substring. When multiple patterns match, configs are merged in order of specificity (shortest pattern first).",
      "properties": {
        "tool": {
          "type": "string",
          "description": "Tool to use for this repository (e.g., 'claude', 'cline', 'opencode', 'paperclipai', 'copilot', 'kilo')."
        },
        "mounts_ro": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Read-only directories or files to mount for this repository."
        },
        "mounts_rw": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Read-write directories or files to mount for this repository."
        },
        "env": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Environment variables for this repository. Same format as global env."
        },
        "pre_run_hooks": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Shell commands to run inside the container before the tool starts."
        },
        "post_build_hooks": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Shell commands to run in the Dockerfile."
        },
        "ports": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Host:container port mappings to publish for this repository."
        }
      },
      "additionalProperties": false
    }
  },
  "additionalProperties": false
}