Config Options

Every OpenBoot config — whether created from a preset, a snapshot, or the dashboard — follows the same structure. Here’s what each field does.

Full Example

{
  "name": "frontend-team",
  "description": "Standard setup for our frontend developers",
  "base_preset": "developer",
  "packages": [
    { "name": "node", "type": "formula" },
    { "name": "pnpm", "type": "formula" },
    { "name": "ripgrep", "type": "formula" },
    { "name": "visual-studio-code", "type": "cask" },
    { "name": "arc", "type": "cask" },
    { "name": "typescript", "type": "npm" },
    { "name": "homebrew/cask-fonts", "type": "tap" }
  ],
  "custom_script": "mkdir -p ~/projects\ngit clone git@github.com:yourorg/main-repo.git ~/projects/main-repo",
  "dotfiles_repo": "https://github.com/yourorg/team-dotfiles.git",
  "snapshot": null,
  "alias": "fe",
  "visibility": "unlisted"
}

Fields

name

Display name for the config. Used as the page title and in the dashboard.

• Type: string
• Required: yes
• Example: "frontend-team"

description

Optional description shown on the config page.

• Type: string
• Required: no
• Example: "Standard setup for our frontend developers"

base_preset

Which preset to start from. The preset’s packages are included unless individually removed.

• Type: string
• Options: "minimal", "developer", "full"
• Required: no
• Default: "developer"

packages

The tools and apps to install. Stored as an array of package objects, each with a name and type.

• formula — CLI tools installed via brew install
• cask — GUI apps installed via brew install --cask
• npm — Global npm packages installed via npm install -g
• tap — Third-party Homebrew repositories added via brew tap

Each entry is an object: { "name": "package-name", "type": "formula" | "cask" | "npm" | "tap" }. Names must match Homebrew or npm package names exactly. Taps are added before formulae and casks are installed.

Limits: max 500 packages per config; name max 200 characters (alphanumeric, ., _, -, @, /).

custom_script

Shell commands that run after all packages are installed. Use this for project-specific setup like cloning repos, generating SSH keys, or configuring services.

• Type: string (newline-separated commands)
• Required: no
• Max length: 10,000 characters
• Runs as: bash (errors are logged but don’t stop the install)

mkdir -p ~/projects
git clone git@github.com:yourorg/api.git ~/projects/api
ssh-keygen -t ed25519 -C "dev@yourcompany.com" -f ~/.ssh/id_ed25519 -N ""

dotfiles_repo

Git URL to a dotfiles repository. OpenBoot clones it to ~/.dotfiles and optionally symlinks with GNU Stow.

• Type: string (HTTPS Git URL)
• Required: no
• Max length: 500 characters
• Must: start with https://. ssh:// and git@ URLs are rejected.
• Example: "https://github.com/yourname/dotfiles.git"

See Dotfiles & Shell for setup details.

snapshot

Snapshot data attached to this config (auto-populated when creating from openboot snapshot). Contains the raw scan results — packages, preferences, shell config, git settings, dev tool versions.

• Type: object or null
• Required: no
• Usually: managed automatically, not edited by hand

Each entry in snapshot.macos_prefs[] has the shape { domain, key, value, type?, host? }. host selects the defaults scope: "" (default) writes to the main domain, "currentHost" writes via defaults -currentHost (required for keys under ~/Library/Preferences/ByHost/).

alias

Short URL alias for easy sharing. If set, this alias becomes the primary way to install the config — for example, openboot install my-setup instead of openboot install username/slug. The alias also works as a short URL: openboot.dev/my-setup.

When a user runs openboot install <word>, the CLI checks aliases first before falling back to username/default.

• Type: string
• Required: no
• Length: 2–20 characters (after cleaning)
• Allowed characters: lowercase letters, digits, hyphens. Other characters are stripped automatically.
• Must be: unique across all configs
• Reserved: api, install, dashboard, login, docs, cli-auth, explore

visibility

Controls who can see and install this config.

• Type: string
• Default: "unlisted"
• Options:
  • "public" — listed on your profile, install URL works for everyone
  • "unlisted" — not listed on your profile, but install URL still works if shared
  • "private" — only you can access. Run openboot login first, then openboot install yourname/slug

Export

You can export any config as a JSON file from the dashboard. Click the Export button on a config card to download a .json file containing all config data (name, packages, custom script, dotfiles repo, snapshot, visibility, and alias).

macOS Preferences Whitelist

These are the system settings that OpenBoot can configure. Only these are captured by openboot snapshot and applied during install. In the dashboard, preferences are grouped into collapsible accordion sections by category.

System

Finder

Dock

Screenshots

Trackpad

Keyboard

Mission Control

Menu Bar

Security

Desktop & Stage Manager