# Quick start

> Create a card from a template, run it live in NeuroSquad with hot reload, publish it on GitHub and install it from there.

Source: https://docs.neurosquad.ai/en/card-sdk/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

```bash
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](https://docs.neurosquad.ai/en/card-sdk/api/ports), and a
[tool](https://docs.neurosquad.ai/en/card-sdk/api/tools) connected agents can call. Read it, then change it.

**Plain template** (`vanilla`):

```text
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:

```bash
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](https://docs.neurosquad.ai/en/card-sdk/testing).

## 3. Run it live in NeuroSquad

**1. Turn on developer mode**

In NeuroSquad: **Settings → Custom cards → Developer mode**. It lets the CLI on this computer ask
to link a folder; it listens only on `127.0.0.1`.

**2. Link the folder**

In your card folder run `npx @neurosquad/card-sdk dev`. The app asks you to confirm the link,
then shows the same permission dialog a user would see. Accept it.

**3. Add the card**

On the canvas: **+ → Custom card…** and pick your card (it has a **Dev** badge).

**4. Edit and save**

Every save reloads the card. The terminal running `dev` prints the card's log —
`card.log.*`, uncaught errors and rejected promises. Press **r** to reload by hand, **q** to quit.

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.

> Developer mode is not a way around consent: a linked folder gets exactly the permissions its
> manifest declares, after the same dialog. Change the permissions in the manifest and the card
> asks again.

**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

```bash
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](https://docs.neurosquad.ai/en/card-sdk/cli).

## 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](https://docs.neurosquad.ai/en/card-sdk/publishing).

## 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](https://docs.neurosquad.ai/en/card-sdk/community-cards).

## The smallest possible card

No template needed. Three files:

```json filename="neurosquad-card.json"
{
  "manifestVersion": 1,
  "name": "hello-card",
  "displayName": "Hello",
  "version": "0.1.0",
  "protocol": 1
}
```

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

```js filename="main.js"
// 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

  - **[Manifest reference](https://docs.neurosquad.ai/en/card-sdk/manifest)**: Size, permissions, settings, ports, tools.
  - **[API reference](https://docs.neurosquad.ai/en/card-sdk/api)**: What `card.*` can do.
  - **[Security checklist](https://docs.neurosquad.ai/en/card-sdk/security)**: Before you share it.