### 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 ``` -------------------------------- ### 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 # → _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 ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### 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`. ``` -------------------------------- ### 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 ``` -------------------------------- ### 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= --ssh --hostname=- ``` -------------------------------- ### 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 --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/) ``` -------------------------------- ### 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" } ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### 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 ``` -------------------------------- ### 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= ``` -------------------------------- ### 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 ```