# Card SDK

> Build your own cards for the NeuroSquad canvas — small web apps that watch and prompt agents, exchange data over arrows and give agents new tools — and share them on GitHub.

Source: https://docs.neurosquad.ai/en/card-sdk

A **custom card** is a small web app that lives on the canvas next to your agents, terminals and
notes. Anyone can build one with the Card SDK (`@neurosquad/card-sdk`), push it to GitHub, and
anyone else can install it by pasting `owner/repo` into NeuroSquad.

This section is for two readers:

- **Everyone** who wants to use a card someone else made — start with
[Installing community cards](https://docs.neurosquad.ai/en/card-sdk/community-cards). It explains what a card can and cannot
do, what the install dialog tells you, and how to take access back.
- **Developers** who want to build one — start with the [Quick start](https://docs.neurosquad.ai/en/card-sdk/quick-start): a
working card on your canvas in a few minutes.

## What a card can do

A custom card is a first-class citizen of the canvas: it has the same header, resizes, joins
[groups](https://docs.neurosquad.ai/en/canvas/groups), takes [arrows](https://docs.neurosquad.ai/en/canvas/arrows), shows a tile when you zoom out and sits in
the sidebar like every other card. Inside its box it draws whatever it wants. Through the SDK it can:

  - **Watch your agents**: Who is working, who waits for you, when a turn starts and ends — and, when you connect it, what an agent prints.
  - **Prompt agents**: Send an instruction to an agent you connected it to. Prompts queue while the agent works and respect the workspace budget.
  - **Talk to other cards**: Typed ports over arrows: a card can append to a note, add tasks to a checklist, or feed another custom card.
  - **Give agents tools**: Declare a tool, implement it in the card; connected agents call it over the app's MCP server.
  - **Reach the web**: Fetch from the hosts it declared — through the app's proxy, with secrets the card never sees.
  - **Work with project files**: Read and write files in the workspace folder, when you allow it.
  - **Run commands**: Run a command in a terminal card you connected it to, and get the exit code and output.
  - **Settings and storage**: A settings form drawn by the app, per-card storage that survives restarts, the app's theme and language.

## Cards never leave the canvas

Community code is not trusted, so a card runs **sealed inside its own box**:

- It runs in a separate, sandboxed process. A card that hangs or crashes cannot freeze the canvas
or take anything else with it.
- It cannot reach the app itself, your other cards, Node.js, your files, cookies or the internet
on its own. Everything goes through the SDK, and the app checks every single request against
what you allowed.
- It cannot open windows or pop-ups, go fullscreen, show system dialogs, send OS notifications,
download files or navigate the app away. It draws only inside its card.
- When a card needs your decision — a confirmation, a link to open, a permission, a prompt to an
agent in dangerous mode, a secret such as an API key — the **app** asks you in its own dialog,
which **dims the whole window**, sidebar and title bar included. A card cannot paint outside its
box, so it can never fake that. Anything inside the card body is the card's own: NeuroSquad never
asks for a key there.

## The security model in plain words

  - **You decide what it may do**: A card lists the [permissions](https://docs.neurosquad.ai/en/card-sdk/permissions) it needs. You see them, high-risk first, before anything is installed. A card without permissions can only draw inside its box.
  - **Arrows are consent**: Anything that reaches another card or an agent — data over a port, a prompt, a command, reading a screen — needs an arrow between the two cards **and** the matching permission. No arrow, no data.
  - **Pinned to a commit**: An install is this repository at this exact commit — a commit of the repository itself, not of a fork. Nothing changes behind your back: updates are never automatic, and one that asks for more access, or changes what the card offers to agents, asks you again.
  - **Secrets stay in the app**: API keys are typed only into the app's own dialog, stored encrypted, and added by the app to requests to the internet hosts you granted. The card itself never sees them.
  - **Some files are off limits**: Even with file access, a card can never change `.git`, your agents' settings and instructions (`.claude/`, `.mcp.json`, `CLAUDE.md`, `AGENTS.md`…) or CI workflows — and it gets no file access at all if the workspace is your home folder or a whole drive.
  - **Everything shows**: A prompt or a tool call made through a card lights up the arrow it went over and lands in the [arrow log](https://docs.neurosquad.ai/en/canvas/arrows#arrow-log) with the card's name.

> Community cards are not made or checked by the NeuroSquad team. Install cards from people you
> trust, and read the permission list — a card that may prompt agents or run commands can do
> anything those agents and terminals can.

## In this section

  - **[Installing community cards](https://docs.neurosquad.ai/en/card-sdk/community-cards)**: For users: install, review, revoke, update and remove.
  - **[Quick start](https://docs.neurosquad.ai/en/card-sdk/quick-start)**: From an empty folder to a card on your canvas, and on GitHub.
  - **[Manifest reference](https://docs.neurosquad.ai/en/card-sdk/manifest)**: Every field of `neurosquad-card.json`.
  - **[Permissions](https://docs.neurosquad.ai/en/card-sdk/permissions)**: Each one: what the user sees, what it unlocks.
  - **[API reference](https://docs.neurosquad.ai/en/card-sdk/api)**: Every method and event, with types and examples.
  - **[React bindings](https://docs.neurosquad.ai/en/card-sdk/react)**: `CardProvider` and hooks.
  - **[UI kit & styling](https://docs.neurosquad.ai/en/card-sdk/styling)**: Look native, or style it your way.
  - **[Testing](https://docs.neurosquad.ai/en/card-sdk/testing)**: An in-memory host for tests and browser previews.
  - **[CLI reference](https://docs.neurosquad.ai/en/card-sdk/cli)**: `create`, `dev`, `validate`, `pack`.
  - **[Publishing & updates](https://docs.neurosquad.ai/en/card-sdk/publishing)**: GitHub, versions, what users see on update.
  - **[Security checklist](https://docs.neurosquad.ai/en/card-sdk/security)**: What to check before you share a card.
  - **[FAQ & troubleshooting](https://docs.neurosquad.ai/en/card-sdk/faq)**: Common errors and how to fix them.

> The Card SDK is new. Everything here describes version 1 of the card protocol; a few things are
> deliberately left for later — a card gallery, automatic updates, cards that run with no frame at
> all, a file picker, and running card code on the phone. Each is called out where it matters.