What This File Controls
BOOT.md defines what your agent does once at launch — verifying that its environment is healthy, loading critical data, and logging its readiness status. The purpose is to catch problems at launch, not mid-session. Without BOOT.md, the agent starts in whatever state the environment happens to be in, and configuration errors only surface when a user hits them during a conversation.
The runtime executes BOOT.md as the final step in the initialisation sequence, after all other workspace files have been loaded. It runs the bootVerify checks sequentially; if any check fails, the agent can either start in degraded mode (with warnings logged) or halt entirely, depending on the severity configuration. The bootLog field then records the startup event for monitoring and audit purposes.
BOOT.md has only two fields, making it the simplest workspace file — but its impact on operational reliability is disproportionate. A well-configured BOOT.md prevents the most frustrating class of agent failures: the ones where everything appears to work until a critical capability silently fails 30 minutes into a session.
Why it matters: Catch problems at launch, not mid-session.
Field-by-Field Breakdown
2 fields that shape your agent
bootVerifyRequiredChecks to run at startup to confirm everything is ready.
bootLogOptionalWhat the agent should record when it starts up.
Real-World Examples
## bootVerify
- Confirm GOV.UK API access is functional (test query)
- Confirm client database read-only connection is active
- Confirm Slack bot token is valid and scoped to #tax-queries
- Load current filing deadline calendar from shared drive
- Check for any unresolved escalations from previous sessions
## bootLog
FINLEY ONLINE — [date] — APIs: [status] | DB: [status] | Pending escalations: [count] | Next filing deadline: [date, client]Common Mistakes
Leaving bootVerify blank
Without verification checks, the agent starts regardless of environment health. API keys could be expired, databases offline, or permissions revoked — and you will not know until a user encounters the failure.
Writing checks that always pass
A verification like ‘check that config file exists’ is trivially true even if the file is empty or corrupt. Checks should validate actual functionality: make a test API call, run a test query, verify a response format.
Logging to unreliable locations
If bootLog writes to a location that is itself unavailable (e.g., a network drive that failed to mount), the boot log is lost when you need it most. Log locally first, then replicate to external monitoring.
Not including timestamps or version in bootLog
Boot logs without timestamps are impossible to correlate with incidents. Without version information, you cannot determine which workspace configuration was active when a problem occurred.
How SetupClaw Handles This
Every SetupClaw deployment includes a pre-launch boot sequence validation. Our specialist configures verification checks for every tool and data source referenced in TOOLS.md, then runs the full boot sequence before handover to confirm a clean startup.
Boot verification for all configured tools + structured boot log + pre-launch validation
All above + degraded mode configuration (start with warnings vs halt) + automated restart handling
All above + bootLog integration with existing monitoring (Datadog, Grafana) + structured JSON boot events
- Both fields configured with meaningful checks
- Every TOOLS.md capability verified at boot
- Boot log format includes timestamp, status, and pending items
- Pre-launch validation passed before handover
- Degraded mode behaviour documented (Standard+)
Configured and validated during deployment (day 1–2). Monitoring integration by day 5 (Professional).
Advanced Topics
Structured JSON boot events for monitoring integration
For Professional-tier deployments with existing monitoring infrastructure, configure bootLog to emit structured JSON events that can be ingested by Datadog, Grafana, or similar tools. This enables automated alerting on boot failures, trend analysis of boot times, and correlation with incident timelines.
## bootLog
{
"event": "BOOT",
"agent": "Finley",
"timestamp": "[ISO 8601]",
"version": "[workspace-version]",
"checks": {
"govuk_api": "[pass/fail]",
"client_db": "[pass/fail]",
"slack_bot": "[pass/fail]"
},
"pending_escalations": [count],
"boot_duration_ms": [duration],
"status": "ONLINE|DEGRADED|FAILED"
}Example Configurations
Persona A — MeridianChief of Staff
# BOOT.md -- Startup Actions
## bootVerify
- Confirm calendar, email, and Notion API access
- Load current OKR document and verify it is up to date
- Check for unresolved escalations from previous sessions
- Verify Slack connectivity and channel permissions
## bootLog
MERIDIAN ONLINE — [date] — Current critical path: [item] | Pending escalations: [count] | OKR status: [loaded/stale]Persona B — Axiom (Veteran Growth Hacker)
# BOOT.md -- Startup Actions
## bootVerify
- Confirm Mixpanel and analytics database connectivity
- Load experiment backlog and check for experiments needing sample size review
- Verify Google/Meta Ads API read access
- Check for experiments past their scheduled end date
## bootLog
AXIOM ONLINE — [date] — Active experiments: [N] | Overdue experiments: [N] | Funnel baseline loaded: [yes/no]Persona C — Lumen (Scientific Researcher)
# BOOT.md -- Startup Actions
## bootVerify
- Confirm PubMed and Zotero API access
- Load current research agenda and active threads
- Check for flagged papers awaiting full review
- Verify citation database is synchronised
## bootLog
LUMEN ONLINE — [date] — Active research threads: [N] | Papers pending review: [N] | Database sync: [current/stale]Persona D — Narrative (Senior Content Creator)
# BOOT.md -- Startup Actions
## bootVerify
- Confirm CMS, Ahrefs, Buffer, and GA4 API access
- Load editorial calendar and check for pieces due within 7 days
- Check for pending content briefs awaiting approval
- Verify social scheduling queue is populated
## bootLog
NARRATIVE ONLINE — [date] — Pieces due this week: [N] | Pending briefs: [N] | Social queue: [N items scheduled]Persona E — Architect (Chief Engineer)
# BOOT.md -- Startup Actions
## bootVerify
- Confirm GitHub, Datadog, and AWS EKS API access
- Load active ADRs and check for pending decisions
- Check for open P1/P2 incidents
- Verify CI/CD pipeline status
## bootLog
ARCHITECT ONLINE — [date] — Open incidents: [N] | PRs awaiting review: [N] | Active ADRs: [N] | Pipeline: [green/red]