View as .md

squadron engage

Name: Squadron
Author: Squadron

Start Squadron as a long-running background service. By default, Squadron launches the local command center web UI. Pass --headless to run without a UI, or declare a command_center block in your config to connect to a remote one instead.

Usage


squadron engage [flags]

Run engage from the root of your Squadron project directory. All runtime state lives in a .squadron/ folder created next to your HCL files, so the directory you’re in determines which project the daemon belongs to.

Important: squadron disengage must be run from the same directory you engaged from — it finds the running daemon via <project>/.squadron/engage.pid. If you’re somewhere else, either cd back or pass -c /path/to/project.

Project State (`.squadron/`)

The first run creates .squadron/ in the current directory. Everything Squadron tracks for this project lives there:

Path	Purpose
`vars.vault`	Encrypted variable store (API keys, secrets)
`vault.key`	Vault passphrase (file vault provider, `0600` perms)
`store.db`	SQLite mission/task/session state for resume
`plugins/<platform>/<name>/<version>/`	Cached plugin binaries
`mcp/<platform>/<name>/<version>/`	Cached MCP server binaries
`command-center/<platform>/<version>/`	Cached command center binary (when the local UI is launched)
`engage.pid`	PID of the running daemon
`engage.log`	Daemon stdout/stderr
`engage.ready`	Ready signal file (parent ↔ child IPC during fork)

Multiple projects can run simultaneously on the same host — each gets its own .squadron/. Add .squadron/ to your .gitignore.

Flags

Flag	Description
`-c, --config`	Path to config directory (default: `.`)
`-r, --reload`	Reload the config of an already-running Squadron (see Reloading configuration)
`--headless`	Skip launching the local command center UI
`--cc-port`	Port for the local command center (default: `8080`)
`--foreground`	Run in the terminal instead of forking to background
`--init`	Auto-initialize Squadron if not already initialized

A command_center block in your config takes precedence — Squadron connects to the remote command center and skips the local UI. Passing --headless alongside a command_center block is an error.

What it does

Validates the directory — refuses to run inside ~, /, /tmp, etc., and errors on nested .squadron/ projects.
Runs the quickstart wizard if there’s no .hcl config and no .squadron/ directory (interactive terminals only).
Auto-initializes the vault in all other first-run cases.
Forks to the background unless --foreground is set.
Launches the command center UI unless --headless is set or a command_center block is declared.
Installs a system service (launchd on macOS, systemd user unit on Linux) so Squadron starts automatically on boot.

Each Squadron project gets its own PID file in <project>/.squadron/engage.pid, so multiple projects can run simultaneously on the same host.

Examples

Default


squadron engage

Runs Squadron in the background, launches the local command center on http://localhost:8080, and opens your browser.

Headless


squadron engage --headless

Runs in the background with no UI. Use this when missions run purely via schedules, webhooks, or remote command center.

Foreground mode


squadron engage --foreground

Keeps the process attached to the terminal. Useful for debugging or when running inside Docker / systemd / a process manager.

Custom port


squadron engage --cc-port 9090

Reloading configuration

After editing your HCL files, reload the running daemon in place:


squadron engage -r

The new config is validated first; if it’s bad, the running daemon keeps its previous config and the command prints the error. In-flight missions and chat sessions keep running on the config they started with.

Stopping


squadron disengage

Sends SIGTERM to the running daemon, removes the system service, cleans up the command center process. See disengage.

Remote Command Center

If your config declares a command_center block:


command_center {
  url           = "wss://command-center.example.com/ws"
  instance_name = "my-instance"
}

…Squadron connects outbound to that command center and skips the local UI automatically. See Command Center for all fields and production patterns (auto-reconnect, webhooks, variable interpolation).

Behavior with Invalid Config

engage is forgiving about config issues:

HCL syntax errors or missing required fields — Squadron starts in degraded mode; unless --headless was passed, the UI lets you fix files in place.
Missing variables — Squadron starts; the UI lets you add them.
Storage open failure — Squadron exits (this is a real environment problem, not user-fixable from the UI).

This means you can deploy a half-finished config and finish setup through the browser.

Schedules & Triggers

In engage mode, missions with schedule blocks run automatically on their cron timers. Missions with a trigger block expose a webhook through the command center.

See Schedules & Triggers for details.

Docker

The official image sets SQUADRON_CONTAINER=1, which tells Squadron to run in the foreground. The command center still launches by default — browser auto-open is always skipped inside containers. Pass --headless if you don’t need the UI:


docker run -v ./my-project:/config -p 8080:8080 \
  ghcr.io/mlund01/squadron engage

See the Docker guide.