BOOTSTRAP.md — Workspace Initialization

+15 Mana ✨
OpenClaw BOOTSTRAP.md Reference(DOCUMENTATION)OpenClaw Workspace Setup Guide(DOCUMENTATION)

Introduction

BOOTSTRAP.md is the workspace initialization file that runs when a new workspace is set up for the first time. It contains setup scripts, initial configuration steps, and first-run instructions that prepare the environment before the agent begins operating. While other bootstrap files define personality and behavior, BOOTSTRAP.md handles the practical setup that must happen once before everything else works correctly.

Key Concepts

  • First-Run Setup: Commands and scripts that execute only when a workspace is initialized for the first time
  • Environment Preparation: Installing dependencies, creating directories, setting permissions, and validating prerequisites
  • Workspace Scaffolding: Creating the file structure and initial files that the agent expects to find in the workspace
  • Idempotent Operations: Setup steps that can safely run multiple times without causing errors or duplicating work
  • Bootstrap vs Runtime: BOOTSTRAP.md runs once during initialization; other bootstrap files (SOUL.md, AGENTS.md) are loaded every session

Real World Context

A team onboards a new developer who clones the repository and sets up OpenClaw for the first time. BOOTSTRAP.md automatically installs project dependencies, creates the required directory structure, sets up git hooks, and runs an initial database migration. Without it, the new developer would need to follow a multi-page setup guide manually, risking missed steps and configuration drift.

Deep Dive

BOOTSTRAP.md lives in the agent directory and is processed during the workspace initialization phase. Its content is a mix of human-readable documentation and executable instructions that the agent follows.

Here is a representative BOOTSTRAP.md:

markdown
# Workspace Initialization

## Prerequisites Check
- Verify Node.js 22+ is installed
- Verify pnpm is available
- Verify Docker is running for database services

## Setup Steps

### 1. Install Dependencies
Run `pnpm install` in the workspace root to install all project
dependencies. This must complete before any other step.

### 2. Environment Configuration
Copy `.env.example` to `.env` if `.env` does not already exist.
Do not overwrite an existing `.env` file.

### 3. Database Setup
Start the database with `docker compose up -d`.
Run `pnpm prisma generate` to generate the Prisma client.
Run `pnpm prisma db push` to apply the schema.

### 4. Directory Structure
Ensure the following directories exist:
- `tmp/` for temporary files
- `logs/` for application logs
- `.openclaw/` for agent state

### 5. Verification
Run `pnpm test` to verify the setup is complete.
All tests should pass on a fresh installation.

This BOOTSTRAP.md walks through a complete workspace setup. Each section handles a different aspect of initialization: prerequisites, dependencies, environment, database, file structure, and verification.

The injection order for bootstrap files during agent startup follows a specific sequence:

markdown
1. IDENTITY.md  (who the agent is)
2. SOUL.md      (personality and boundaries)
3. USER.md      (user preferences)
4. AGENTS.md    (operating instructions)
5. TOOLS.md     (tool conventions)
6. BOOTSTRAP.md (workspace initialization - first run only)
7. MEMORY.md    (accumulated knowledge)

BOOTSTRAP.md is injected after the behavioral files but before MEMORY.md. This means the agent already knows its identity, personality, and instructions when it processes the initialization steps. On subsequent sessions, BOOTSTRAP.md is not re-injected unless the workspace is reset.

An important characteristic of good BOOTSTRAP.md content is idempotency. Every step should be safe to run again:

markdown
# Good: idempotent (safe to re-run)
Copy `.env.example` to `.env` if `.env` does not already exist.

# Bad: not idempotent (would overwrite existing config)
Copy `.env.example` to `.env`.

The first instruction checks before acting. The second would destroy any customizations if accidentally re-run.

Common Pitfalls

  • Including non-idempotent operations: Steps that break on re-run (like unconditional file overwrites) cause problems when workspaces are re-initialized or when the agent re-processes the file.
  • Mixing runtime instructions with setup steps: BOOTSTRAP.md is for one-time setup. Ongoing operational instructions belong in AGENTS.md.
  • Assuming a specific OS: Unless your team is homogeneous, write BOOTSTRAP.md steps that work across macOS, Linux, and Windows or clearly document OS-specific alternatives.

Best Practices

  • Make every step idempotent: Use conditional checks ("if not exists") so re-running BOOTSTRAP.md never causes harm.
  • Include a verification step: End with a command that validates the setup (running tests, checking endpoints, verifying file existence) so issues are caught immediately.
  • Document prerequisites clearly: List exact version requirements and how to install them before the setup steps begin.

Summary

  • BOOTSTRAP.md handles one-time workspace initialization: installing dependencies, configuring environment, setting up databases, and creating directory structures
  • It is processed during first-run setup and not re-injected in subsequent sessions unless the workspace is reset
  • Bootstrap files follow a specific injection order: IDENTITY.md, SOUL.md, USER.md, AGENTS.md, TOOLS.md, BOOTSTRAP.md, MEMORY.md
  • All setup steps should be idempotent to safely handle re-initialization
  • Always include a verification step at the end to confirm the workspace is correctly configured
✓ Completed