### Install and Initialize LobsterBoard Agent

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

Install the lobsterboard-agent globally, initialize it to generate an API key, and start the agent server.

```bash
npm install -g lobsterboard-agent
lobsterboard-agent init
lobsterboard-agent serve
```

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

### Install and Run LobsterBoard via npm

Source: https://github.com/curbob/lobsterboard/blob/main/index.html

Commands to install the package and start the server locally.

```bash
$ npm install lobsterboard
$ cd node_modules/lobsterboard
$ node server.cjs
```

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

### Install and Run LobsterBoard (npm)

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

Install LobsterBoard using npm and run the server. Access the dashboard at http://localhost:8080.

```bash
npm install lobsterboard
cd node_modules/lobsterboard
node server.cjs
```

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

### Start LobsterBoard via CLI

Source: https://github.com/curbob/lobsterboard/blob/main/pages/README.md

Commands to navigate to the project folder and start the development server.

```bash
cd your-project
npm start
```

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

### Clone and Install Dependencies

Source: https://github.com/curbob/lobsterboard/blob/main/CONTRIBUTING.md

Clone the LobsterBoard repository and install necessary npm packages.

```bash
git clone https://github.com/YOUR_USERNAME/LobsterBoard.git
cd LobsterBoard
npm install
```

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

### Custom Page Server-Side API Example

Source: https://context7.com/curbob/lobsterboard/llms.txt

Example of how to build custom pages with server-side APIs by adding a folder to the `pages/` directory.

```APIDOC
## Creating Custom Pages

Build custom pages with server-side APIs by adding a folder to the `pages/` directory.

### File Structure Example

```javascript
// pages/my-page/page.json
{
  "id": "my-page",
  "title": "My Page",
  "icon": "🔖",
  "description": "Custom page description",
  "order": 50,
  "enabled": true,
  "standalone": true
}

// pages/my-page/api.cjs
module.exports = function(ctx) {
  // ctx.dataDir - path to data/my-page/
  // ctx.readData(filename) - read JSON from data dir
  // ctx.writeData(filename, obj) - write JSON to data dir

  return {
    routes: {
      'GET /': (req, res, { query }) => {
        const data = ctx.readData('items.json');
        return data.items || [];
      },

      'POST /': (req, res, { body }) => {
        const data = ctx.readData('items.json');
        const item = { id: Date.now().toString(), ...body };
        data.items.push(item);
        ctx.writeData('items.json', data);
        res.statusCode = 201;
        return item;
      },

      'GET /:id': (req, res, { params }) => {
        const data = ctx.readData('items.json');
        return data.items.find(i => i.id === params.id) || { error: 'Not found' };
      },

      'DELETE /:id': (req, res, { params }) => {
        const data = ctx.readData('items.json');
        data.items = data.items.filter(i => i.id !== params.id);
        ctx.writeData('items.json', data);
        return { ok: true };
      }
    }
  };
};
```

### API Context (`ctx`)

- **`ctx.dataDir`**: Path to the data directory for the specific page (e.g., `data/my-page/`).
- **`ctx.readData(filename)`**: Reads JSON data from the page's data directory.
- **`ctx.writeData(filename, obj)`**: Writes JSON data to the page's data directory.

### Available Routes (Example)

- **`GET /`**: Retrieves all items from `items.json`.
- **`POST /`**: Adds a new item to `items.json`.
  - **Request Body**: Contains the data for the new item.
  - **Response**: Returns the newly created item with a 201 status code.
- **`GET /:id`**: Retrieves a specific item by its ID.
- **`DELETE /:id`**: Deletes a specific item by its ID.
```

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

### pm2 Process Management

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

Use pm2, a Node.js process manager, to run LobsterBoard on any OS. This includes installation, starting the application, saving the process list, and setting up startup scripts.

```bash
npm install -g pm2
cd /path/to/lobsterboard
PORT=8080 HOST=0.0.0.0 pm2 start server.cjs --name lobsterboard
pm2 save
pm2 startup
```

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

### Start LobsterBoard Server

Source: https://context7.com/curbob/lobsterboard/llms.txt

Commands to launch the server with custom environment variables for port, host, and security.

```bash
# Basic startup
node server.cjs

# Custom port and network exposure
PORT=3000 HOST=0.0.0.0 node server.cjs

# With password protection
DASHBOARD_PASSWORD=mysecret node server.cjs
```

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

### Clone and Run LobsterBoard

Source: https://github.com/curbob/lobsterboard/blob/main/index.html

Use these commands to download the repository, install required packages, and launch the server on localhost:8080.

```bash
$ git clone https://github.com/curbob/LobsterBoard.git
$ cd LobsterBoard
$ npm install
$ node server.cjs
```

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

### Run Development Server

Source: https://github.com/curbob/lobsterboard/blob/main/CONTRIBUTING.md

Start the local development server for LobsterBoard. Access the application at http://localhost:8080 and use Ctrl+E to enter edit mode.

```bash
node server.cjs
```

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

### GET /api/lb-release

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

Check for the current LobsterBoard version.

```APIDOC
## GET /api/lb-release

### Description
Check for the current LobsterBoard version.

### Method
GET

### Endpoint
/api/lb-release
```

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

### GET /api/templates/:id/preview

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

Get the preview image for a specific template.

```APIDOC
## GET /api/templates/:id/preview

### Description
Get the preview image for a specific template.

### Method
GET

### Endpoint
/api/templates/:id/preview

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the template.
```

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

### Widget Properties Example

Source: https://github.com/curbob/lobsterboard/blob/main/CONTRIBUTING.md

Illustrates common widget properties like title, count, and refresh interval, showing how their default values infer input types.

```javascript
properties: {
  title: 'My Widget',       // string → text input
  count: 10,                // number → number input
  refreshInterval: 60,
            // seconds between auto-refreshes
  apiKey: 'YOUR_API_KEY_HERE',
}
```

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

### Bookmarks Page Metadata

Source: https://github.com/curbob/lobsterboard/blob/main/pages/README.md

Example page.json configuration for a bookmarks page.

```json
{
  "id": "bookmarks",
  "title": "Bookmarks",
  "icon": "🔖",
  "description": "Save and organize bookmarks",
  "order": 40,
  "enabled": true,
  "standalone": true
}
```

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

### API Route Handler Implementation

Source: https://github.com/curbob/lobsterboard/blob/main/pages/README.md

Example of defining server-side API routes using api.cjs, which must use the .cjs extension.

```javascript
module.exports = function(ctx) {
  // ctx.dataDir — absolute path to data/<page-id>/
  // ctx.readData(filename) — read and parse JSON file from data dir
  // ctx.writeData(filename, obj) — write JSON object to data dir

  return {
    routes: {
      'GET /': (req, res, { query, body, params }) => {
        // Return value is sent as JSON automatically
        return { items: [] };
      },

      'POST /': (req, res, { body }) => {
        // body is the parsed JSON request body
        const item = { id: Date.now().toString(), ...body };
        res.statusCode = 201;
        return item;
      },

      'GET /:id': (req, res, { params }) => {
        // :id params are extracted automatically
        return { id: params.id };
      },

      'PATCH /:id': (req, res, { body, params }) => {
        // Set res.statusCode for non-200 responses
        res.statusCode = 404;
        return { error: 'Not found' };
      },

      'DELETE /:id': (req, res, { params }) => {
        return { ok: true };
      },

      // Wildcard routes (match multiple path segments)
      'GET /*': (req, res, { params }) => {
        // params['*'] contains the matched path
        return { path: params['*'] };
      }
    }
  };
};
```

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

### GET /api/system-log

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves system log entries from OpenClaw.

```APIDOC
## GET /api/system-log

### Description
Access OpenClaw system log entries.

### Method
GET

### Endpoint
/api/system-log

### Parameters
#### Query Parameters
- **max** (integer) - Optional - Maximum number of log entries to return
```

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

### GET /api/servers

Source: https://context7.com/curbob/lobsterboard/llms.txt

Lists configured remote servers for monitoring.

```APIDOC
## GET /api/servers

### Description
Returns a list of all configured remote servers.

### Method
GET

### Endpoint
/api/servers
```

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

### Linux systemd Service Configuration

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

Set up a systemd service file to manage LobsterBoard on Linux systems. This ensures it runs as a service, restarts automatically, and starts on boot.

```bash
sudo cat > /etc/systemd/system/lobsterboard.service << 'EOF'
[Unit]
Description=LobsterBoard Dashboard
After=network.target

[Service]
Type=simple
User=your-user
WorkingDirectory=/path/to/lobsterboard
ExecStart=/usr/bin/node server.cjs
Environment=PORT=8080 HOST=0.0.0.0
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target
EOF

sudo systemctl enable lobsterboard
sudo systemctl start lobsterboard
```

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

### GET /api/releases

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves release information for OpenClaw.

```APIDOC
## GET /api/releases

### Description
Checks for the latest OpenClaw release information.

### Method
GET

### Endpoint
/api/releases
```

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

### GET /api/templates

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

List all available dashboard templates.

```APIDOC
## GET /api/templates

### Description
List all available dashboard templates.

### Method
GET

### Endpoint
/api/templates
```

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

### GET /api/templates/:id

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

Retrieve the configuration for a specific template.

```APIDOC
## GET /api/templates/:id

### Description
Retrieve the configuration for a specific template.

### Method
GET

### Endpoint
/api/templates/:id

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the template.
```

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

### Get All Todos

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves the entire list of todos from persistent storage. The response is a JSON array of todo objects.

```bash
curl http://localhost:8080/api/todos
```

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

### Get All Notes

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves all stored notes, keyed by their widget IDs. The response is a JSON object where keys are widget IDs and values are note content.

```bash
curl http://localhost:8080/api/notes
```

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

### GET /config

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves the current dashboard configuration, including canvas dimensions, font scale, and widget definitions.

```APIDOC
## GET /config

### Description
Retrieves the current dashboard configuration, including canvas dimensions, font scale, and widget definitions.

### Method
GET

### Endpoint
/config

### Response
#### Success Response (200)
- **canvas** (object) - Canvas dimensions (width, height)
- **fontScale** (number) - Font scale factor
- **widgets** (array) - List of widget definitions

#### Response Example
{
  "canvas": { "width": 1920, "height": 1080 },
  "fontScale": 1.25,
  "widgets": [
    {
      "id": "widget-1",
      "type": "weather",
      "x": 600,
      "y": 120,
      "width": 200,
      "height": 140,
      "properties": {
        "title": "Local Weather",
        "location": "Atlanta",
        "units": "F",
        "refreshInterval": 600
      }
    }
  ]
}
```

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

### GET /api/stats/stream

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

Retrieve live system statistics via Server-Sent Events (SSE).

```APIDOC
## GET /api/stats/stream

### Description
Retrieve live system statistics via Server-Sent Events (SSE).

### Method
GET

### Endpoint
/api/stats/stream
```

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

### GET /api/today

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves a summary of today's activities, including commits and cron job runs.

```APIDOC
## GET /api/today

### Description
Retrieves a summary of today's activities, including commits and cron job runs.

### Method
GET

### Endpoint
/api/today

### Response
#### Success Response (200)
- **date** (string) - The current date in YYYY-MM-DD format.
- **activities** (array) - An array of activity objects.
  - **type** (string) - The type of activity (e.g., 'commit', 'cron').
  - **icon** (string) - An icon representing the activity.
  - **text** (string) - A description of the activity.
  - **source** (string) - The source of the activity (e.g., 'git', 'cron').
  - **status** (string) - Optional - The status of the activity if applicable (e.g., 'ok').
- **count** (integer) - The total number of activities for the day.

### Response Example
```json
{
  "date": "2026-03-24",
  "activities": [
    { "type": "commit", "icon": "💾", "text": "Fixed authentication bug", "source": "git" },
    { "type": "cron", "icon": "⏰", "text": "daily-backup ran", "source": "cron", "status": "ok" }
  ],
  "count": 2
}
```
```

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

### Get System Log Entries Bash

Source: https://context7.com/curbob/lobsterboard/llms.txt

Access OpenClaw system logs via the API. Requires OpenClaw to be installed and running.

```bash
# Get system log entries (requires OpenClaw)
curl "http://localhost:8080/api/system-log?max=50"
```

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

### Copy Widget Template

Source: https://github.com/curbob/lobsterboard/blob/main/CONTRIBUTING.md

Use this command to initialize a new widget directory from the provided template.

```bash
cp -r community-widgets/_template community-widgets/your-widget-name
```

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

### GET /api/calendar

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

Proxy an iCal feed.

```APIDOC
## GET /api/calendar

### Description
Proxy an iCal feed.

### Method
GET

### Endpoint
/api/calendar

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the iCal feed.
```

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

### GET /api/quote

Source: https://context7.com/curbob/lobsterboard/llms.txt

Fetches a random inspirational quote.

```APIDOC
## GET /api/quote

### Description
Fetches a random inspirational quote.

### Method
GET

### Endpoint
/api/quote

### Response
#### Success Response (200)
- An array containing a single quote object.
  - **q** (string) - The quote text.
  - **a** (string) - The author of the quote.

### Response Example
```json
[{ "q": "Stay hungry, stay foolish.", "a": "Steve Jobs" }]
```
```

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

### Configure LobsterBoard Port and Host

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

Run the LobsterBoard server with a custom port or expose it to the network by setting environment variables.

```bash
PORT=3000 node server.cjs
```

```bash
HOST=0.0.0.0 node server.cjs
```

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

### GET /api/cron

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves the status of all cron jobs.

```APIDOC
## GET /api/cron

### Description
Retrieves the status of all cron jobs.

### Method
GET

### Endpoint
/api/cron

### Response
#### Success Response (200)
- **jobs** (array) - An array of cron job objects.
  - **name** (string) - The name of the cron job.
  - **schedule** (string) - The cron schedule string.
  - **enabled** (boolean) - Whether the cron job is enabled.
  - **lastRun** (string) - The timestamp of the last run (ISO 8601 format).
  - **lastStatus** (string) - The status of the last run (e.g., 'success', 'failed').

### Response Example
```json
{
  "jobs": [
    { "name": "daily-backup", "schedule": "0 2 * * *", "enabled": true, "lastRun": "2026-03-24T02:00:00Z", "lastStatus": "success" }
  ]
}
```
```

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

### Copy Widget Template

Source: https://github.com/curbob/lobsterboard/blob/main/CONTRIBUTING.md

Create a new widget directory by copying the provided template.

```bash
cp -r community-widgets/_template community-widgets/my-widget-name
```

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

### Initialize Feature Branch

Source: https://github.com/curbob/lobsterboard/blob/main/DEVJARVIS_WORKFLOW.md

Standard commands to sync with upstream and create a new feature branch for development.

```bash
# For each new task/feature
git checkout main
git pull upstream main
git checkout -b feature/task-name-from-paperclip
# Work on the feature
git add . && git commit -m "descriptive message"
git push -u origin feature/task-name-from-paperclip
```

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

### GET /api/calendar

Source: https://context7.com/curbob/lobsterboard/llms.txt

Fetches and parses iCal feeds.

```APIDOC
## GET /api/calendar

### Description
Fetches iCal data and returns structured event objects.

### Method
GET

### Endpoint
/api/calendar

### Parameters
#### Query Parameters
- **url** (string) - Optional - The iCal URL
- **max** (integer) - Optional - Maximum number of events
- **widgetId** (string) - Optional - Widget identifier for secret keys
- **secretKey** (string) - Optional - Key to retrieve stored iCal URL
```

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

### Bookmarks Data Initialization

Source: https://github.com/curbob/lobsterboard/blob/main/pages/README.md

Initial state for the bookmarks data file.

```json
{ "bookmarks": [] }
```

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

### List Configured Servers

Source: https://context7.com/curbob/lobsterboard/llms.txt

Lists all servers configured for remote monitoring. Includes server ID, name, type, and connection details for remote servers.

```bash
curl http://localhost:8080/api/servers
```

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

### GET /api/rss

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

Proxy an RSS or Atom feed.

```APIDOC
## GET /api/rss

### Description
Proxy an RSS or Atom feed.

### Method
GET

### Endpoint
/api/rss

### Parameters
#### Query Parameters
- **url** (string) - Required - The URL of the RSS/Atom feed.
```

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

### macOS launchd Agent Configuration

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

Create a launchd plist file to run LobsterBoard as a background agent on macOS. Ensure paths to Node.js and the server script are correct.

```bash
cat > ~/Library/LaunchAgents/com.lobsterboard.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
  <dict>
    <key>Label</key><string>com.lobsterboard</string>
    <key>RunAtLoad</key><true/>
    <key>KeepAlive</key><true/>
    <key>ProgramArguments</key>
    <array>
      <string>/usr/local/bin/node</string>
      <string>/path/to/lobsterboard/server.cjs</string>
    </array>
    <key>WorkingDirectory</key><string>/path/to/lobsterboard</string>
    <key>EnvironmentVariables</key>
    <dict>
      <key>PORT</key><string>8080</string>
      <key>HOST</key><string>0.0.0.0</string>
    </dict>
  </dict>
</plist>
EOF

launchctl load ~/Library/LaunchAgents/com.lobsterboard.plist
```

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

### GET /api/latest-image

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves the most recent image from a specified directory.

```APIDOC
## GET /api/latest-image

### Description
Retrieves the most recent image from a specified directory.

### Method
GET

### Endpoint
/api/latest-image

### Query Parameters
- **dir** (string) - Required - The directory path to search for the latest image (e.g., "~/Pictures/Screenshots").

### Response
#### Success Response (200)
- **status** (string) - The status of the response ('ok').
- **image** (object) - An object containing details about the latest image.
  - **name** (string) - The filename of the image.
  - **mtime** (integer) - The modification time of the image (Unix timestamp in milliseconds).
  - **dataUrl** (string) - The data URL of the image.
- **total** (integer) - The total number of images in the directory.

### Response Example
```json
{
  "status": "ok",
  "image": {
    "name": "Screenshot-2026-03-24.png",
    "mtime": 1711296000000,
    "dataUrl": "data:image/png;base64,..."
  },
  "total": 127
}
```
```

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

### Enable Bookmarks Page Configuration

Source: https://github.com/curbob/lobsterboard/blob/main/pages/README.md

JSON configuration to enable and order the bookmarks page within the application.

```json
{
  "pages": {
    "bookmarks": { "enabled": true, "order": 40 }
  }
}
```

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

### Project Directory Structure

Source: https://github.com/curbob/lobsterboard/blob/main/pages/README.md

Standard layout for a LobsterBoard project, requiring a pages folder in the root directory.

```text
your-project/
├── pages/              # Your custom pages go here
│   └── my-page/
├── data/               # Auto-created for page data
├── public/             # Optional: static assets (images, etc.)
├── node_modules/
└── package.json
```

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

### GET /api/notes

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves all notes stored for the Notes widget.

```APIDOC
## GET /api/notes

### Description
Fetches all notes keyed by widget ID.

### Method
GET

### Endpoint
/api/notes

### Response
#### Success Response (200)
- **Object** (object) - Map of widget IDs to note content

#### Response Example
{
  "widget-note-1": { "content": "Meeting notes for today..." },
  "widget-note-2": { "content": "Important reminders..." }
}
```

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

### Subscribe to System Stats via SSE

Source: https://context7.com/curbob/lobsterboard/llms.txt

Client-side implementation for consuming real-time system metrics or fetching a single snapshot.

```javascript
// Browser-side JavaScript to subscribe to system stats
const eventSource = new EventSource('/api/stats/stream');

eventSource.onmessage = (event) => {
  const stats = JSON.parse(event.data);
  console.log('CPU Load:', stats.cpu.currentLoad.toFixed(0) + '%');
  console.log('Memory Used:', (stats.memory.active / 1024 / 1024 / 1024).toFixed(1) + 'GB');
  console.log('Uptime:', Math.floor(stats.uptime / 86400) + ' days');

  // Disk usage for root partition
  const rootDisk = stats.disk.find(d => d.mount === '/');
  if (rootDisk) {
    console.log('Disk Usage:', rootDisk.use.toFixed(0) + '%');
  }

  // Network throughput
  stats.network.forEach(iface => {
    if (iface.iface !== 'lo') {
      console.log(`${iface.iface}: ↓${(iface.rx_sec / 1024).toFixed(1)}KB/s ↑${(iface.tx_sec / 1024).toFixed(1)}KB/s`);
    }
  });

  // Docker containers
  if (stats.docker && stats.docker.length > 0) {
    stats.docker.forEach(c => {
      console.log(`Container ${c.name}: ${c.state}`);
    });
  }
};

// Get stats once without streaming
fetch('/api/stats')
  .then(res => res.json())
  .then(stats => console.log(stats));
```

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

### GET /api/pages

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

List all custom pages available in the dashboard.

```APIDOC
## GET /api/pages

### Description
List all custom pages available in the dashboard.

### Method
GET

### Endpoint
/api/pages
```

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

### Retrieve Activity Summary

Source: https://context7.com/curbob/lobsterboard/llms.txt

Fetches a summary of today's activities.

```bash
curl http://localhost:8080/api/today
```

```json
{
  "date": "2026-03-24",
  "activities": [
    { "type": "commit", "icon": "💾", "text": "Fixed authentication bug", "source": "git" },
    { "type": "cron", "icon": "⏰", "text": "daily-backup ran", "source": "cron", "status": "ok" }
  ],
  "count": 2
}
```

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

### Asset Path Configuration

Source: https://github.com/curbob/lobsterboard/blob/main/pages/README.md

Demonstrates the requirement for absolute paths when referencing scripts and stylesheets.

```html
<!-- ✅ Correct: absolute paths -->
<script src="/pages/my-page/script.js"></script>
<link rel="stylesheet" href="/pages/my-page/style.css">

<!-- ❌ Wrong: relative paths may break -->
<script src="script.js"></script>
```

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

### GET /api/browse-dirs

Source: https://context7.com/curbob/lobsterboard/llms.txt

Browses directories, restricted to the user's home directory.

```APIDOC
## GET /api/browse-dirs

### Description
Browses directories, restricted to the user's home directory.

### Method
GET

### Endpoint
/api/browse-dirs

### Query Parameters
- **dir** (string) - Required - The directory path to browse (e.g., "~/Pictures").

### Response
#### Success Response (200)
- **status** (string) - The status of the response ('ok').
- **path** (string) - The absolute path of the browsed directory.
- **dirs** (array) - An array of subdirectory names.
- **imageCount** (integer) - The number of images found in the directory.

### Response Example
```json
{
  "status": "ok",
  "path": "/Users/me/Pictures",
  "dirs": ["Screenshots", "Wallpapers", "Photos"],
  "imageCount": 45
}
```
```

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

### Manage Authentication and Dashboard Modes

Source: https://context7.com/curbob/lobsterboard/llms.txt

Handle PIN protection, verify credentials, and toggle public/private dashboard modes.

```bash
curl http://localhost:8080/api/auth/status
```

```bash
curl -X POST http://localhost:8080/api/auth/set-pin \
  -H "Content-Type: application/json" \
  -d '{"pin": "1234"}'
```

```bash
curl -X POST http://localhost:8080/api/auth/verify-pin \
  -H "Content-Type: application/json" \
  -d '{"pin": "1234"}'
```

```bash
curl -X POST http://localhost:8080/api/auth/remove-pin \
  -H "Content-Type: application/json" \
  -d '{"pin": "1234"}'
```

```bash
curl -X POST http://localhost:8080/api/mode \
  -H "Content-Type: application/json" \
  -d '{"publicMode": true, "pin": "1234"}'
```

```bash
curl http://localhost:8080/api/mode
```

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

### GET /api/servers/:id/stats

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves performance statistics for a specific remote server.

```APIDOC
## GET /api/servers/:id/stats

### Description
Returns CPU, memory, disk, and uptime stats for a remote server.

### Method
GET

### Endpoint
/api/servers/:id/stats

### Parameters
#### Path Parameters
- **id** (string) - Required - Server ID
```

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

### Export Dashboard as Template

Source: https://context7.com/curbob/lobsterboard/llms.txt

Exports the current dashboard configuration as a new template. Includes metadata such as name, description, author, and tags.

```bash
curl -X POST http://localhost:8080/api/templates/export \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My Dashboard",
    "description": "Personal homelab monitoring setup",
    "author": "myusername",
    "tags": ["homelab", "monitoring"]
  }'
```

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

### Interact with Template Gallery API

Source: https://context7.com/curbob/lobsterboard/llms.txt

Commands for listing, retrieving, previewing, and importing dashboard templates.

```bash
# List all available templates
curl http://localhost:8080/api/templates

# Response:
[
  {
    "id": "minimal-layout",
    "name": "Minimal Layout",
    "description": "Clean minimal dashboard for 10-inch screens",
    "author": "curbob",
    "tags": ["minimal", "small-screen"],
    "canvasSize": "1024x600",
    "widgetCount": 8
  }
]

# Get a specific template configuration
curl http://localhost:8080/api/templates/minimal-layout

# Get template preview image
curl http://localhost:8080/api/templates/minimal-layout/preview --output preview.png

# Import a template (replace mode - replaces entire dashboard)
curl -X POST http://localhost:8080/api/templates/import \
  -H "Content-Type: application/json" \
  -d '{"id": "minimal-layout", "mode": "replace"}'
```

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

### GET /api/ai-usage

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves AI usage statistics across various providers.

```APIDOC
## GET /api/ai-usage

### Description
Returns combined usage data for all configured AI providers.

### Method
GET

### Endpoint
/api/ai-usage

### Response
#### Success Response (200)
- **Object** (object) - Usage statistics per provider
```

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

### GET /api/todos

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves the full list of todos for the Todo List widget.

```APIDOC
## GET /api/todos

### Description
Fetches all stored todo items.

### Method
GET

### Endpoint
/api/todos

### Response
#### Success Response (200)
- **Array** (object) - List of todo items

#### Response Example
[
  { "id": "1", "text": "Finish dashboard setup", "done": false },
  { "id": "2", "text": "Configure weather widget", "done": true }
]
```

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

### Global Page Configuration

Source: https://github.com/curbob/lobsterboard/blob/main/pages/README.md

Enabling or disabling pages via the root pages.json file.

```json
{
  "pages": {
    "my-page": { "enabled": true, "order": 50 },
    "other-page": { "enabled": false }
  }
}
```

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

### GET /api/logs

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves log entries from the system. Supports filtering by time, level, and category.

```APIDOC
## GET /api/logs

### Description
Retrieves log entries from the system. Supports filtering by time, level, and category.

### Method
GET

### Endpoint
/api/logs

### Query Parameters
- **since** (string) - Optional - Filter logs after this timestamp (ISO 8601 format).
- **level** (string) - Optional - Filter logs by level (e.g., INFO, OK, ERROR).
- **category** (string) - Optional - Filter logs by category (e.g., gateway, auth).

### Response
#### Success Response (200)
- **status** (string) - The status of the response ('ok').
- **entries** (array) - An array of log entry objects.
  - **time** (string) - The timestamp of the log entry (ISO 8601 format).
  - **level** (string) - The log level.
  - **category** (string) - The category of the log entry.
  - **message** (string) - The log message.

### Response Example
```json
{
  "status": "ok",
  "entries": [
    { "time": "2026-03-24T10:30:00Z", "level": "INFO", "category": "gateway", "message": "Server started" },
    { "time": "2026-03-24T10:31:00Z", "level": "OK", "category": "auth", "message": "Session created" }
  ]
}
```
```

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

### Define Custom Page Configuration and API

Source: https://context7.com/curbob/lobsterboard/llms.txt

Configure page metadata and implement server-side routes using the provided context object.

```json
{
  "id": "my-page",
  "title": "My Page",
  "icon": "🔖",
  "description": "Custom page description",
  "order": 50,
  "enabled": true,
  "standalone": true
}
```

```javascript
module.exports = function(ctx) {
  // ctx.dataDir - path to data/my-page/
  // ctx.readData(filename) - read JSON from data dir
  // ctx.writeData(filename, obj) - write JSON to data dir

  return {
    routes: {
      'GET /': (req, res, { query }) => {
        const data = ctx.readData('items.json');
        return data.items || [];
      },

      'POST /': (req, res, { body }) => {
        const data = ctx.readData('items.json');
        const item = { id: Date.now().toString(), ...body };
        data.items.push(item);
        ctx.writeData('items.json', data);
        res.statusCode = 201;
        return item;
      },

      'GET /:id': (req, res, { params }) => {
        const data = ctx.readData('items.json');
        return data.items.find(i => i.id === params.id) || { error: 'Not found' };
      },

      'DELETE /:id': (req, res, { params }) => {
        const data = ctx.readData('items.json');
        data.items = data.items.filter(i => i.id !== params.id);
        ctx.writeData('items.json', data);
        return { ok: true };
      }
    }
  };
};
```

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

### GET/POST /config

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

Load or save the dashboard layout configuration.

```APIDOC
## GET/POST /config

### Description
Load or save the dashboard layout configuration.

### Method
GET, POST

### Endpoint
/config
```

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

### POST /api/templates/import

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

Import a template into the dashboard.

```APIDOC
## POST /api/templates/import

### Description
Import a template into the dashboard (merge or replace).

### Method
POST

### Endpoint
/api/templates/import
```

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

### POST /config

Source: https://context7.com/curbob/lobsterboard/llms.txt

Saves the dashboard layout, canvas size, and widget positions to the local configuration file.

```APIDOC
## POST /config

### Description
Saves the dashboard layout, canvas size, and widget positions to the local configuration file.

### Method
POST

### Endpoint
/config

### Request Body
- **canvas** (object) - Canvas dimensions (width, height)
- **widgets** (array) - List of widget definitions

### Request Example
{
  "canvas": { "width": 1920, "height": 1080 },
  "widgets": [
    {
      "id": "widget-1",
      "type": "cpu-memory",
      "x": 20,
      "y": 120,
      "width": 200,
      "height": 120,
      "properties": { "title": "System", "server": "local", "refreshInterval": 5 }
    }
  ]
}
```

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

### Add New Remote Server

Source: https://context7.com/curbob/lobsterboard/llms.txt

Adds a new remote server to the monitoring system. Requires the server's name, URL, and an API key for the lobsterboard-agent.

```bash
curl -X POST http://localhost:8080/api/servers \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production VPS",
    "url": "http://your-server-ip:9090",
    "apiKey": "your-agent-api-key"
  }'
```

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

### Check LobsterBoard Releases Bash

Source: https://context7.com/curbob/lobsterboard/llms.txt

Use curl to query the LobsterBoard API for release information, including current, latest, and published dates.

```bash
# Check LobsterBoard releases
curl http://localhost:8080/api/lb-release
```

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

### Data Storage Helpers

Source: https://github.com/curbob/lobsterboard/blob/main/pages/README.md

Usage of context helpers for reading and writing JSON data files.

```javascript
// Read
const data = ctx.readData('items.json');

// Write
ctx.writeData('items.json', { items: [...] });
```

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

### Get Remote Server Stats

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves real-time statistics for a specific remote server, including CPU load, memory usage, disk space, and uptime.

```bash
curl http://localhost:8080/api/servers/vps-1/stats
```

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

### POST /api/templates/import

Source: https://context7.com/curbob/lobsterboard/llms.txt

Imports a dashboard template by merging widgets into the current dashboard.

```APIDOC
## POST /api/templates/import

### Description
Imports a template in merge mode, appending widgets below existing ones.

### Method
POST

### Endpoint
/api/templates/import

### Request Body
- **id** (string) - Required - The template ID to import
- **mode** (string) - Required - The import mode (e.g., "merge")

### Request Example
{
  "id": "minimal-layout",
  "mode": "merge"
}
```

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

### Get Specific AI Provider Usage

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves AI usage statistics for a single specified provider. Supports providers like Claude, Copilot, Cursor, and Gemini.

```bash
curl http://localhost:8080/api/ai-usage/claude
```

```bash
curl http://localhost:8080/api/ai-usage/copilot
```

```bash
curl http://localhost:8080/api/ai-usage/cursor
```

```bash
curl http://localhost:8080/api/ai-usage/gemini
```

```bash
curl http://localhost:8080/api/ai-usage/codex
```

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

### Create a Custom Page in LobsterBoard

Source: https://github.com/curbob/lobsterboard/blob/main/README.md

Structure for creating a custom page within LobsterBoard. Pages are auto-discovered by placing a folder in the 'pages/' directory.

```directory structure
pages/
└── my-page/
    ├── page.json       # Metadata (title, icon, order)
    ├── index.html      # Page UI
    └── api.cjs         # Optional: server-side API routes
```

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

### Import Template (Merge Mode)

Source: https://context7.com/curbob/lobsterboard/llms.txt

Imports a dashboard template, appending its widgets below existing ones. Requires a valid template ID and specifies the merge mode.

```bash
curl -X POST http://localhost:8080/api/templates/import \
  -H "Content-Type: application/json" \
  -d '{"id": "minimal-layout", "mode": "merge"}'
```

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

### Get Combined AI Usage

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves combined AI usage statistics across all supported providers. The response includes used and limit values for sessions and weekly usage.

```bash
curl http://localhost:8080/api/ai-usage
```

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

### Get Claude API Usage Details

Source: https://context7.com/curbob/lobsterboard/llms.txt

Retrieves detailed API usage information for Claude, including token counts, cost, model-specific usage, and weekly/monthly summaries. Requires an admin key.

```bash
curl http://localhost:8080/api/usage/claude
```

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

### Implement JavaScript Logic for Usage Data

Source: https://github.com/curbob/lobsterboard/blob/main/pages/claude-usage/index.html

Functions to calculate usage thresholds, format reset times, and fetch/render usage data from the API.

```javascript
function barClass(pct) { if (pct >= 80) return 'red'; if (pct >= 50) return 'yellow'; return 'green'; } function timeLeft(iso) { if (!iso) return ''; const ms = new Date(iso) - Date.now(); if (ms <= 0) return 'just now'; const h = Math.floor(ms / 3600000); const m = Math.floor((ms % 3600000) / 60000); if (h > 24) return Math.floor(h / 24) + 'd ' + (h % 24) + 'h'; return h > 0 ? h + 'h ' + m + 'm' : m + 'm'; } function renderMeter(label, pct, resetIso) { const p = Math.min(100, Math.max(0, pct || 0)); const cls = barClass(p); const reset = resetIso ? `<div class="meter-sub">resets in ${timeLeft(resetIso)}</div>` : ''; return `<div class="meter"> <div class="meter-header"> <span class="meter-label">${label}</span> <span class="meter-value ${cls}">${p.toFixed(0)}%</span> </div> <div class="meter-bar"><div class="meter-fill bg-${cls}" style="width:${p}%"></div></div> ${reset} </div>`; } async function loadUsage() { const card = document.getElementById('usage-card'); const planEl = document.getElementById('plan-info'); const refreshEl = document.getElementById('refresh-info'); try { const res = await fetch('/api/pages/claude-usage/usage'); const d = await res.json(); if (d.error) { card.innerHTML = `<div class="error">${d.error}</div>`; return; } const labels = { max: 'Max (5×)', pro: 'Pro', free: 'Free' }; const planName = labels[d.subscription] || d.subscription || 'Unknown'; const tierLabel = d.tier ? d.tier.replace('default_claude_', '').replace(/_/g, ' ') : ''; planEl.innerHTML = `${planName} plan` + (tierLabel ? `<span class="badge">${tierLabel}</span>` : ''); let html = ''; if (d.five_hour) html += renderMeter('5-Hour Session', d.five_hour.utilization, d.five_hour.resets_at); if (d.seven_day) html += renderMeter('7-Day Weekly', d.seven_day.utilization, d.seven_day.resets_at); if (d.seven_day_opus) html += renderMeter('Opus (7-Day)', d.seven_day_opus.utilization, d.seven_day_opus.resets_at); if (d.seven_day_sonnet) html += renderMeter('Sonnet (7-Day)', d.seven_day_sonnet.utilization, d.seven_day_sonnet.resets_at); if (d.extra_usage && d.extra_usage.is_enabled) { const used = (d.extra_usage.used_credits / 100).toFixed(2); const limit = d.extra_usage.monthly_limit > 0 ? '$' + (d.extra_usage.monthly_limit / 100).toFixed(2) : 'No limit'; html += `<div class="extra-row"> <span class="extra-label">Extra Usage (this month)</span> <span class="extra-value">$${used} / ${limit}</span> </div>`; } card.innerHTML = html || '<div class="loading">No usage data available</div>'; refreshEl.textContent = 'Last updated: ' + new Date().toLocaleTimeString(); } catch (e) { card.innerHTML = `<div class="error">Failed to load: ${e.message}</div>`; } } loadUsage(); setInterval(loadUsage, 120000);
```