Boot

Boot Skill

Overview

The boot skill gives every agent worktree its own isolated application instance — a dedicated port, an optional isolated database schema or file, and a health-check loop that blocks until the app is accepting requests.

Two entry points are provided:

Workflow

Do you need a standalone bash script? → Generate a boot script

Do you need to start the app from Python? → Boot directly from Python

Do you need database isolation between concurrent agents? → Configure database isolation

Generate a Boot Script

from harness_skills.boot import BootConfig, IsolationConfig, generate_boot_script

config = BootConfig(
    worktree_id="fb563322",          # short task-UUID prefix or branch slug
    start_command="uvicorn myapp.main:app --port 8001",
    isolation=IsolationConfig(port=8001),
    health_path="/healthz",
    health_timeout_s=30,
    log_file="/tmp/harness_fb563322.log",
)

script_content = generate_boot_script(config)

# Write to disk and make executable
with open("boot_fb563322.sh", "w") as f:
    f.write(script_content)

The generated script (boot_<worktree_id>.sh):

1. Exports PORT and any isolation env-vars.
2. Launches the application in the background with &.
3. Polls curl against the health endpoint every health_interval_s seconds.
4. Exits 0 when HTTP 2xx is received; exits 1 and kills the process on timeout.

Run it with:

bash boot_fb563322.sh

Boot Directly from Python

from harness_skills.boot import BootConfig, IsolationConfig, boot_instance

cfg = BootConfig(
    worktree_id="fb563322",
    start_command="uvicorn myapp.main:app --port 8001",
    isolation=IsolationConfig(port=8001),
    health_path="/healthz",
    health_timeout_s=30,
)

result = boot_instance(cfg)

if result.ready:
    print(f"Instance ready — PID {result.pid} on port {result.port} "
          f"({result.elapsed_s:.1f}s)")
else:
    print(f"Boot failed: {result.error}")

boot_instance returns a BootResult regardless of success or failure — always inspect result.ready before proceeding.

Configure Database Isolation

PostgreSQL schema per worktree

from harness_skills.boot import IsolationConfig, DatabaseIsolation

isolation = IsolationConfig(
    port=8001,
    db_isolation=DatabaseIsolation.SCHEMA,
    db_schema="worktree_fb563322",   # omit to auto-derive from worktree_id
)

The boot script exports DB_SCHEMA=worktree_fb563322. Your app must honour that variable when constructing its database connection.

SQLite file per worktree

isolation = IsolationConfig(
    port=8001,
    db_isolation=DatabaseIsolation.FILE,
    db_file="/tmp/harness_fb563322.db",  # omit to auto-derive
)

Exports DATABASE_URL=sqlite:///....

Container-level isolation

isolation = IsolationConfig(
    port=8001,
    db_isolation=DatabaseIsolation.CONTAINER,
)

Assumes DATABASE_URL is already set by the container orchestrator; the boot script emits a comment to that effect.

No isolation (default)

isolation = IsolationConfig(port=8001)   # db_isolation=DatabaseIsolation.NONE

Health Check Spec

Use generate_health_check_spec to get a machine-readable spec you can persist or pass to another component:

from harness_skills.boot import generate_health_check_spec

spec = generate_health_check_spec(cfg)
# spec.url          → "http://localhost:8001/healthz"
# spec.method       → HealthCheckMethod.GET
# spec.expected_codes → [200..299]
# spec.max_wait_s   → 30.0

Extra Environment Variables

Inject arbitrary env-vars into the boot script or subprocess:

isolation = IsolationConfig(
    port=8001,
    extra_env={
        "FEATURE_FLAG_PAYMENTS": "false",
        "LOG_LEVEL": "debug",
    },
)

Reference: BootConfig Fields

Reference: BootResult Fields

Key Files