Skip to main content
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

OptionDescription
--env-file <path>Path to .env file (defaults to .env in project root)

​
What It Does

  1. Loads clawup.yaml and resolves agent identities
  2. Loads .env and resolves secrets
  3. Runs each plugin’s onboard hook (if defined) with the resolved context
  4. 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.