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. 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: 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, takes 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:
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
A card lists the permissions it needs. You see them, high-risk first, before anything is installed. A card without permissions can only draw inside its box.
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.
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.
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.
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.
A prompt or a tool call made through a card lights up the arrow it went over and lands in the 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
neurosquad-card.json.CardProvider and hooks.create, dev, validate, pack.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.