onboard - Clawup

Plugin hooks are experimental and subject to change. The API may evolve in future releases.

Runs onboard hooks interactively. Onboard hooks are scripts (defined at the swarm, identity, or plugin level) that handle first-time setup tasks like creating webhook endpoints, generating signing secrets, or configuring external services. For a comprehensive guide to all hook types, see Lifecycle Hooks.

Usage

clawup onboard [options]

Options

Option	Description
`--env-file <path>`	Path to `.env` file (defaults to `.env` in project root)

What It Does

Loads clawup.yaml and resolves agent identities
Loads .env and resolves secrets
Runs each plugin’s onboard hook (if defined) with the resolved context
Hooks can prompt for input, call external APIs, and display follow-up instructions

When to Use

Run clawup onboard after your first clawup deploy if any plugins have onboard hooks that need interactive setup. For example, a plugin might need to register webhook URLs that are only available after deployment. You can also pass --onboard to clawup deploy to run onboard hooks during the deploy phase.

Plugin Manifest Example

Onboard hooks are defined in a plugin’s manifest file. Here’s a minimal example:

hooks:
  onboard:
    description: "Register webhook with external service"
    inputs:
      configToken:
        envVar: MY_CONFIG_TOKEN
        prompt: "Enter your config token"
        instructions: "Generate at https://example.com/settings/tokens"
        validator: "tok_"
    script: |
      WEBHOOK_URL="https://$(hostname).tail1234.ts.net/hooks/my-plugin"
      curl -s -X POST https://api.example.com/webhooks \
        -H "Authorization: Bearer $MY_CONFIG_TOKEN" \
        -d "{\"url\": \"$WEBHOOK_URL\"}"
      echo "Webhook registered at $WEBHOOK_URL"
    runOnce: true

When runOnce is true, the hook is skipped if all required secrets for the plugin are already configured.

Examples

# Run onboard hooks
clawup onboard

# Run with custom .env location
clawup onboard --env-file /path/to/.env

Onboard hooks can be defined at the swarm level (clawup.yaml), identity level (identity.yaml), or plugin level. Not all levels require onboard hooks — only those that need interactive first-time configuration. See the Lifecycle Hooks guide for details on writing onboard hooks.

​Usage

​Options

​What It Does

​When to Use

​Plugin Manifest Example

​Examples

Usage

Options

What It Does

When to Use

Plugin Manifest Example

Examples