Tabs Start here
Quickstart
Make a small app, see it in the local harness in a minute, then install it in a real workspace. You need Node 22 or later, and the Tabs & Spaces repository: the developer tools are in it, as yarn tands.
1. Make an app
From the repository's root:
yarn tands new ../team-notesIt makes a folder with a working app and no dependencies:
| File | What it is |
|---|---|
public/tands.json | The manifest: a tab, a collection, an action and an event |
public/tab.html | The tab: it greets whoever opens it and keeps notes for its space |
server.js | Serves both, and answers the add_note action after checking its token |
public/tands-sdk.js, lib/tands-sdk-server.js | The SDK, built and copied in (it isn't on npm yet) |
2. Run it in the harness
Start your app, then the harness, in two terminals:
cd ../team-notes && npm start # your app, on http://localhost:5480
yarn tands dev http://localhost:5480/tands.json # the harness, on http://localhost:5470Open http://localhost:5470. The harness stands in for a workspace: it shows your tab as someone you choose (their name, the space, the language), signs real tokens, keeps your data in memory, lists the events your app reports, and runs your actions on your server. Change who's looking and choose Open the tab; switch to dark and your tab follows. See Developer tools.
3. Install it in a workspace
When it works in the harness, try it in a real workspace on your machine.
Follow the repository's README to start the development servers. The web app runs at
http://localhost:5400.Installing an app makes the workspace's server fetch its manifest, and a workspace normally refuses addresses on private networks. In
apps/api/.env, setAPPS_PRIVATE_NETWORKS=true, then restart the API.Restart your app so it checks tokens with the workspace's keys:
shWORKSPACE_URL=http://localhost:5400 npm startAs an owner or admin, open Settings → Apps, paste
http://localhost:5480/tands.json, choose Check, then Install.In any space, choose + (Add tab) → Custom tab → Notes.
Ask an agent to add a note ("@Tabby add a note: lunch on Friday?"), and it uses your action, asking you first. Make a trigger in a Tasks tab on your note_added event, and a note starts a task.
4. Read the code
public/tands.json, the manifest. See The manifest.public/tab.html, the page, with the SDK'sconnect(). See Building a Custom tab and Keeping data.server.js, which answers the action. See Actions and Events.
The Hello example, at examples/hello-app, does the same things without the SDK: its page speaks the frame protocol directly.