Clawup

https://github.com/stepandel/clawup
Admin
Clawup is a deployment platform for provisioning fleets of specialized AI agents on AWS or Hetzner...
Tokens:43,646
Snippets:449
Trust Score:7.8
License:MIT
Update:7 months ago
Show doc for...
Tokens:
Raw
### Copy Environment Example

Source: https://github.com/stepandel/clawup/blob/main/README.md

Copies the example environment file to `.env`, which should then be edited to include sensitive API keys and credentials required by Clawup and its associated services.

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

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

### Display Project Configuration using Clawup CLI

Source: https://github.com/stepandel/clawup/blob/main/docs/cli/list.mdx

This snippet demonstrates how to use the Clawup command-line interface to list the current project's configuration. It shows the basic command and an example for JSON output. No external dependencies are required beyond the clawup CLI installation.

```bash
clawup list

```

```bash
clawup list --json

```

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

### Clawup Manifest Example Configuration

Source: https://github.com/stepandel/clawup/blob/main/docs/configuration/manifest.mdx

An example of a complete clawup.yaml file, demonstrating how to configure stack, owner, model, template variables, secrets, and agent definitions. This serves as a practical guide for setting up a deployment.

```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
```

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

### Development Commands for Clawup

Source: https://github.com/stepandel/clawup/blob/main/CLAUDE.md

This snippet lists essential commands for developing the Clawup project using pnpm. It covers installing dependencies, building packages, running tests, starting development servers, and using watch mode for individual packages.

```bash
pnpm install                              # Install all dependencies
pnpm build                                # Build all packages
pnpm test                                 # Run all tests

# Individual packages
pnpm --filter @clawup/core build      # Build core
pnpm --filter clawup build            # Build CLI
pnpm --filter @clawup/pulumi build    # Build Pulumi
pnpm --filter clawup-web dev          # Web dev server (localhost:3000)

# Watch mode
cd packages/cli && pnpm watch
```

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

### Setup Linear Webhooks

Source: https://context7.com/stepandel/clawup/llms.txt

Configures Linear webhooks for deployed agents that utilize the Linear plugin. This command automates the setup of webhook integrations.

```bash
clawup webhooks setup
```

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

### Install Clawup CLI

Source: https://github.com/stepandel/clawup/blob/main/docs/cli/overview.mdx

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
```

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

### Clone and Build Clawup CLI

Source: https://github.com/stepandel/clawup/blob/main/docs/contributing.mdx

Steps to clone the Clawup repository, install its 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
```

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

### Identity Manifest YAML Configuration Example

Source: https://github.com/stepandel/clawup/blob/main/docs/architecture/identities.mdx

A comprehensive example of an `identity.yaml` file, demonstrating the use of required and optional fields for configuring an engineering agent. It includes model selection, dependencies, plugins, and skill configurations.

```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 Project Manifest (`clawup.yaml`) Example

Source: https://github.com/stepandel/clawup/blob/main/packages/cli/README.md

This YAML snippet shows the structure of the `clawup.yaml` file, which defines deployment settings like stack name, provider, region, instance type, and owner. It also includes agent configurations with their roles, identities, volume sizes, and specific secrets and plugins.

```yaml
stackName: dev
provider: aws
region: us-east-1
instanceType: t3.medium
ownerName: Your Name
secrets:
  anthropicApiKey: "${env:ANTHROPIC_API_KEY}"
  tailscaleAuthKey: "${env:TAILSCALE_AUTH_KEY}"
  tailnetDnsName: "${env:TAILNET_DNS_NAME}"
agents:
  - name: agent-pm
    displayName: Juno
    role: pm
    identity: "https://github.com/your-org/army-identities#pm"
    volumeSize: 30
    secrets:
      slackBotToken: "${env:PM_SLACK_BOT_TOKEN}"
      slackAppToken: "${env:PM_SLACK_APP_TOKEN}"
    plugins:
      openclaw-linear:
        agentId: agent-pm
      slack:
        mode: socket

```

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

### Local Docker Deployment Configuration

Source: https://context7.com/stepandel/clawup/llms.txt

Specifies the configuration for deploying Clawup locally using Docker, which is useful for testing without incurring cloud costs. Includes commands to deploy, access, and validate the local setup.

```yaml
provider: local
region: local
instanceType: local
```

```bash
# Deploy locally
clawup deploy --local

# Access local containers
clawup ssh pm --local

# Validate local setup
clawup validate --local
```

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

### Example GitHub CLI Commands for Agent Operations

Source: https://github.com/stepandel/clawup/blob/main/docs/integrations/github.mdx

Demonstrates common GitHub CLI commands that ClawUp agents use for interacting with repositories. These include cloning, branching, creating pull requests, and checking CI status.

```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
```

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

### Clawup CLI Commands

Source: https://github.com/stepandel/clawup/blob/main/docs/cli/overview.mdx

Lists the primary commands available in the Clawup CLI for managing agent teams, including setup, deployment, monitoring, 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
```

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

### Identity File Structure Example

Source: https://github.com/stepandel/clawup/blob/main/docs/architecture/identities.mdx

Illustrates the typical directory and file structure for a Clawup identity. This includes the main `identity.yaml` manifest, markdown files for personality and operational details, and a `skills` subdirectory.

```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
```

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

### TOOLS.md - Tool Reference (Markdown)

Source: https://github.com/stepandel/clawup/blob/main/docs/guides/creating-identities.mdx

Serves as a reference guide for the tools available to the agent, categorized for easy access. Includes communication and research tools like Slack and Brave Search.

```markdown
# TOOLS.md - Tool Reference

## Communication
### Slack
- Primary way to communicate with {{OWNER_NAME}}

## Research
### Brave Search
- Use for web research and fact-checking
```

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

### Build and Develop Clawup Monorepo Packages

Source: https://github.com/stepandel/clawup/blob/main/README.md

Commands for cloning the Clawup repository, installing dependencies, building all packages, running tests, and developing individual packages within the monorepo using pnpm.

```bash
git clone https://github.com/stepandel/clawup.git
cd clawup
pnpm install
pnpm build                                 # Build all packages
pnpm test                                  # Run all tests

# Individual packages
pnpm --filter @clawup/core build       # Build core
pnpm --filter clawup build             # Build CLI
pnpm --filter @clawup/pulumi build     # Build Pulumi
pnpm --filter clawup-web dev           # Web dev server
```

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

### Clawup Project Structure

Source: https://github.com/stepandel/clawup/blob/main/CLAUDE.md

This snippet illustrates the directory structure of the Clawup project, detailing the purpose of each package and its subdirectories. It highlights shared types, the CLI, infrastructure as code using Pulumi, and the web dashboard.

```text
clawup/
├── packages/
│   ├── core/                    # @clawup/core — shared types, constants, registries
│   │   └── src/
│   │       ├── schemas/         # Zod schemas (source of truth for types)
│   │       ├── types.ts         # TypeScript types (z.infer<> re-exports)
│   │       ├── constants.ts     # Regions, costs, model providers
│   │       ├── identity.ts      # Identity loader + local discovery
│   │       ├── skills.ts        # Skill classification (private vs clawhub)
│   │       ├── deps.ts          # Dep resolution
│   │       ├── plugin-registry.ts
│   │       ├── coding-agent-registry.ts
│   │       └── dep-registry.ts
│   ├── cli/                     # Published npm package (clawup CLI)
│   │   ├── bin.ts               # Entry point - Commander.js commands
│   │   ├── commands/            # Command implementations (init, deploy, ssh, etc.)
│   │   ├── tools/               # Tool implementations (adapter-based)
│   │   ├── lib/                 # CLI-only utilities (config, pulumi, ui, exec, tailscale)
│   │   └── adapters/            # Runtime adapters (CLI vs API)
│   ├── pulumi/                  # @clawup/pulumi — infrastructure as code
│   │   └── src/
│   │       ├── components/
│   │       │   ├── openclaw-agent.ts    # AWS EC2 agent
│   │       │   ├── hetzner-agent.ts     # Hetzner Cloud agent
│   │       │   ├── local-docker-agent.ts # Local Docker agent
│   │       │   ├── cloud-init.ts        # User-data script generation
│   │       │   ├── config-generator.ts  # OpenClaw config builder
│   │       │   ├── shared.ts            # Shared component utilities
│   │       │   └── types.ts             # Component type definitions
│   │       ├── shared-vpc.ts            # AWS VPC component
│   │       └── index.ts                 # Main Pulumi stack program
│   └── web/                     # Next.js dashboard (clawup-web)
│       └── src/
│           ├── app/             # App router pages & API routes
│           ├── components/      # React components (shadcn/ui)
│           └── lib/             # Server utilities (prisma, auth, crypto)
├── docs/                        # Mintlify documentation
├── Pulumi.yaml                  # Points to packages/pulumi/dist/index.js
└── pnpm-workspace.yaml          # packages: ["packages/*"]

```

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

### Check Cloud-init Logs

Source: https://github.com/stepandel/clawup/blob/main/CLAUDE.md

This command retrieves the last 100 lines of the cloud-init output log on an agent. It's used for troubleshooting cloud-init failures by examining the initialization process. Accessing the agent via SSH is required to run this command.

```bash
sudo cat /var/log/cloud-init-output.log | tail -100
```

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

### Example .env File for Secret Values

Source: https://github.com/stepandel/clawup/blob/main/docs/configuration/environment.mdx

This example `.env` file contains the actual secret values used by Clawup. It is intended to be kept out of version control (git-ignored) and is used to populate the environment variables declared in `clawup.yaml`.

```dotenv
# .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
```

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

### Clawup Agent Configuration Example (YAML)

Source: https://github.com/stepandel/clawup/blob/main/README.md

Defines a list of agents to be deployed. Each agent has a name, display name, role, and specifies an identity source, version, and volume size. Identities can be referenced from Git repositories.

```yaml
# clawup.yaml
agents:
  - name: agent-researcher
    displayName: Atlas
    role: researcher
    identity: "https://github.com/your-org/your-identities#researcher"
    identityVersion: "v1.0.0"   # optional: pin to a tag or commit
    volumeSize: 20

```

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

### Identity Manifest Example (identity.yaml)

Source: https://github.com/stepandel/clawup/blob/main/README.md

Declares the core properties of an AI agent identity. This includes its name, display name, role, emoji, description, volume size, model preferences, dependencies, plugins, and template variables.

```yaml
name: researcher
displayName: Atlas
role: researcher
emoji: telescope
description: Deep research, source analysis, report generation
volumeSize: 20

model: anthropic/claude-opus-4-6
codingAgent: claude-code

deps:
  - brave-search

plugins:
  - slack

pluginDefaults:
  slack:
    mode: socket
    dm:
      enabled: true
      policy: open

skills:
  - research-report

templateVars:
  - OWNER_NAME
  - TIMEZONE
  - WORKING_HOURS
  - USER_NOTES

# Additional secrets not covered by plugins/deps
requiredSecrets:
  - notionApiKey       # → <ROLE>_NOTION_API_KEY in .env

```

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

### Expose OpenClaw Gateway with Tailscale Serve

Source: https://github.com/stepandel/clawup/blob/main/docs/architecture/networking.mdx

This command starts the OpenClaw gateway and makes its web UI accessible over the Tailscale network. Tailscale Serve handles TLS termination and proxies traffic to the local gateway, which is bound to localhost.

```bash
# During bootstrap:
tailscale serve --bg 18789
```

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

### Bootstrap Agent with Tailscale

Source: https://github.com/stepandel/clawup/blob/main/docs/architecture/networking.mdx

This command installs Tailscale on an agent during bootstrap and joins the tailnet using a reusable authentication key. It also configures SSH access through Tailscale and sets a unique hostname for the agent.

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

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

### HEARTBEAT.md - Periodic Tasks (Markdown)

Source: https://github.com/stepandel/clawup/blob/main/docs/guides/creating-identities.mdx

Outlines the checklist of tasks the agent executes on each heartbeat cycle, starting with a bootstrap check. This ensures regular maintenance and attention to pending items.

```markdown
# Heartbeat Checklist

## Always
- [ ] If `BOOTSTRAP.md` exists in workspace, follow it first.
- [ ] Check memory files for pending requests or follow-ups.
- [ ] If nothing needs attention, return `HEARTBEAT_OK`.
```

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

### Run Tests with pnpm

Source: https://github.com/stepandel/clawup/blob/main/CLAUDE.md

This command executes the test suite for the project using the pnpm package manager. It's essential for verifying code changes and ensuring the stability of the application. Currently, test coverage is minimal, and new tests should be placed in `__tests__/` directories or as `*.test.ts` files, mocking external dependencies.

```bash
pnpm test
```

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

### OpenClaw Heartbeat Configuration Example

Source: https://github.com/stepandel/clawup/blob/main/docs/architecture/overview.mdx

This JSON snippet defines the heartbeat configuration for an OpenClaw agent. It specifies the interval at which the heartbeat should fire ('1m' for every minute) and the session it belongs to ('main'). This heartbeat is crucial for periodic tasks and bootstrap detection.

```json
{
  "every": "1m",
  "session": "main"
}
```

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

### Juno Agent Configuration (YAML)

Source: https://github.com/stepandel/clawup/blob/main/docs/agents/juno.mdx

Defines the configuration for the Juno agent, including its name, display name, role, identity source, volume size, plugins, and dependencies. This YAML snippet outlines the core setup for the 'agent-pm'.

```yaml
- name: agent-pm
  displayName: Juno
  role: pm
  identity: "https://github.com/stepandel/army-identities#pm"
  volumeSize: 30
  plugins:
    - openclaw-linear
    - slack
  deps:
    - gh
    - brave-search
```

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

### Manual Linear User UUID Configuration in .env

Source: https://github.com/stepandel/clawup/blob/main/docs/configuration/environment.mdx

This bash snippet demonstrates how to manually set the `linearUserUuid` in the `.env` file. This is an alternative to Clawup auto-fetching the UUID via the Linear API during `clawup setup`.

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

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

### Manage Pulumi Configuration Secrets

Source: https://github.com/stepandel/clawup/blob/main/README.md

Manages secrets within the Pulumi configuration, which are automatically set by `clawup setup`. Secrets are stored encrypted. This allows direct management of sensitive configuration values.

```bash
pulumi config set --secret anthropicApiKey sk-ant-xxxxx
pulumi config set --secret tailscaleAuthKey tskey-auth-xxxxx
pulumi config set tailnetDnsName tail12345.ts.net
```

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

### API Route Structure (TypeScript)

Source: https://github.com/stepandel/clawup/blob/main/CLAUDE.md

This outlines the structure for creating a new API route within the web application. It involves creating a `route.ts` file, using `getToken()` for authentication, validating input with Zod schemas, and returning a `NextResponse.json()` object. This follows the conventions of the web framework used in the project.

```typescript
import { NextResponse } from "next/server";
import { getToken } from "next-auth/jwt";
import { z } from "zod";

// Example Zod schema for input validation
const routeSchema = z.object({
  name: z.string(),
  value: z.number()
});

export async function POST(request: Request) {
  const token = await getToken({
    req: request,
    secret: process.env.NEXTAUTH_SECRET
  });

  if (!token) {
    return new NextResponse("Unauthorized", {
      status: 401
    });
  }

  const body = await request.json();
  const validationResult = routeSchema.safeParse(body);

  if (!validationResult.success) {
    return new NextResponse(JSON.stringify(validationResult.error.errors), {
      status: 400,
      headers: {
        "Content-Type": "application/json"
      }
    });
  }

  const { name, value } = validationResult.data;

  // Process the validated data and return a JSON response
  return NextResponse.json({
    message: `Received: ${name} with value ${value}`,
    processedBy: token.email
  });
}
```

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

### Minimal Identity Configuration (YAML)

Source: https://github.com/stepandel/clawup/blob/main/docs/configuration/identity.mdx

The most basic identity configuration requires only essential fields like name, display name, role, emoji, description, volume size, and skills. This serves as a starting point for creating new agents.

```yaml
name: greeter
displayName: Gabi
role: greeter
emoji: wave
description: Friendly welcome bot
volumeSize: 10
skills: []
templateVars:
  - OWNER_NAME
```

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

### Destroy and Redeploy ClawUp Agents

Source: https://github.com/stepandel/clawup/blob/main/README.md

Performs a clean rebuild of ClawUp agents by first destroying the existing infrastructure and then deploying it again. This is useful when in-place updates fail or a fresh start is needed.

```bash
clawup destroy -y && clawup deploy -y
```

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

### Troubleshoot Pulumi Stack Conflicts

Source: https://github.com/stepandel/clawup/blob/main/CLAUDE.md

These commands help resolve issues related to Pulumi stack locks and state synchronization. `pulumi cancel` releases a locked stack, while `pulumi refresh` synchronizes the local stack state with the actual cloud resources. This is crucial for maintaining consistency between your infrastructure definition and its deployed state.

```bash
pulumi cancel
pulumi refresh
```

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

### List Project Configuration

Source: https://context7.com/stepandel/clawup/llms.txt

Lists the project configuration, including all agents and their settings. This provides a comprehensive overview of the deployment.

```bash
clawup list
```

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

### Show Full Configuration as JSON

Source: https://context7.com/stepandel/clawup/llms.txt

Displays the full current configuration as JSON output. This is useful for programmatic access or detailed inspection of the deployment settings.

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

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

### Show Current Configuration Summary

Source: https://context7.com/stepandel/clawup/llms.txt

Displays a human-readable summary of the current configuration from the manifest without opening any files. This provides a quick overview of the deployment settings.

```bash
clawup config show
```

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

### List Project Configuration as JSON

Source: https://context7.com/stepandel/clawup/llms.txt

Lists the project configuration in JSON format. This is useful for programmatic access and integration with other tools.

```bash
clawup list --json
```

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

### Generate Clawup Configuration

Source: https://github.com/stepandel/clawup/blob/main/README.md

Initializes the Clawup project by generating a `clawup.yaml` configuration file and a `.env.example` file. These files provide sensible defaults for cloud provider settings and agent configurations.

```bash
clawup init
```

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

### Environment Variable Configuration for API Keys

Source: https://context7.com/stepandel/clawup/llms.txt

Sets up environment variables for various API keys required by Clawup for different services. This includes keys for OpenAI, Google Gemini, Tailscale, Hetzner Cloud, Brave Search, and agent-specific integrations like Slack, Linear, and GitHub.

```env
# OpenAI API key (if using OpenAI models)
OPENAI_API_KEY=sk-xxxxx

# Google Gemini API key (if using Google models)
GOOGLE_API_KEY=xxxxx

# Tailscale auth key (required for cloud deployments)
# Generate at: https://login.tailscale.com/admin/settings/keys
# Enable both "Reusable" and "Ephemeral"
TAILSCALE_AUTH_KEY=tskey-auth-xxxxx

# Tailscale API key for cleanup during destroy (optional but recommended)
TAILSCALE_API_KEY=tskey-api-xxxxx

# Tailnet DNS name (e.g., tail12345.ts.net)
TAILNET_DNS_NAME=tail12345.ts.net

# Hetzner Cloud token (required for hetzner provider)
HCLOUD_TOKEN=xxxxx

# Brave Search API key (if using brave-search dep)
BRAVE_API_KEY=BSAxxxxx

# =============================================================================
# Per-Agent Secrets (prefix with ROLE_)
# =============================================================================

# PM Agent - Slack integration
PM_SLACK_BOT_TOKEN=xoxb-xxxxx
PM_SLACK_APP_TOKEN=xapp-xxxxx

# PM Agent - Linear integration
PM_LINEAR_API_KEY=lin_api_xxxxx

# Eng Agent - GitHub integration
ENG_GITHUB_TOKEN=ghp_xxxxx

# Researcher Agent - Custom secrets
RESEARCHER_NOTION_API_KEY=secret_xxxxx
```

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

### Clawup CLI Global Options

Source: https://github.com/stepandel/clawup/blob/main/docs/cli/overview.mdx

Shows how to use global options with the Clawup CLI to display version information or help documentation for the CLI and its commands.

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

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

### SOUL.md - Agent Personality (Markdown)

Source: https://github.com/stepandel/clawup/blob/main/docs/guides/creating-identities.mdx

Defines the agent's personality, core truths, superpowers, boundaries, and overall vibe using Markdown. This file guides the agent's behavior and communication style.

```markdown
# SOUL.md - Who You Are

_You're not a chatbot. You're a researcher who finds signal in noise._

## Core Truths
**Depth over breadth.** You don't skim — you dig...

## Your Superpowers
- **Source evaluation:** You can assess credibility...

## Boundaries
- Don't present opinions as facts...

## Vibe
Curious, thorough, intellectually honest.

## Continuity
Each session, you wake up fresh. These files _are_ your memory.
```

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

### Clawup Project Structure Overview

Source: https://github.com/stepandel/clawup/blob/main/packages/cli/README.md

This text-based representation outlines the directory structure of a Clawup project, highlighting key directories like `commands`, `tools`, `lib`, and `adapters` within the `packages/cli` module. It shows where different functionalities, such as command handlers, tool implementations, and utilities, are located.

```text
my-project/
├── clawup.yaml          # Deployment manifest (created by clawup init)
├── .clawup/             # Pulumi state, workspace files (git-ignored)
└── ...

packages/cli/
├── bin.ts              # Entry point (Commander.js program)
├── commands/           # Command handlers (init, deploy, ssh, secrets, push, webhooks, etc.)
├── tools/              # Tool implementations (adapter-based: deploy, destroy, redeploy, status, validate, push, webhooks)
├── lib/                # CLI-only utilities
│   ├── config.ts       # Load/save clawup.yaml manifest
│   ├── constants.ts    # CLI-specific constants
│   ├── env.ts          # .env parser, ${env:VAR} resolver, secret builder
│   ├── exec.ts         # Shell command execution
│   ├── prerequisites.ts # Prerequisite checks
│   ├── process.ts      # Graceful shutdown handling
│   ├── project.ts      # Project root finder
│   ├── pulumi.ts       # Pulumi stack & config operations
│   ├── tailscale.ts    # Tailscale device management
│   ├── tool-helpers.ts # Shared helpers for tool implementations
│   ├── ui.ts           # UI helpers (banners, spinners, formatting)
│   ├── update-check.ts # Update notification system
│   ├── vendor.ts       # Vendor utilities
│   └── workspace.ts    # Workspace file management
└── adapters/           # Runtime adapters (CLI vs API)

# Shared types, constants, and registries live in @clawup/core (packages/core/)

```

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

### Pulumi Configuration and Management

Source: https://context7.com/stepandel/clawup/llms.txt

Demonstrates how to manage secrets and stack state using Pulumi, an alternative to direct environment variable management for Clawup secrets. Includes commands for setting secrets, viewing stack state, and refreshing the infrastructure state.

```bash
# Direct Pulumi config management (alternative to clawup secrets)
pulumi config set --secret anthropicApiKey sk-ant-xxxxx
pulumi config set --secret tailscaleAuthKey tskey-auth-xxxxx
pulumi config set tailnetDnsName tail12345.ts.net

# View Pulumi stack state
pulumi stack

# Refresh state from cloud
pulumi refresh

# Cancel locked operations
pulumi cancel
```

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

### Clawup .env.example File Structure

Source: https://github.com/stepandel/clawup/blob/main/docs/configuration/environment.mdx

This bash snippet shows the content of the `.env.example` file generated by `clawup init`. It lists all required environment variable names with empty values, organized by scope, serving as a template for the actual `.env` file.

```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=
```

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

### Common Pulumi and Clawup Troubleshooting Commands

Source: https://context7.com/stepandel/clawup/llms.txt

Offers solutions for common issues encountered during Clawup deployments, specifically addressing Pulumi state locks and synchronization problems. It also includes a command for performing a clean redeployment.

```bash
# Pulumi state locked - release lock
pulumi cancel

# Pulumi state out of sync - refresh from cloud
pulumi refresh

# Clean rebuild when in-place update fails
clawup destroy -y && clawup deploy -y
```

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

### Agent Debugging Commands for Clawup

Source: https://context7.com/stepandel/clawup/llms.txt

Provides essential bash commands for debugging AI agents deployed with Clawup. These commands allow checking cloud-init logs, gateway status and logs, Tailscale status, and Docker container status directly on the agent instances.

```bash
# Check cloud-init progress
clawup ssh pm 'sudo cat /var/log/cloud-init-output.log | tail -100'

# Check OpenClaw gateway status
clawup ssh pm 'openclaw gateway status'

# View gateway logs
clawup ssh pm 'journalctl -u openclaw -n 50'

# Restart gateway
clawup ssh pm 'openclaw gateway restart'

# Check Tailscale status
clawup ssh pm 'tailscale status'

# Verify Docker is running
clawup ssh pm 'docker ps'
```

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

### Clawup CLI Local Docker Mode Commands

Source: https://github.com/stepandel/clawup/blob/main/docs/cli/overview.mdx

Demonstrates how to use the `--local` flag with various Clawup CLI commands to target local Docker containers instead of cloud infrastructure.

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

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

### Hetzner Cloud Provider Configuration

Source: https://context7.com/stepandel/clawup/llms.txt

Sets the Hetzner API token in the .env file and defines manifest settings for Hetzner deployments. This includes specifying the region and instance type suitable for Hetzner Cloud.

```bash
# Set Hetzner token in .env
HCLOUD_TOKEN=xxxxx
```

```yaml
provider: hetzner
region: fsn1  # fsn1, nbg1, hel1 (EU) or ash (US)
instanceType: cx22  # cx22 (~$4/mo), cx32 (~$7/mo), cx42 (~$14/mo)
# US locations use cpx types: cpx21, cpx31, cpx41
```

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

### config show

Source: https://github.com/stepandel/clawup/blob/main/docs/cli/config.mdx

View the current deployment configuration. The output can be formatted as JSON.

```APIDOC
## GET /config/show

### Description
Retrieves the current deployment configuration.

### Method
GET

### Endpoint
/config/show

### Query Parameters
- **json** (boolean) - Optional - Output the configuration as JSON.

### Request Example
```bash
clawup config show
clawup config show --json
```

### Response
#### Success Response (200)
- **config** (object) - The current deployment configuration.

#### Response Example
```json
{
  "config": {
    "region": "us-west-2",
    "instanceType": "t3.large",
    "templateVars": {
      "LINEAR_TEAM": "ENG"
    },
    "agents": {
      "titus": {
        "instanceType": "cx32"
      },
      "scout": {
        "volumeSize": 50
      }
    }
  }
}
```
```

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

### Manage Linear Tickets with CLI Commands

Source: https://github.com/stepandel/clawup/blob/main/docs/integrations/linear.mdx

This snippet demonstrates common Linear CLI commands used by agents to manage tickets. It covers listing, viewing, updating, and creating tickets, including sub-tasks. These commands are essential for agents interacting with Linear for task management.

```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
```

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

### Target a Single Agent for Configuration Push

Source: https://context7.com/stepandel/clawup/llms.txt

Targets a specific agent, 'juno', for pushing workspace configurations. This allows for granular updates to individual agents within the system.

```bash
clawup push --workspace -a juno
```

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

### Custom Identity Configuration (YAML)

Source: https://github.com/stepandel/clawup/blob/main/docs/agents/juno.mdx

Illustrates how to customize Juno's identity by pointing to a forked or custom identity repository. This YAML snippet shows how to update the 'identity' field in the agent's manifest to use a new source.

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

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

### Show Clawup Configuration

Source: https://github.com/stepandel/clawup/blob/main/docs/cli/config.mdx

Displays the current clawup deployment configuration. Supports JSON output for programmatic access. No external dependencies are required.

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

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

### Slack App Manifest Configuration (JSON)

Source: https://github.com/stepandel/clawup/blob/main/docs/integrations/slack.mdx

Defines the configuration for a Slack application, including its display name, description, features (like bot user, app home, and slash commands), OAuth scopes for bot and user tokens, and event subscription settings. This manifest is crucial for setting up and customizing Slack app functionality.

```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"
      ]
    }
  }
}
```

```json
{
  "display_information": {
    "name": "Titus (Engineer)",
    "description": "Slack connector for OpenClaw"
  },
  "features": {
    "bot_user": {
      "display_name": "Titus",
      "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"
      ]
    }
  }
}
```

```json
{
  "display_information": {
    "name": "Scout (QA)",
    "description": "Slack connector for OpenClaw"
  },
  "features": {
    "bot_user": {
      "display_name": "Scout",
      "always_online": false
    },
    "app_home": {
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    }
  }
}
```

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

### Identity Structure Directory

Source: https://github.com/stepandel/clawup/blob/main/docs/guides/creating-identities.mdx

Illustrates the directory structure of a Clawup identity, including the required identity.yaml manifest and optional workspace files and skills.

```tree
my-identity/
├── identity.yaml       # Manifest (required)
├── SOUL.md             # Personality, approach, boundaries
├── IDENTITY.md         # Name, role, emoji
├── HEARTBEAT.md        # Periodic tasks
├── TOOLS.md            # Tool reference for the agent
├── AGENTS.md           # Operational instructions
├── BOOTSTRAP.md        # First-run setup checks
├── USER.md             # Owner info (templated)
└── skills/             # Bundled skills
    └── my-skill/
        └── SKILL.md
```

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

### Push Local Configuration and Restart Gateway

Source: https://context7.com/stepandel/clawup/llms.txt

Pushes the local openclaw.json configuration and restarts the gateway. This command is essential for applying local changes to the running system.

```bash
clawup push --config-push
```

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

### Configure Linear API Keys in .env

Source: https://github.com/stepandel/clawup/blob/main/docs/integrations/linear.mdx

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 ClawUp to authenticate with Linear and manage tickets.

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

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

### Set Top-Level Configuration Values

Source: https://context7.com/stepandel/clawup/llms.txt

Updates top-level configuration values in the manifest with validation. This command does not re-run the initialization process.

```bash
clawup config set region us-west-2
clawup config set instanceType t3.large
clawup config set ownerName "John Doe"
clawup config set timezone "America/Los_Angeles"
clawup config set workingHours "8am-5pm"
```

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

### Troubleshoot OpenClaw Gateway Status and Logs

Source: https://github.com/stepandel/clawup/blob/main/README.md

Commands to check the status, view recent logs, and restart the OpenClaw gateway on a remote agent via SSH. These commands are useful for diagnosing issues with the gateway service.

```bash
clawup ssh <agent> 'openclaw gateway status'
clawup ssh <agent> 'journalctl -u openclaw -n 50'
clawup ssh <agent> 'openclaw gateway restart'
```

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

### Define Skill Metadata in SKILL.md

Source: https://github.com/stepandel/clawup/blob/main/docs/guides/creating-identities.mdx

Skills are defined in `skills/<skill-name>/SKILL.md` using YAML frontmatter. This frontmatter includes essential details like the skill's name, a description, and optional metadata such as an emoji icon and required binary dependencies.

```markdown
---
name: research-report
description: Conduct deep research and produce a structured report
metadata: {"openclaw":{"emoji":":telescope:"}}
---

# Research Report

## Inputs
The user provides a research topic via Slack or direct prompt.

## Workflow

### Phase 1: Scope
1. Parse the research request...

### Phase 2: Gather Sources
1. Search using Brave Search...

### Phase 3: Write Report
Structure as Summary → Key Findings → Analysis → Sources...

### Phase 4: Deliver
1. Save report to memory
2. Send summary via Slack

```

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

### SKILL.md Format with YAML Frontmatter

Source: https://github.com/stepandel/clawup/blob/main/docs/architecture/identities.mdx

Defines the structure of a skill file, including YAML frontmatter for metadata and markdown for instructions. The frontmatter specifies the skill's name, description, and optional metadata like emoji and dependencies.

```markdown
---
name: research-report
description: Conduct deep research and produce a structured report
metadata: {"openclaw":{"emoji":":telescope:"}}
---

# Research Report

Step-by-step workflow instructions here...

```

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

### Identity Manifest Configuration (YAML)

Source: https://github.com/stepandel/clawup/blob/main/docs/guides/creating-identities.mdx

Defines the core and optional configurations for an identity in YAML format. Includes basic fields like name, role, and emoji, as well as advanced settings for AI models, dependencies, and plugins.

```yaml
name: researcher
displayName: Atlas
role: researcher
emoji: telescope
description: Deep research, source analysis, report generation
volumeSize: 20
skills:
  - research-report
templateVars:
  - OWNER_NAME
  - TIMEZONE
  - WORKING_HOURS
  - USER_NOTES
```

```yaml
# AI model (defaults to the stack's model if omitted)
model: anthropic/claude-sonnet-4-5
backupModel: anthropic/claude-haiku-4-5
codingAgent: claude-code

# System dependencies installed on the agent
deps:
  - brave-search

# OpenClaw plugins
plugins:
  - slack

# Per-plugin default configuration
pluginDefaults:
  slack:
    mode: socket
    dm:
      enabled: true
      policy: open

# Additional secrets not covered by plugins/deps
requiredSecrets:
  - notionApiKey
```

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

### ClawUp Manifest Configuration (clawup.yaml)

Source: https://github.com/stepandel/clawup/blob/main/README.md

The `clawup.yaml` file serves as the manifest for driving the entire deployment. It defines stack name, provider, region, instance types, and agent configurations, including secrets loaded from environment variables.

```yaml
stackName: dev
provider: aws
region: us-east-1
instanceType: t3.medium
ownerName: Your Name
timezone: America/New_York
workingHours: 9am-6pm
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
    displayName: Juno
    role: pm
    identity: "https://github.com/your-org/army-identities#pm"
    volumeSize: 30
    secrets:
      slackBotToken: "${env:PM_SLACK_BOT_TOKEN}"
      slackAppToken: "${env:PM_SLACK_APP_TOKEN}"
    plugins:
      openclaw-linear:
        agentId: agent-pm
      slack:
        mode: socket
  - name: agent-researcher
    displayName: Atlas
    role: researcher
    identity: "./my-identities/researcher"
    volumeSize: 20
```

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

### Environment Variable Configuration for Slack Tokens

Source: https://github.com/stepandel/clawup/blob/main/docs/integrations/slack.mdx

Sets up environment variables for storing Slack Bot User OAuth Token and App-Level Token. These tokens are essential for authenticating the bot and enabling Socket Mode communication with Slack.

```bash
PM_SLACK_BOT_TOKEN=xoxb-XXXXXXXXXXXX
PM_SLACK_APP_TOKEN=xapp-XXXXXXXXXXXX
```

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

### Destroy Deployed Resources with Confirmation

Source: https://context7.com/stepandel/clawup/llms.txt

Tears down all deployed resources. It includes a safety confirmation prompt by default to prevent accidental deletion. Use '-y' to skip confirmation, which is dangerous.

```bash
clawup destroy
```

```bash
clawup destroy -y
```

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

### Run Clawup Deployment

Source: https://github.com/stepandel/clawup/blob/main/docs/cli/deploy.mdx

Executes the clawup deployment command. This command provisions infrastructure and deploys an agent team using Pulumi. It can be run with or without confirmation prompts, and supports local Docker deployment.

```bash
clawup deploy [options]

```

```bash
clawup deploy --local

```

```bash
# Deploy with confirmation
clawup deploy

```

```bash
# Deploy without confirmation
clawup deploy --yes

```

```bash
# Deploy to local Docker containers
clawup deploy --local --yes

```

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

### List Configured Secrets

Source: https://context7.com/stepandel/clawup/llms.txt

Shows which secrets are configured for the current stack, with values redacted for security. It lists both global secrets and agent-specific secrets.

```bash
clawup secrets list
```

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

### Push Configuration to Local Docker Containers

Source: https://context7.com/stepandel/clawup/llms.txt

Pushes workspace configurations to local Docker containers. This is useful for testing and development environments running within Docker.

```bash
clawup push --workspace --local
```

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

### Set Template Variables

Source: https://context7.com/stepandel/clawup/llms.txt

Sets template variables that can be used for substitution in workspace files. This allows for dynamic configuration based on project needs.

```bash
clawup config set templateVars.LINEAR_TEAM "Engineering"
clawup config set templateVars.GITHUB_REPO "myorg/myrepo"
```

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

### Configure Linear Webhook Secrets in .env

Source: https://github.com/stepandel/clawup/blob/main/docs/integrations/linear.mdx

This snippet demonstrates how to add Linear webhook secrets to your .env file. These secrets are used to verify the authenticity of incoming webhooks from Linear, ensuring secure communication.

```bash
<ROLE>_LINEAR_WEBHOOK_SECRET=<your_webhook_secret>
```

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

### Update Clawup CLI

Source: https://context7.com/stepandel/clawup/llms.txt

Updates the clawup CLI to the latest available version. It's recommended to run this command periodically to ensure you have the latest features and bug fixes.

```bash
clawup update
```
Tokens:
Raw