### Verify Clawup Setup

Source: https://docs.clawup.sh/prerequisites

Runs the `clawup setup` command to validate the installation and configuration of all prerequisites. Missing items will be flagged.

```bash
clawup setup
```

--------------------------------

### Copy Environment Example

Source: https://docs.clawup.sh/quickstart

Copies the example environment file to `.env`. This file is used to store sensitive API keys and credentials required for ClawUp operations.

```bash
cp .env.example .env
```

--------------------------------

### Install Tailscale

Source: https://docs.clawup.sh/prerequisites

Installs Tailscale on macOS and Linux (Ubuntu/Debian). Tailscale provides secure mesh networking.

```bash
# macOS
brew install tailscale

# Linux (Ubuntu/Debian)
curl -fsSL https://tailscale.com/install.sh | sh
```

--------------------------------

### Install Pulumi CLI

Source: https://docs.clawup.sh/prerequisites

Installs the Pulumi CLI on macOS and Linux systems. It's a crucial tool for infrastructure provisioning.

```bash
# macOS
brew install pulumi/tap/pulumi

# Linux
curl -fsSL https://get.pulumi.com | sh

# Verify
pulumi version
```

--------------------------------

### Example .env.example File Structure

Source: https://docs.clawup.sh/configuration/environment

Demonstrates the structure of the `.env.example` file generated by `clawup init` and `clawup setup`. It lists required environment variables organized by scope, with empty values for user input.

```bash
# Clawup Secrets — copy to .env and fill in values
# See clawup.yaml 'secrets' section for which keys map where

# ── Required ─────────────────────────────────
ANTHROPIC_API_KEY=
TAILSCALE_AUTH_KEY=
TAILNET_DNS_NAME=
TAILSCALE_API_KEY=

# ── Agent: Juno (pm) ──────────────────────
PM_SLACK_BOT_TOKEN=
PM_SLACK_APP_TOKEN=
PM_NOTION_API_KEY=
# PM_LINEAR_USER_UUID=  # auto-fetched if PM_LINEAR_API_KEY is set
```

--------------------------------

### Configure AWS CLI

Source: https://docs.clawup.sh/prerequisites

Installs and configures the AWS Command Line Interface. Requires AWS credentials and specific IAM permissions for EC2, EBS, VPC, Security Groups, and IAM.

```bash
# Install AWS CLI
brew install awscli  # or: pip install awscli

# Configure credentials
aws configure
```

--------------------------------

### Initialize ClawUp Project

Source: https://docs.clawup.sh/quickstart

Initializes a new ClawUp project by discovering local identity directories and generating a `clawup.yaml` manifest and `.env.example` file with default configurations.

```bash
clawup init
```

--------------------------------

### Install Clawup CLI

Source: https://docs.clawup.sh/cli/overview

Installs the Clawup CLI globally using npm. This command requires Node.js and npm to be installed on your system.

```bash
npm install -g clawup
```

--------------------------------

### Clawup Manifest Example Configuration (YAML)

Source: https://docs.clawup.sh/configuration/manifest

An example of a complete clawup.yaml manifest file. This configuration demonstrates how to set up a deployment with Hetzner Cloud, including stack details, owner information, model provider settings, template variables, secrets, and definitions for multiple agents with specific roles and plugins.

```yaml
stackName: prod
provider: hetzner
region: fsn1
instanceType: cx32
ownerName: Jane Doe
timezone: America/New_York
workingHours: 9am-6pm
modelProvider: anthropic
defaultModel: anthropic/claude-opus-4-6
templateVars:
  LINEAR_TEAM: ENG
  GITHUB_REPO: https://github.com/myorg/myrepo
secrets:
  anthropicApiKey: "${env:ANTHROPIC_API_KEY}"
  tailscaleAuthKey: "${env:TAILSCALE_AUTH_KEY}"
  tailnetDnsName: "${env:TAILNET_DNS_NAME}"
  tailscaleApiKey: "${env:TAILSCALE_API_KEY}"
  hcloudToken: "${env:HCLOUD_TOKEN}"
agents:
  - name: agent-pm
    displayName: Juno
    role: pm
    identity: "https://github.com/stepandel/army-identities#pm"
    volumeSize: 30
    plugins:
      openclaw-linear:
        agentId: agent-pm
      slack:
        mode: socket
  - name: agent-eng
    displayName: Titus
    role: eng
    identity: "https://github.com/stepandel/army-identities#eng"
    volumeSize: 50
  - name: agent-researcher
    displayName: Atlas
    role: researcher
    identity: "./my-identities/researcher"
    volumeSize: 20
```

--------------------------------

### Clone and Build Clawup CLI

Source: https://docs.clawup.sh/contributing

Instructions to clone the Clawup repository, install dependencies using pnpm, and build the command-line interface (CLI) package.

```bash
# Clone the repo
git clone https://github.com/stepandel/clawup.git
cd clawup

# Install dependencies
pnpm install

# Build the CLI
pnpm --filter clawup build
```

--------------------------------

### Examples of Setting and Listing Pulumi Secrets

Source: https://docs.clawup.sh/cli/secrets

Illustrates practical usage of the `clawup secrets` command for setting global and per-agent secrets, and for listing all configured secrets. These examples demonstrate how to manage sensitive data effectively.

```bash
# Set a global secret
clawup secrets set braveApiKey BSA_xxx

# Set per-agent secrets
clawup secrets set slackBotToken xoxb-xxx --agent eng
clawup secrets set githubToken ghp_xxx --agent pm

# List all configured secrets
clawup secrets list
```

--------------------------------

### Deploy ClawUp Agents

Source: https://docs.clawup.sh/quickstart

Provisions your AI agents, including dedicated servers, storage, networking, and bootstrap integrations, using Pulumi. The first deployment may take 3-5 minutes.

```bash
clawup deploy
```

--------------------------------

### Identity Manifest (`identity.yaml`) Full Example

Source: https://docs.clawup.sh/architecture/identities

A comprehensive example of an `identity.yaml` file, demonstrating required and optional fields for configuring an agent's name, role, model, dependencies, plugins, and skills. This manifest is crucial for defining agent behavior and capabilities.

```yaml
name: eng
displayName: Titus
role: eng
emoji: building_construction
description: Lead engineering, coding, shipping
volumeSize: 50

model: anthropic/claude-opus-4-6
backupModel: anthropic/claude-sonnet-4-5
codingAgent: claude-code

deps:
  - gh
  - brave-search

plugins:
  - openclaw-linear
  - slack

pluginDefaults:
  openclaw-linear:
    stateActions:
      triage: remove
      backlog: add
      started: add
      completed: remove
  slack:
    mode: socket
    dm:
      enabled: true
      policy: open

skills:
  - eng-queue-handler
  - eng-ticket-workflow
  - eng-pr-tester
  - pr-review-resolver

templateVars:
  - OWNER_NAME
  - TIMEZONE
  - WORKING_HOURS
  - USER_NOTES
  - LINEAR_TEAM
  - GITHUB_REPO
```

--------------------------------

### Clawup CLI Commands Overview

Source: https://docs.clawup.sh/cli/overview

Lists the primary commands available in the Clawup CLI for managing agent teams. These commands cover initialization, setup, deployment, monitoring, access, and teardown.

```bash
clawup init
clawup setup
clawup deploy
clawup redeploy
clawup status
clawup ssh
clawup validate
clawup push
clawup destroy
clawup list
clawup config
clawup secrets
clawup webhooks
clawup update
```

--------------------------------

### Manage ClawUp Agent Status

Source: https://docs.clawup.sh/quickstart

Provides commands to check the status of your deployed agents, SSH into a specific agent, and validate the health of all agents.

```bash
# Check status
clawup status

# SSH to an agent
clawup ssh <agent-name>

# Validate health
clawup validate
```

--------------------------------

### Environment Variables (.env) Example

Source: https://docs.clawup.sh/configuration/environment

An example of a `.env` file, which stores the actual sensitive values for environment variables. This file is intended to be git-ignored and is used by Clawup to populate the secrets declared in `clawup.yaml`.

```bash
# .env — actual values (git-ignored)
ANTHROPIC_API_KEY=sk-ant-api03-xxxxx
TAILSCALE_AUTH_KEY=tskey-auth-xxxxx
TAILNET_DNS_NAME=tail12345.ts.net
TAILSCALE_API_KEY=tskey-api-xxxxx
PM_SLACK_BOT_TOKEN=xoxb-xxxxx
PM_SLACK_APP_TOKEN=xapp-xxxxx
```

--------------------------------

### Setup Linear Webhooks using Clawup CLI

Source: https://docs.clawup.sh/cli/webhooks

This command configures Linear webhooks for deployed agents. It reads the clawup.yaml manifest, identifies agents with the openclaw-linear plugin, creates Linear webhooks pointing to each agent's OpenClaw gateway endpoint, and configures webhook secrets for secure payload verification. Agents must be deployed and accessible via Tailscale.

```bash
clawup webhooks setup
```

--------------------------------

### Custom Identity Configuration (YAML)

Source: https://docs.clawup.sh/agents/juno

Example of how to customize Juno's identity by pointing to a forked or custom identities repository. This allows for tailored agent behavior and personality.

```yaml
identity: "https://github.com/your-org/your-identities#pm"
```

--------------------------------

### Configure Linear API Keys in .env

Source: https://docs.clawup.sh/integrations/linear

This snippet shows how to add Linear API keys for different agent roles (PM, Engineer, Tester) to your .env file. These keys are essential for the agents to interact with Linear and are validated during the 'clawup setup' process.

```bash
PM_LINEAR_API_KEY=lin_api_XXXXXXXXXXXX
ENG_LINEAR_API_KEY=lin_api_XXXXXXXXXXXX
TESTER_LINEAR_API_KEY=lin_api_XXXXXXXXXXXX
```

--------------------------------

### Bootstrap Agent with Tailscale Mesh VPN

Source: https://docs.clawup.sh/architecture/networking

This command bootstraps an agent by installing Tailscale and joining the tailnet using a reusable authentication key. It also enables SSH access over the mesh and sets a unique hostname for the agent based on the stack and agent name. Dependencies include Tailscale being installed on the agent and a valid auth key.

```bash
tailscale up --authkey=<key> --ssh --hostname=<stack>-<agent-name>
```

--------------------------------

### Monorepo Identity Structure Example

Source: https://docs.clawup.sh/architecture/identities

Illustrates a monorepo layout where multiple identities (e.g., researcher, analyst, writer) reside in separate subdirectories, each with its own identity configuration file.

```tree
my-identities/
├── researcher/
│   ├── identity.yaml
│   └── ...
├── analyst/
│   ├── identity.yaml
│   └── ...
└── writer/
    ├── identity.yaml
    └── ...
```

--------------------------------

### Identity Structure Example

Source: https://docs.clawup.sh/architecture/identities

Illustrates the typical file structure for a Clawup identity, including the manifest, personality files, and skill directories. This structure helps organize agent configurations and operational files.

```tree
my-identity/
├── identity.yaml       # Manifest: model, plugins, deps, skills, template vars
├── SOUL.md             # Personality, approach, boundaries
├── IDENTITY.md         # Name, role, emoji
├── HEARTBEAT.md        # Periodic tasks
├── TOOLS.md            # Tool reference
├── AGENTS.md           # Operational instructions
├── BOOTSTRAP.md        # First-run setup
├── USER.md             # Owner info (templated)
└── skills/
    └── my-skill/
        └── SKILL.md
```

--------------------------------

### Override Plugins and Dependencies in Clawup Agent Manifest

Source: https://docs.clawup.sh/architecture/identities

Demonstrates how to override an identity's default plugins and dependencies within an agent's configuration in the manifest. This example shows how to specifically enable the Slack plugin.

```yaml
agents:
  - name: agent-eng
    displayName: Titus
    role: eng
    identity: "https://github.com/stepandel/army-identities#eng"
    volumeSize: 50
    plugins:
      slack:               # Only Slack, skip Linear
        mode: socket
```

--------------------------------

### Set Anthropic API Key

Source: https://docs.clawup.sh/prerequisites

Sets the ANTHROPIC_API_KEY environment variable. An Anthropic Claude API key is required for agents, and the Max plan is recommended due to continuous agent operation.

```bash
export ANTHROPIC_API_KEY="sk-ant-..."
```

--------------------------------

### Set Linear Webhook Secret in .env

Source: https://docs.clawup.sh/integrations/linear

This example demonstrates how to add Linear webhook secrets to your .env file. These secrets are used to secure the webhook communication between Linear and your agents, ensuring that only authorized events are processed.

```bash
PM_LINEAR_WEBHOOK_SECRET=your_pm_webhook_secret
ENG_LINEAR_WEBHOOK_SECRET=your_eng_webhook_secret
TESTER_LINEAR_WEBHOOK_SECRET=your_tester_webhook_secret
```

--------------------------------

### Setting Linear User UUID Manually

Source: https://docs.clawup.sh/configuration/environment

Example of how to manually set the `linearUserUuid` in the `.env` file. This bypasses the automatic fetching of the UUID via the Linear API during `clawup setup`.

```bash
PM_LINEAR_USER_UUID=a1b2c3d4-e5f6-7890-abcd-ef1234567890
```

--------------------------------

### Expose OpenClaw Web UI with Tailscale Serve

Source: https://docs.clawup.sh/architecture/networking

This command starts Tailscale Serve in the background to proxy the OpenClaw gateway. It makes the web UI accessible over the Tailscale network via HTTPS. The gateway port, defaulting to 18789, remains on localhost, with Tailscale Serve handling TLS termination and traffic proxying. Dependencies include Tailscale being installed and the OpenClaw gateway running.

```bash
tailscale serve --bg 18789
```

--------------------------------

### Clawup CLI Global Options

Source: https://docs.clawup.sh/cli/overview

Shows the global options available for the Clawup CLI, including how to display the version and access help information for the CLI and specific commands.

```bash
clawup --version
clawup --help
clawup <cmd> --help
```

--------------------------------

### Slack App Manifest for Juno (Product Manager)

Source: https://docs.clawup.sh/integrations/slack

This JSON manifest configures the 'Juno' Slack app, intended for Product Managers. It defines the app's display name, description, bot user settings, app home tab enablement, a '/openclaw' slash command, and extensive bot and user OAuth scopes. It also enables socket mode and subscribes to various bot events.

```json
{
  "display_information": {
    "name": "Juno (PM)",
    "description": "Slack connector for OpenClaw"
  },
  "features": {
    "bot_user": {
      "display_name": "Juno",
      "always_online": false
    },
    "app_home": {
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "slash_commands": [
      {
        "command": "/openclaw",
        "description": "Send a message to OpenClaw",
        "should_escape": false
      }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "chat:write",
        "chat:write.customize",
        "channels:history",
        "channels:read",
        "groups:history",
        "groups:read",
        "groups:write",
        "im:history",
        "im:read",
        "im:write",
        "mpim:history",
        "mpim:read",
        "mpim:write",
        "users:read",
        "app_mentions:read",
        "reactions:read",
        "reactions:write",
        "pins:read",
        "pins:write",
        "emoji:read",
        "commands",
        "files:read",
        "files:write"
      ],
      "user": [
        "channels:history",
        "channels:read",
        "groups:history",
        "groups:read",
        "im:history",
        "im:read",
        "mpim:history",
        "mpim:read",
        "users:read",
        "reactions:read",
        "pins:read",
        "emoji:read",
        "search:read"
      ]
    }
  },
  "settings": {
    "socket_mode_enabled": true,
    "event_subscriptions": {
      "bot_events": [
        "app_mention",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim",
        "reaction_added",
        "reaction_removed",
        "member_joined_channel",
        "member_left_channel",
        "channel_rename",
        "pin_added",
        "pin_removed"
      ]
    }
  }
}
```

--------------------------------

### Dependency Registry Configuration (TypeScript)

Source: https://docs.clawup.sh/configuration/identity

Details the system-level tools that can be declared as dependencies for OpenClaw agents. It specifies the key, what each dependency installs, and how it's configured.

```typescript
// Defined in packages/core/src/dep-registry.ts
// Example structure (actual code not provided in text):
/*
{
  "gh": {
    "description": "GitHub CLI — installed from official apt repo, authenticated with provided token",
    "installCommand": "sudo apt install gh && gh auth login --with-token < token.txt",
    "config": {
      "tokenEnvVar": "GH_TOKEN"
    }
  },
  "brave-search": {
    "description": "Brave Search API key — config-only, sets environment variable for API access",
    "config": {
      "apiKeyEnvVar": "BRAVE_SEARCH_API_KEY"
    }
  }
}
*/

```

--------------------------------

### Manage Linear Tickets with CLI Commands (Bash)

Source: https://docs.clawup.sh/integrations/linear

This snippet demonstrates common commands for managing Linear tickets using the Linear CLI. It covers listing, viewing, updating, and creating tickets, including sub-tasks. These commands are essential for agents interacting with the Linear platform.

```bash
# List tickets assigned to the agent
linear issue list --filter "assignee:me"

# View ticket details
linear issue view ENG-123

# Update ticket status
linear issue update ENG-123 --state "In Progress"

# Create a sub-task
linear issue create --title "Implement auth endpoint" --team ENG --parent ENG-100
```

--------------------------------

### Display Project Configuration with Clawup CLI

Source: https://docs.clawup.sh/cli/list

The 'clawup list' command retrieves and displays the current project's configuration, which is stored in 'clawup.yaml'. This includes details such as the stack name, number of agents, deployment region, and the instance type used. An optional '--json' flag can be used to format the output as JSON.

```bash
clawup list

```

```bash
clawup list --json

```

--------------------------------

### GitHub CLI and Git Commands for Agent Operations

Source: https://docs.clawup.sh/integrations/github

This section outlines common commands agents use to interact with GitHub repositories. It covers cloning, branching, creating pull requests, and checking CI status using the GitHub CLI (`gh`) and Git.

```bash
# Clone the repo
git clone https://github.com/yourorg/yourrepo.git

# Create a feature branch
git checkout -b feat/add-auth-endpoint

# Open a PR
gh pr create --title "feat: add auth endpoint" --body "Closes ENG-123"

# Check CI status
gh pr checks 42

# View PR review comments
gh pr view 42 --comments
```

--------------------------------

### Custom Identity Configuration (YAML)

Source: https://docs.clawup.sh/agents/titus

Example of how to configure Titus to use a custom identity source, such as a forked army-identities repository. This allows for deep customization of the agent's behavior and capabilities.

```yaml
identity: "https://github.com/your-org/your-identities#eng"
```

--------------------------------

### Deploy Agent Team with Clawup CLI

Source: https://docs.clawup.sh/cli/deploy

The 'clawup deploy' command provisions infrastructure and deploys your agent team using Pulumi. It reads the 'clawup.yaml' manifest, runs 'pulumi up' to create cloud resources, and bootstraps agents. The '--local' option allows deployment to local Docker containers for testing without creating cloud resources.

```bash
clawup deploy [options]

# Deploy with confirmation
clawup deploy

# Deploy without confirmation
clawup deploy --yes

# Deploy to local Docker containers
clawup deploy --local

# Deploy to local Docker containers without confirmation
clawup deploy --local --yes
```

--------------------------------

### Skill Configuration in clawup.yaml

Source: https://docs.clawup.sh/guides/creating-identities

The `clawup.yaml` file lists the skills to be loaded. Skills can be local (defined within the project) or fetched from a remote registry like ClawHub.

```yaml
skills:
  - my-private-skill          # Loaded from skills/my-private-skill/SKILL.md
  - clawhub:org/public-skill  # Fetched from ClawHub registry
```

--------------------------------

### Identity YAML Required Secrets Declaration

Source: https://docs.clawup.sh/configuration/environment

Example of an `identity.yaml` file showing how to declare additional required secrets using the `requiredSecrets` field. This complements secrets implicitly required by plugins and dependencies.

```yaml
# identity.yaml
plugins:
  - slack              # implicitly → slackBotToken, slackAppToken
deps:
  - gh                 # implicitly → githubToken


```

--------------------------------

### Clawup CLI Local Docker Mode Commands

Source: https://docs.clawup.sh/cli/overview

Demonstrates how to use the `--local` flag with Clawup CLI commands to target local Docker containers instead of cloud infrastructure. This is useful for development and testing.

```bash
clawup deploy --local
clawup redeploy --local
clawup status --local
clawup ssh titus --local
clawup validate --local
clawup push --local
clawup destroy --local
```

--------------------------------

### Managing Secrets with Clawup CLI

Source: https://docs.clawup.sh/configuration/environment

Provides examples of using the `clawup secrets` command to set, rotate, and list secrets. These operations update the encrypted Pulumi config and require `clawup redeploy` to apply changes.

```bash
# Set or rotate a secret
clawup secrets set braveApiKey BSA_xxx
clawup secrets set slackBotToken xoxb-xxx --agent pm

# List configured secrets (values redacted)
clawup secrets list
```

--------------------------------

### Plugin Defaults Configuration (YAML)

Source: https://docs.clawup.sh/configuration/identity

Illustrates how to set default configurations for plugins within an agent's identity. This allows for fine-tuning plugin behavior, such as Linear state actions and Slack DM settings.

```yaml
pluginDefaults:
  openclaw-linear:
    stateActions:
      backlog: add        # Add to queue when ticket enters Backlog
      started: add        # Add to queue when ticket enters Started
      completed: remove   # Remove from queue when completed
  slack:
    mode: socket
    dm:
      enabled: true
      policy: open

```

--------------------------------

### Overriding Default Environment File Location

Source: https://docs.clawup.sh/configuration/environment

Shows how to specify a custom environment file path using the `--env-file` flag with the `clawup setup` command. This allows users to manage their `.env` file in a different location.

```bash
clawup setup --env-file /path/to/my/.env
```

--------------------------------

### View Clawup Configuration

Source: https://docs.clawup.sh/cli/config

Displays the current clawup deployment configuration. The `--json` flag outputs the configuration in JSON format, which can be useful for programmatic access or detailed inspection.

```bash
clawup config show
clawup config show --json
```

--------------------------------

### Configure GitHub Tokens in .env File

Source: https://docs.clawup.sh/integrations/github

This snippet shows how to add GitHub personal access tokens for different agent roles to the `.env` file. These tokens are used for authentication and are typically prefixed with the agent's role (e.g., PM, ENG, TESTER).

```bash
PM_GITHUB_TOKEN=ghp_XXXXXXXXXXXX
ENG_GITHUB_TOKEN=github_pat_XXXXXXXXXXXX
TESTER_GITHUB_TOKEN=ghp_XXXXXXXXXXXX
```

--------------------------------

### Clawup YAML Secrets Configuration

Source: https://docs.clawup.sh/configuration/environment

Example of the `secrets` section in `clawup.yaml`, demonstrating how to declare environment variables using the `${env:VAR_NAME}` syntax for global and per-agent secrets. This makes the YAML self-documenting while keeping actual values out of version control.

```yaml
# clawup.yaml — secrets section (auto-generated)
secrets:
  anthropicApiKey: "${env:ANTHROPIC_API_KEY}"
  tailscaleAuthKey: "${env:TAILSCALE_AUTH_KEY}"
  tailnetDnsName: "${env:TAILNET_DNS_NAME}"
  tailscaleApiKey: "${env:TAILSCALE_API_KEY}"
agents:
  - name: agent-pm
    role: pm
    secrets:
      slackBotToken: "${env:PM_SLACK_BOT_TOKEN}"
      slackAppToken: "${env:PM_SLACK_APP_TOKEN}"
```

--------------------------------

### Agent Configuration in Local Directory

Source: https://docs.clawup.sh/architecture/identities

This YAML snippet shows how to configure an agent, referencing its identity from a local directory path. It includes the agent's name, display name, role, and volume size.

```yaml
agents:
  - name: agent-researcher
    displayName: Atlas
    role: researcher
    identity: "./my-identities/researcher"
    volumeSize: 20
```

--------------------------------

### Update Clawup CLI using Bash

Source: https://docs.clawup.sh/cli/update

Updates the clawup CLI to the latest version available on npm. This command executes `npm install -g clawup@latest` in the background. The CLI also includes a feature to periodically check for and notify users about new versions.

```bash
clawup update
```