Configuration

Project config (`.switchyard.json`)

Create a per-project config file in any directory:

sy init
# or with overrides:
sy init --label myapp --port 3001 --command "pnpm dev"

Schema

.switchyard.json

{
  "label": "myapp",
  "port": 3001,
  "command": "pnpm run dev",
  "env": {
    "NODE_ENV": "development",
    "DEBUG": "true"
  }
}

Field	Type	Description
`label`	string	Process label (defaults to `package.json` name)
`port`	number	Preferred port (auto-resolves conflicts)
`command`	string	Dev command (defaults to detected dev script)
`env`	object	Environment variables merged into the process

When you run sy run in a directory with .switchyard.json, these settings are used automatically.

Global config (`~/.switchyard/config.json`)

Global preferences that apply to all Switchyard operations:

sy config list          # show all with defaults
sy config set colorMode none
sy config get refreshInterval

Key	Type	Default	Description
`portRangeStart`	number	3000	Start of port scan range
`portRangeEnd`	number	9999	End of port scan range
`refreshInterval`	number	2000	Watch mode refresh interval (ms)
`colorMode`	string	auto	Color output: `auto`, `dark`, `light`, `none`
`defaultDetach`	boolean	false	Default `sy run` to background mode
`logRetentionDays`	number	7	Days to retain log files

Monorepo detection

Switchyard automatically detects monorepos and reads their structure. No config needed — it reads everything from package.json.

What gets detected

Source	What
`packageManager` field	pnpm, yarn, npm, or bun (no lock file guessing)
`dependencies` / `devDependencies`	Framework: Next.js, Vite, Nuxt, Remix, Astro, Gatsby, Express, etc.
`pnpm-workspace.yaml` or `workspaces`	Available workspace apps
Script content (`--port`, `PORT=`)	Default ports per app
Compound scripts (`dev:web`, `api:dev`)	Workspace-specific run targets
`turbo.json`, `nx.json`, `lerna.json`	Orchestrator detection

Running workspace apps

# Run by workspace name — checks compound scripts first, then filter
sy run web              # → pnpm run dev:web (if dev:web script exists)
sy run docs             # → pnpm run dev:docs

# From inside an app directory
cd apps/web && sy run   # → pnpm --filter web run dev

# At root with no target — shows all options
sy run
#   Monorepo detected — specify which app to run:
#     sy run <name>
#   Available:
#     Scripts:
#       web → pnpm run dev:web
#       docs → pnpm run dev:docs
#     Workspaces:
#       web (apps/web) → next
#       docs (apps/docs) → next

# See everything Switchyard knows
sy info

Ports are auto-detected from script content. If apps/web/package.json has "dev": "next dev --port 3000", Switchyard uses 3000. Otherwise it falls back to framework defaults (Next.js → 3000, Vite → 5173, Astro → 4321).

Data directory

All Switchyard state lives in ~/.switchyard/:

~/.switchyard/
├── registry.json    # Registered processes (PID, label, port, command)
├── ports.json       # Port reservations
├── groups.json      # Process groups
├── config.json      # Global config
└── logs/            # Process logs (detached mode)
    └── <label>.log

The menubar app reads these same files — CLI and app stay in sync automatically.

Claude Code integration

Switchyard can auto-register dev servers launched via Claude Code hooks. Run sy hook to get the config:

Claude Code settings.json

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "command": "sh -c 'sleep 2 && sy register \"$(basename \"$(pwd)\")\" 2>/dev/null || true'"
      }
    ]
  }
}

This fires after every Bash tool use and auto-labels any new dev server with the project directory name.