### Install Dependencies and Run Dev Servers

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/development.md

Use these make commands to install all development dependencies and start both backend and frontend development servers.

```bash
make install-dev

make dev
```

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

### Install Claworc with Installer Script (Windows)

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/install.md

Use PowerShell to clone the repository and run the Windows installer script. This script provides an interactive setup for Docker or Kubernetes.

```powershell
git clone https://github.com/gluk-w/claworc.git
cd claworc
.
install.ps1
```

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

### First-Time Setup CLI

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/auth.md

Commands to create the initial admin user via Docker or Kubernetes when Claworc starts with an empty database.

```APIDOC
## First-Time Setup CLI

### Description
Commands to create the initial admin user via Docker or Kubernetes when Claworc starts with an empty database.

### Method
N/A (CLI Commands)

### Endpoint
N/A

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
# Docker
docker exec claworc-dashboard /app/claworc --create-admin --username admin --password <password>

# Kubernetes
kubectl exec deploy/claworc -n claworc -- /app/claworc --create-admin --username admin --password <password>
```

### Response
N/A
```

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

### Install Claworc with Installer Script (Linux/macOS)

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/install.md

Use this command to download and execute the installer script for Linux or macOS. The script guides you through Docker or Kubernetes setup.

```bash
curl -fsSL https://raw.githubusercontent.com/gluk-w/claworc/main/install.sh | bash
```

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

### GET /api/v1/auth/setup-required

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/auth.md

Checks if the initial administrator account setup is required.

```APIDOC
## GET /api/v1/auth/setup-required

### Description
Checks if the initial administrator account setup is required. This is typically used to determine if the application needs to present the first-time setup screen.

### Method
GET

### Endpoint
/api/v1/auth/setup-required

### Parameters
None

### Response
#### Success Response (200)
- **setup_required** (boolean) - True if setup is required, false otherwise.

#### Response Example
```json
{
  "setup_required": true
}
```
```

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

### Development Configuration (Authentication Disabled)

Source: https://github.com/dsactivi-2/claworc/blob/main/website/src/content/docs/docs/environment-variables.mdx

A command-line example for development setup, disabling authentication and specifying the Docker host.

```bash
CLAWORC_DATA_PATH=./data \
CLAWORC_AUTH_DISABLED=true \
CLAWORC_DOCKER_HOST=unix:///var/run/docker.sock \
./claworc
```

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

### Check Setup Status and Create Initial Admin

Source: https://context7.com/dsactivi-2/claworc/llms.txt

Check if the initial admin setup is required and create the first admin account if no users exist. This is crucial for first-time setup of the Claworc system.

```bash
# Check if first-time setup is required
curl http://localhost:8000/api/v1/auth/setup-required
```

```json
{ "setup_required": true }
```

```bash
# Create initial admin account (only works when no users exist)
curl -X POST http://localhost:8000/api/v1/auth/setup \
  -H "Content-Type: application/json" \
  -d '{
    "username": "admin",
    "password": "secure-password-123"
  }'
```

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

### Quick Start Docker Compose Up

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/deployment/docker.md

Clone the repository, navigate to the directory, create the data directory, and start the control plane using Docker Compose.

```bash
git clone https://github.com/gluk-w/claworc.git
cd claworc
mkdir -p ~/.claworc/data/configs
CLAWORC_DATA_DIR=~/.claworc/data docker compose up -d
```

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

### Install Claworc by Cloning Repo (Linux/macOS)

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/install.md

Clone the Claworc repository and run the install script locally. This method allows for local modifications before installation.

```bash
git clone https://github.com/gluk-w/claworc.git
cd claworc
bash install.sh
```

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

### Install Claworc with One-Line Installer

Source: https://github.com/dsactivi-2/claworc/blob/main/website/src/content/landing/home.mdx

Use this command to quickly install Claworc. Ensure you have curl and a shell environment.

```bash
curl -fsSL https://claworc.com/install.sh | sh
```

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

### Install Backend Dependencies

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/development.md

Installs Python dependencies for the backend using Poetry.

```bash
poetry install
```

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

### Run Frontend Development Server

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/development.md

Starts the Vite development server for the frontend.

```bash
npm run dev
```

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

### Install Frontend Dependencies

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/development.md

Installs Node.js dependencies for the frontend using npm.

```bash
npm install
```

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

### Install Mintlify CLI

Source: https://github.com/dsactivi-2/claworc/blob/main/website_docs/README.md

Installs the Mintlify Command Line Interface globally. This tool is used for previewing documentation changes locally.

```bash
npm i -g mint
```

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

### Example Project File Structure

Source: https://github.com/dsactivi-2/claworc/blob/main/website_docs/CLAUDE.md

Illustrates a typical project directory layout including configuration, documentation, API specs, assets, and snippets.

```tree
project/
├── docs.json           # Site configuration
├── introduction.mdx
├── quickstart.mdx
├── guides/
│   └── example.mdx
├── openapi.yml         # API specification
├── images/             # Static assets
│   └── example.png
└── snippets/           # Reusable components
    └── component.jsx
```

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

### Install Claworc on Linux/macOS

Source: https://github.com/dsactivi-2/claworc/blob/main/website_docs/quickstart.mdx

Use this command to download and run the Claworc installer script on Linux or macOS. Alternatively, clone the repository and run the script locally.

```bash
curl -fsSL https://raw.githubusercontent.com/gluk-w/claworc/main/install.sh | bash
```

```bash
git clone https://github.com/gluk-w/claworc.git
cd claworc
bash install.sh
```

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

### Install Claworc on Windows

Source: https://github.com/dsactivi-2/claworc/blob/main/website/src/content/docs/docs/quickstart.mdx

Clone the Claworc repository and execute the install script using PowerShell on Windows. Ensure you are using PowerShell, not Command Prompt.

```powershell
git clone https://github.com/gluk-w/claworc.git
cd claworc
.\install.ps1
```

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

### Start Local Mintlify Development Server

Source: https://github.com/dsactivi-2/claworc/blob/main/website_docs/README.md

Runs the Mintlify development server from the root of your documentation project. View your local preview at http://localhost:3000.

```bash
mint dev
```

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

### Run Backend Development Server

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/development.md

Starts the backend development server using Uvicorn, enabling hot reloading.

```bash
poetry run uvicorn backend.app:app --reload --port 8000
```

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

### Start Task API

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/kanban.md

Starts an existing task by sending a POST request to the tasks start endpoint. This changes the task status to 'todo' and triggers 'EnqueueTask'.

```http
POST /tasks/{id}/start
```

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

### Example Gateway Provider Configuration

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/virtual-keys.md

This JSON structure shows an example configuration for an Anthropic provider. It includes base URL, API type, and model-specific metadata like context window and cost.

```json
{
  "anthropic": {
    "baseUrl": "http://127.0.0.1:40001",
    "api":     "anthropic-messages",
    "apiKey":  "claworc-vk-<token>",
    "models": [
      {
        "id": "claude-sonnet-4-6",
        "name": "Claude Sonnet 4.6",
        "contextWindow": 200000,
        "maxTokens": 64000,
        "cost": {"input": 3.0, "output": 15.0, "cacheRead": 0.3, "cacheWrite": 3.75}
      }
    ]
  }
}
```

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

### Start Claude Code

Source: https://github.com/dsactivi-2/claworc/blob/main/website/src/content/docs/docs/ai-tools/claude-code.mdx

Launch the Claude Code interactive command-line interface to begin writing documentation.

```bash
claude
```

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

### Install Claworc with Custom Values

Source: https://github.com/dsactivi-2/claworc/blob/main/website/src/content/docs/docs/installation.mdx

Install the Claworc Helm chart using a custom values file and specify the namespace. Ensure the namespace is created if it doesn't exist.

```bash
helm install claworc helm/ \
  --namespace claworc \
  --create-namespace \
  -f custom-values.yaml
```

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

### Start Claworc with Docker Compose

Source: https://github.com/dsactivi-2/claworc/blob/main/website/src/content/docs/docs/installation.mdx

Start the Claworc services using Docker Compose. The CLAWORC_DATA_DIR environment variable must be set to point to the data directory. Alternatively, create a .env file.

```bash
CLAWORC_DATA_DIR=~/.claworc/data docker compose up -d
```

```bash
echo "CLAWORC_DATA_DIR=$HOME/.claworc/data" > .env
docker compose up -d
```

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

### Install Claworc with Helm Chart

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/install.md

Install the Claworc Helm chart into a specified Kubernetes namespace. This command creates the namespace if it does not exist.

```bash
helm install claworc helm/ \
  --namespace claworc \
  --create-namespace
```

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

### Install Claworc Helm chart

Source: https://github.com/dsactivi-2/claworc/blob/main/website/src/content/docs/docs/installation.mdx

Install the Claworc Helm chart into a Kubernetes cluster. Specify the namespace and optionally the kubeconfig path if it's not default.

```bash
helm install claworc helm/ \
  --namespace claworc \
  --create-namespace
```

```bash
helm install claworc helm/ \
  --namespace claworc \
  --create-namespace \
  --kubeconfig /path/to/kubeconfig
```

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

### Get Global Settings

Source: https://context7.com/dsactivi-2/claworc/llms.txt

Retrieves the current global system settings and default configurations.

```bash
curl http://localhost:8000/api/v1/settings \
  -b cookies.txt
```

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

### Verify RBAC in Kubernetes for Agent Startup Issues

Source: https://github.com/dsactivi-2/claworc/blob/main/website/src/content/docs/docs/installation.mdx

Check the RoleBinding in the 'claworc' namespace to ensure the agent has the necessary permissions to start.

```bash
kubectl get rolebinding -n claworc
```

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

### Start Claworc with Docker Compose

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/install.md

Start the Claworc services in detached mode using Docker Compose. Ensure the `CLAWORC_DATA_DIR` environment variable is set.

```bash
CLAWORC_DATA_DIR=~/.claworc/data docker compose up -d
```

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

### Deploy to Kubernetes using Helm

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/development.md

Commands for installing, upgrading, and templating Kubernetes deployments via Helm.

```bash
make helm-install
make helm-upgrade
make helm-template
```

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

### Regular Navigation Structure

Source: https://github.com/dsactivi-2/claworc/blob/main/website_docs/essentials/navigation.mdx

Defines a basic navigation structure with a single tab and a getting started group.

```json
"navigation": {
  "tabs": [
    {
      "tab": "Docs",
      "groups": [
        {
          "group": "Getting Started",
          "pages": ["quickstart"]
        }
      ]
    }
  ]
}
```

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

### SSH Proxy Package Initialization

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/development.md

Demonstrates the initialization steps for the SSH proxy package, including key pair generation, SSH manager creation, and tunnel manager setup.

```go
import "github.com/gluk-w/claworc/control-plane/internal/sshproxy"

// 1. Ensure the SSH key pair exists (generates on first run)
sshSigner, sshPublicKey, err := sshproxy.EnsureKeyPair(config.Cfg.DataPath)

// 2. Create the SSH connection manager
sshMgr := sshproxy.NewSSHManager(sshSigner, sshPublicKey)

// 3. Create the tunnel manager (depends on SSHManager)
tunnelMgr := sshproxy.NewTunnelManager(sshMgr)

// 4. Start background reconciliation (maintains tunnels for running instances)
tunnelMgr.StartBackgroundManager(ctx, listRunningInstances, orch)
```

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

### Reset Claworc Installation (Kubernetes)

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/install.md

For a fresh start on Kubernetes, delete the persistent volume claim for data and then restart the Claworc deployment.

```bash
kubectl delete pvc claworc-data -n claworc
kubectl rollout restart deploy/claworc -n claworc
```

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

### Build Frontend for Production

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/development.md

Creates a production-ready build of the frontend application.

```bash
npm run build
```

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

### Verify Docker Compose installation

Source: https://github.com/dsactivi-2/claworc/blob/main/website/src/content/docs/docs/installation.mdx

Check if Claworc is running correctly after starting with Docker Compose. Stream logs or check the health endpoint.

```bash
docker compose logs -f
curl http://localhost:8000/health
```

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

### POST /api/v1/auth/setup

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/auth.md

Creates the initial administrator account. This endpoint should only be called when no users exist in the system.

```APIDOC
## POST /api/v1/auth/setup

### Description
Creates the initial administrator account. This endpoint should only be called when no users exist in the system. It is used during the first-time setup process.

### Method
POST

### Endpoint
/api/v1/auth/setup

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **username** (string) - Required - The desired username for the admin account.
- **password** (string) - Required - The desired password for the admin account.

### Request Example
```json
{
  "username": "admin",
  "password": "securepassword123"
}
```

### Response
#### Success Response (200)
- **message** (string) - Confirmation message indicating successful admin creation.

#### Response Example
```json
{
  "message": "Admin account created successfully."
}
```
```

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

### Useful Docker Compose commands

Source: https://github.com/dsactivi-2/claworc/blob/main/website/src/content/docs/docs/installation.mdx

Common commands for managing Claworc services when installed with Docker Compose, including logging, stopping, starting, and upgrading.

```bash
docker compose logs -f           # Stream logs
docker compose down              # Stop
docker compose up -d             # Start
docker compose pull && docker compose up -d   # Upgrade to latest image
docker compose down -v           # Stop and delete volumes (destructive)
```

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

### Instance Lifecycle Operations

Source: https://context7.com/dsactivi-2/claworc/llms.txt

Perform lifecycle operations on an AI agent instance, such as getting details, starting, stopping, restarting, or deleting it. Requires administrator privileges for deletion.

```bash
# Get instance details
curl http://localhost:8000/api/v1/instances/1 \
  -b cookies.txt
```

```bash
# Start a stopped instance
curl -X POST http://localhost:8000/api/v1/instances/1/start \
  -b cookies.txt
```

```bash
# Stop a running instance
curl -X POST http://localhost:8000/api/v1/instances/1/stop \
  -b cookies.txt
```

```bash
# Restart an instance (rebuilds container with current config)
curl -X POST http://localhost:8000/api/v1/instances/1/restart \
  -b cookies.txt
```

```json
{ "status": "running" }  # or "stopping", "restarting"
```

```bash
# Delete an instance (admin only)
curl -X DELETE http://localhost:8000/api/v1/instances/1 \
  -b cookies.txt
```

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

### List and Create Instances

Source: https://context7.com/dsactivi-2/claworc/llms.txt

List all AI agent instances accessible by the current user or create a new instance. Instance creation is restricted to administrators.

```bash
# List all instances (filtered by role - users see only assigned instances)
curl http://localhost:8000/api/v1/instances \
  -b cookies.txt
```

```json
[
  {
    "id": 1,
    "name": "bot-research-agent",
    "display_name": "Research Agent",
    "status": "running",
    "cpu_request": "500m",
    "cpu_limit": "2000m",
    "memory_request": "1Gi",
    "memory_limit": "4Gi",
    "storage_homebrew": "10Gi",
    "storage_home": "10Gi",
    "default_model": "anthropic/claude-sonnet-4-20250514",
    "control_url": "/openclaw/1/",
    "created_at": "2025-01-15T10:30:00Z"
  }
]
```

```bash
# Create a new instance (admin only)
curl -X POST http://localhost:8000/api/v1/instances \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "display_name": "Data Analysis Bot",
    "cpu_request": "1000m",
    "cpu_limit": "4000m",
    "memory_request": "2Gi",
    "memory_limit": "8Gi",
    "storage_home": "20Gi",
    "default_model": "anthropic/claude-sonnet-4-20250514",
    "enabled_providers": [1, 2],
    "env_vars_set": {
      "CUSTOM_VAR": "value"
    }
  }'
```

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

### Reset Claworc Installation Data (Docker)

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/install.md

To reset the Claworc installation on Docker without uninstalling, remove the dashboard container and delete the local database file. You can then re-run the installation script or docker compose up.

```bash
docker rm -f claworc-dashboard
rm -f ~/.claworc/data/claworc.db
# Re-run install.sh or docker compose up
```

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

### Start Docker Compose Services

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/install.md

Start the services defined in the `docker-compose.yml` file in detached mode.

```bash
docker compose up -d
```

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

### Install Claude Code CLI

Source: https://github.com/dsactivi-2/claworc/blob/main/website/src/content/docs/docs/ai-tools/claude-code.mdx

Install the Claude Code command-line interface globally using npm.

```bash
npm install -g @anthropic-ai/claude-code
```

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

### Create Admin Account CLI

Source: https://github.com/dsactivi-2/claworc/blob/main/website/src/content/docs/docs/authentication.mdx

Use these commands to create the initial admin account from the CLI. This is an alternative to the initial web form.

```bash
# Docker Compose
docker compose exec claworc ./claworc --create-admin
```

```bash
# Kubernetes
kubectl exec -n claworc deploy/claworc -- ./claworc --create-admin
```

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

### Create Kanban Board

Source: https://context7.com/dsactivi-2/claworc/llms.txt

Creates a new Kanban board. Provide a name, description, and a list of eligible instance IDs.

```bash
curl -X POST http://localhost:8000/api/v1/kanban/boards \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "name": "Development Tasks",
    "description": "Tasks for the dev team",
    "eligible_instances": [1, 2, 3]
  }'
```

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

### Kubernetes Client Integration

Source: https://github.com/dsactivi-2/claworc/blob/main/CLAUDE.md

Demonstrates the use of the official Go client-go library for Kubernetes integration. It prioritizes in-cluster configuration and falls back to kubeconfig for local development.

```go
package kubernetes

import (
	"context"

	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
	"k8s.io/client-go/kubernetes"
	"k8s.io/client-go/rest"
	"k8s.io/client-go/tools/clientcmd"
	"k8s.io/client-go/util/homedir"

	"github.com/clawarc/claworc/internal/config"
)

type Kubernetes struct {
	clientset *kubernetes.Clientset
	config    *rest.Config
	namespace string
}

func New(cfg *config.Config) (*Kubernetes, error) {
	var config *rest.Config
	var err error

	// Try in-cluster config first
	config, err = rest.InClusterConfig()
	if err != nil {
		// Fallback to kubeconfig for local development
		kubeconfigPath := os.Getenv("KUBECONFIG")
		if kubeconfigPath == "" {
			kubeconfigPath = filepath.Join(homedir.HomeDir(), ".kube", "config")
		}
		config, err = clientcmd.BuildConfigFromFlags("", kubeconfigPath)
		if err != nil {
			return nil, fmt.Errorf("failed to build kubeconfig: %w", err)
		}
	}

	clientset, err := kubernetes.NewForConfig(config)
	if err != nil {
		return nil, fmt.Errorf("failed to create kubernetes clientset: %w", err)
	}

	return &Kubernetes{
		clientset: clientset,
		config:    config,
		namespace: cfg.K8sNamespace,
	},
		nil
}

func (k *Kubernetes) ListPods(ctx context.Context) ([]string, error) {
	pods, err := k.clientset.CoreV1().Pods(k.namespace).List(ctx, metav1.ListOptions{})
	if err != nil {
		return nil, fmt.Errorf("failed to list pods: %w", err)
	}

	var podNames []string
	for _, pod := range pods.Items {
		podNames = append(podNames, pod.Name)
	}

	return podNames,
		nil
}
```

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

### POST /api/v1/auth/webauthn/login/begin

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/auth.md

Initiates the WebAuthn (passkey) login process.

```APIDOC
## POST /api/v1/auth/webauthn/login/begin

### Description
Initiates the WebAuthn (passkey) login process. This endpoint is called to start the authentication flow using a registered passkey.

### Method
POST

### Endpoint
/api/v1/auth/webauthn/login/begin

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **username** (string) - Required - The username of the user attempting to log in.

### Request Example
```json
{
  "username": "testuser"
}
```

### Response
#### Success Response (200)
- **challenge** (string) - A challenge string to be used in the next step of the WebAuthn authentication.
- **options** (object) - WebAuthn options required by the client to initiate the authenticator.
  - **rpId** (string) - The relying party ID.
  - **allowCredentials** (array) - List of allowed credential IDs.
  - **userVerification** (string) - Specifies whether user verification is required.

#### Response Example
```json
{
  "challenge": "some_base64_encoded_challenge",
  "options": {
    "rpId": "localhost",
    "allowCredentials": [
      {
        "id": "some_credential_id",
        "type": "public-key"
      }
    ],
    "userVerification": "required"
  }
}
```
```

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

### Direct Gateway Call Example

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/virtual-keys.md

This example demonstrates how to call the Claworc gateway directly from the control plane host. The gateway will proxy the request and substitute the Authorization header.

```APIDOC
## POST /v1/chat/completions

### Description
This endpoint is used to send chat completions requests to the gateway. The gateway proxies these requests to upstream providers and logs the usage.

### Method
POST

### Endpoint
http://127.0.0.1:40001/v1/chat/completions

### Request Body
- **model** (string) - Required - The model to use for the chat completion.
- **messages** (array) - Required - An array of message objects.
  - **role** (string) - Required - The role of the message sender (e.g., "user", "assistant").
  - **content** (string) - Required - The content of the message.

### Request Example
```json
{
  "model": "test",
  "messages": [
    {
      "role": "user",
      "content": "hi"
    }
  ]
}
```

### Headers
- **Authorization**: Bearer [your_api_key]
- **Content-Type**: application/json
```

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

### Create Instance with Environment Variables

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/environment-variables.md

Used to create a new instance, allowing the specification of environment variables to be set.

```json
{
  "display_name": "Bot Alpha",
  "env_vars_set": {"MY_TOKEN": "plaintext"}
}
```

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

### Create Directory

Source: https://context7.com/dsactivi-2/claworc/llms.txt

Create a new directory on an instance. The 'path' parameter specifies the location and name of the new directory.

```bash
# Create a directory
curl -X POST http://localhost:8000/api/v1/instances/1/files/mkdir \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{"path": "/home/claworc/new-project"}'
```

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

### Authentication API

Source: https://context7.com/dsactivi-2/claworc/llms.txt

Endpoints for user authentication, including login, logout, and setup.

```APIDOC
## POST /api/v1/auth/login

### Description
Logs in a user with username and password, returning session cookies.

### Method
POST

### Endpoint
/api/v1/auth/login

### Request Body
- **username** (string) - Required - The user's username.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "username": "admin",
  "password": "your-password"
}
```

### Response
#### Success Response (200)
- **user** (object) - Information about the logged-in user.
  - **id** (integer) - User ID.
  - **username** (string) - Username.
  - **role** (string) - User role (e.g., "admin").

#### Response Example
```json
{
  "user": {
    "id": 1,
    "username": "admin",
    "role": "admin"
  }
}
```
```

```APIDOC
## GET /api/v1/auth/setup-required

### Description
Checks if the initial administrator account setup is required.

### Method
GET

### Endpoint
/api/v1/auth/setup-required

### Response
#### Success Response (200)
- **setup_required** (boolean) - True if setup is required, false otherwise.

#### Response Example
```json
{ "setup_required": true }
```
```

```APIDOC
## POST /api/v1/auth/setup

### Description
Creates the initial administrator account. This endpoint only works when no users exist.

### Method
POST

### Endpoint
/api/v1/auth/setup

### Request Body
- **username** (string) - Required - The desired username for the admin account.
- **password** (string) - Required - The desired password for the admin account.

### Request Example
```json
{
  "username": "admin",
  "password": "secure-password-123"
}
```
```

```APIDOC
## GET /api/v1/auth/me

### Description
Retrieves details of the currently authenticated user.

### Method
GET

### Endpoint
/api/v1/auth/me

### Response
#### Success Response (200)
- **id** (integer) - User ID.
- **username** (string) - Username.
- **role** (string) - User role.

#### Response Example
```json
{
  "id": 1,
  "username": "admin",
  "role": "admin"
}
```
```

```APIDOC
## POST /api/v1/auth/logout

### Description
Logs out the currently authenticated user.

### Method
POST

### Endpoint
/api/v1/auth/logout
```

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

### Configure Passkey Relying Party Settings

Source: https://github.com/dsactivi-2/claworc/blob/main/website/src/content/docs/docs/authentication.mdx

Set the Relying Party settings for passkeys to match your domain. Ensure `CLAWORC_RP_ID` matches the domain for successful registration in production.

```bash
CLAWORC_RP_ORIGINS=https://claworc.example.com
CLAWORC_RP_ID=claworc.example.com
```

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

### API Endpoint Structure (Manual)

Source: https://github.com/dsactivi-2/claworc/blob/main/website_docs/CLAUDE.md

Example structure for manually documenting an API endpoint.

```APIDOC
## POST /api/users

### Description

Creates a new user in the system.

### Method

POST

### Endpoint

/api/users

### Parameters

#### Request Body

- **username** (string) - Required - The desired username for the new user.
- **email** (string) - Required - The email address for the user.
- **password** (string) - Required - The user's password.

### Request Example

```json
{
  "username": "johndoe",
  "email": "john.doe@example.com",
  "password": "securepassword123"
}
```

### Response

#### Success Response (201)

- **id** (string) - The unique identifier for the newly created user.
- **username** (string) - The username of the created user.
- **email** (string) - The email address of the created user.

#### Response Example

```json
{
  "id": "usr_123abc",
  "username": "johndoe",
  "email": "john.doe@example.com"
}
```
```

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

### Create a Test Provider

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/virtual-keys.md

This `curl` command creates a new provider with a specified key, name, and base URL pointing to httpbin.org for testing purposes. Note the returned `id` for subsequent operations.

```bash
curl -s -X POST http://localhost:8080/api/v1/providers \
  -H 'Content-Type: application/json' \
  -d '{"key":"test","name":"Test","base_url":"https://httpbin.org/anything"}'
```

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

### Get Audit Logs

Source: https://context7.com/dsactivi-2/claworc/llms.txt

Retrieves audit logs with a specified limit. Requires authentication.

```bash
curl "http://localhost:8000/api/v1/audit-logs?limit=100" \
  -b cookies.txt
```

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

### Skill format example

Source: https://github.com/dsactivi-2/claworc/blob/main/website/src/content/docs/docs/skills.mdx

This markdown file defines a skill's metadata and instructions. Ensure the YAML frontmatter includes 'name' and 'description'. The agent follows the Markdown instructions.

```markdown
---
name: "Web researcher"
description: "Searches the web and summarizes findings"
---

When asked to research a topic, search the web for recent sources
and compile a concise summary with citations.
```

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

### Start Kanban Task Processing

Source: https://context7.com/dsactivi-2/claworc/llms.txt

Initiates AI processing for a task. Requires the task ID.

```bash
curl -X POST http://localhost:8000/api/v1/kanban/tasks/1/start \
  -b cookies.txt
```

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

### Get Tunnel Status

Source: https://context7.com/dsactivi-2/claworc/llms.txt

Retrieves the status of tunnels (VNC, gateway) for an instance. Requires authentication.

```bash
curl http://localhost:8000/api/v1/instances/1/tunnels \
  -b cookies.txt
```

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

### Import and use a basic snippet

Source: https://github.com/dsactivi-2/claworc/blob/main/website_docs/essentials/reusable-snippets.mdx

Import a snippet from the `snippets` directory into your destination file and use it as a component, passing any necessary props.

```mdx
---
title: My title
description: My Description
---

import MySnippet from '/snippets/path/to/my-snippet.mdx';

## Header

Lorem impsum dolor sit amet.

<MySnippet word="bananas" />
```

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

### Get Shared Folder Details

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/shared-folders.md

Retrieves detailed information about a specific shared folder by its ID.

```APIDOC
## GET /shared-folders/{id}

### Description
Retrieves the details of a specific shared folder using its unique ID.

### Method
GET

### Endpoint
/shared-folders/{id}

### Parameters
#### Path Parameters
- **id** (uint) - Required - The unique identifier of the shared folder.

### Request Example
None

### Response
#### Success Response (200)
- **id** (uint) - Primary key of the shared folder.
- **name** (string) - User-visible folder name.
- **mount_path** (string) - Container mount path.
- **owner_id** (uint) - User ID of the folder creator.
- **instance_ids** (string) - JSON array of instance IDs mapped to this folder.
- **created_at** (datetime) - Creation timestamp.
- **updated_at** (datetime) - Last update timestamp.

#### Response Example
```json
{
  "id": 1,
  "name": "Shared Data",
  "mount_path": "/shared/data",
  "owner_id": 1,
  "instance_ids": "[1, 3]",
  "created_at": "2026-04-03T10:00:00Z",
  "updated_at": "2026-04-03T10:00:00Z"
}
```
```

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

### Create Directory

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/file-browser.md

Creates a new directory, including any necessary parent directories.

```shell
mkdir -p <path>
```

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

### Get Global Environment Variables

Source: https://github.com/dsactivi-2/claworc/blob/main/docs/environment-variables.md

Retrieves the plaintext global environment variables. This endpoint is admin-only.

```json
{
  "...": "...other settings...",
  "default_env_vars": {
    "SLACK_TOKEN": "xoxb-...",
    "TEAM_NAME": "engineering"
  }
}
```

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

### Navigation with Folder Structure

Source: https://github.com/dsactivi-2/claworc/blob/main/website_docs/essentials/navigation.mdx

Shows how to map folder structures to navigation paths in docs.json.

```json
"navigation": {
  "tabs": [
    {
      "tab": "Docs",
      "groups": [
        {
          "group": "Group Name",
          "pages": ["your-folder/your-page"]
        }
      ]
    }
  ]
}
```

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

### Create User

Source: https://context7.com/dsactivi-2/claworc/llms.txt

Adds a new user to the system. Requires username, password, and role. This is an administrative action.

```bash
curl -X POST http://localhost:8000/api/v1/users \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "username": "newuser",
    "password": "secure-password",
    "role": "user"
  }'
```

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

### Markdown Multiline Blockquote

Source: https://github.com/dsactivi-2/claworc/blob/main/website_docs/essentials/markdown.mdx

Use '>' at the start of each line for multiline blockquotes, including blank lines between paragraphs.

```markdown
> Dorothy followed her through many of the beautiful rooms in her castle.
>
> The Witch bade her clean the pots and kettles and sweep the floor and keep the fire fed with wood.
```