> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cnap.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom Dashboards

> Build live monitoring dashboards from reusable code snippets

Custom dashboards let you build live monitoring views for your infrastructure by combining reusable code snippets into a configurable grid layout. Each widget runs a snippet that queries the CNAP API and displays the result as a table, stat, JSON tree, or log output.

Snippets use the same sandboxed JavaScript execution as [MCP Code Mode](/ai/platform-mcp#why-code-mode) — the same `cnap.request()` API, the same V8 isolate, the same security model. You can write snippets by hand, or [let an AI agent build your dashboards for you](/ai/dashboard-generation).

## How It Works

Dashboards are built from two building blocks:

* **Snippets** — JavaScript functions that query the CNAP API and return data. Each snippet has a display type (table, stat, JSON, or logs) that controls how the result is rendered.
* **Dashboards** — Grid layouts that arrange snippets as widgets. Each widget can span 1–4 columns and runs its snippet automatically when you open the dashboard.

You write a snippet once, then reuse it across multiple dashboards. When you update a snippet, every dashboard that uses it picks up the change.

## Creating a Snippet

Navigate to **Dashboards → Snippets** tab and click **New Snippet**.

Snippets are `async` JavaScript functions that use `cnap.request()` to call the [CNAP API](/apis/introduction). The workspace header is injected automatically — you don't need to pass authentication or workspace IDs.

```javascript theme={null}
async () => {
  const res = await cnap.request({
    method: "GET",
    path: "/v1/clusters",
  });
  if (res.status !== 200) throw new Error(JSON.stringify(res.body));
  return res.body.data.map(c => ({
    name: c.name,
    status: c.kaas?.status ?? "imported",
    version: c.kaas?.version ?? "—",
  }));
}
```

The editor includes a side-by-side preview — click **Run** to execute the snippet and see the result before saving.

<Tip>
  Use the **Examples** dropdown in the snippet editor to load pre-built snippets for common tasks like listing clusters, counting installs, or generating status reports.
</Tip>

### Display Types

The display type controls how the snippet result is rendered in dashboard widgets:

| Display Type | Return Value            | Use Case                    |
| ------------ | ----------------------- | --------------------------- |
| **Table**    | Array of objects        | List resources with columns |
| **Stat**     | Single number or string | KPIs, counts, status values |
| **JSON**     | Any object              | Structured data, breakdowns |
| **Logs**     | String                  | Text reports, log output    |

### The `cnap.request()` API

This is the same API available in [MCP Code Mode](/ai/code-mode-in-action). Snippets run in a sandboxed environment with access to a single function:

```javascript theme={null}
const response = await cnap.request({
  method: "GET" | "POST" | "PUT" | "DELETE",
  path: "/v1/...",
  body: { ... },  // optional, for POST/PUT
});
// response.status — HTTP status code
// response.body — parsed JSON response
```

All requests are authenticated and scoped to the current workspace. See the [API Reference](/apis/introduction) for available endpoints.

<Note>
  Snippets execute server-side in an isolated V8 sandbox — the same sandbox that powers [Code Mode](/ai/platform-mcp#why-code-mode). They cannot access `require`, `process`, `fs`, or any Node.js APIs — only `cnap.request()` is available.
</Note>

## Creating a Dashboard

Navigate to **Dashboards** tab and click **New Dashboard**. Give it a name and optional description, then click **Create Dashboard** to open the builder.

### The Dashboard Builder

Dashboards open in **view mode** by default, showing your widgets in a live grid. Click **Edit** to enter edit mode, where overlay controls appear on each widget:

* **Move up/down** — Reorder widgets in the grid
* **Resize (−/+)** — Adjust column span from 1/4 to full width
* **Edit snippet** — Jump to the snippet editor
* **Delete** — Remove the widget

Use the **Add Widget** bar at the bottom to select a snippet and add it to the dashboard. Click **Save** when you're done, or **Done** to return to view mode.

<Tip>
  Use **Cmd+S** (Mac) or **Ctrl+S** (Windows/Linux) to save without clicking the button.
</Tip>

## Workspace Scoping

Snippets and dashboards follow the same workspace scoping as other CNAP resources:

* **When a workspace is selected** — You see snippets and dashboards belonging to that workspace
* **When "All Workspaces" is selected** — You see snippets and dashboards from all workspaces you have access to

Snippet API calls are always scoped to the workspace the snippet belongs to.

## Related Topics

* [Generate Dashboards with AI →](/ai/dashboard-generation) — Let an AI agent build and iterate on dashboards for you
* [Code Mode in Action →](/ai/code-mode-in-action) — See how the same sandbox powers AI agent operations
* [API Reference →](/apis/introduction) — Explore available API endpoints for snippets
* [Workspaces →](/workspaces) — Understand how workspaces organize resources