Quick start

You need NeuroSquad and Node.js 18.17 or newer. No developer account, and no build tools for the plain template.

1. Create a card

npx @neurosquad/card-sdk create my-card                    # plain HTML + JS, no build step
npx @neurosquad/card-sdk create my-card --template react   # React + Vite + TypeScript

Both templates give you the same working card: the agents on the canvas with live statuses, a scratchpad saved in the card’s storage, an input and an output port, and a tool connected agents can call. Read it, then change it.

Plain template (vanilla):

my-card/
  neurosquad-card.json   the manifest: name, size, permissions, settings, ports, tools
  index.html             the page loaded into the card
  main.js                the card's code
  style.css
  icon.png               square PNG or WebP, 128 KB at most
  vendor/                the SDK (card-sdk.js), the UI kit (ui.css), the mock host, the manifest schema

React template: the same manifest and icon, src/ with main.tsx, App.tsx and i18n.ts, and a Vite config already set up for cards (relative URLs, no inline scripts). Run npm install first; npm run build writes dist/, which is what the app loads.

2. See it without the app

Open the page on its own and it runs against a mock host with sample agents and a connected note, so you can work on the look in any browser:

npx serve .      # plain template, then open http://localhost:3000
npm run dev      # React template

In the browser console, mockHost drives it: mockHost.setAgentStatus('a2', 'working'), mockHost.setLanguage('ru'), mockHost.sendPortMessage('text', 'hello'). See Testing with the mock host.

3. Run it live in NeuroSquad

With the React template, dev also runs npm run watch for you, so dist/ is rebuilt on every save. Pass --no-build to run your own watcher.

Without the CLI. Settings → Custom cards → Link a folder… links a folder too — handy if you only want to try a card someone sent you as a folder.

4. Check it like the installer will

npx @neurosquad/card-sdk validate

validate runs the app’s own manifest checks and the installer’s file rules, warns about things the sandbox will block (inline scripts, external files), and prints the install dialog your users will see. pack goes one step further and lists exactly which files would be installed, with the tree hash the app records. See the CLI reference.

5. Publish it on GitHub

Push the card folder to a GitHub repository — its own repository, or a folder inside a bigger one. That’s all publishing is. A few things to get right:

• neurosquad-card.json must be at the root of the card folder.
• Commit your build output. The app installs straight from the repository and never runs a build. The React template’s .gitignore deliberately does not ignore dist/.
• Tag releases (v1.0.0) and people can install a fixed version, or follow your latest release.

More in Publishing & updates.

6. Install it from GitHub

In Settings → Custom cards → Install a card, paste your-name/my-card (or your-name/my-cards/pomodoro for a card in the pomodoro folder of a repository, your-name/my-card@v1.0.0 for a tag) and press Install. That’s what your users do; see Installing community cards.

The smallest possible card

No template needed. Three files:

{
  "manifestVersion": 1,
  "name": "hello-card",
  "displayName": "Hello",
  "version": "0.1.0",
  "protocol": 1
}

<!doctype html>
<html>
  <head>
    <meta charset="utf-8" />
    <script type="module" src="main.js"></script>
  </head>
  <body>
    <h1 id="title">…</h1>
  </body>
</html>

// card-sdk.js is dist/card-sdk.js from the @neurosquad/card-sdk package, copied next to this file.
import { connect } from './card-sdk.js'
 
const card = await connect()
document.getElementById('title').textContent = `Hello from ${card.workspace.name}`
card.setStatus('Ready', { tone: 'success' })

It asks for no permissions, so it can only draw in its box, keep storage and settings, and set its header — which is already a useful card.

Next