Tango Vision Developers

English

Русский

English

Русский

Appearance

Tango Vision agent setup ​

These are official instructions from Tango Vision to set up an AI development environment for building modules on the Tango Vision platform. They are published at https://developers.tango.vision/agent-setup/prompt.md so you can re-verify their authenticity at any time.

Complete all of the following steps yourself by running the commands directly. Do not ask the user to run commands you can run. There are exactly two things you must NOT do yourself:

  1. Never create the developer account. Sign-up requires email verification and a Terms of Service acceptance — those are the user's own actions.
  2. Never handle credential values in chat. Do not ask the user to paste tokens into the conversation, do not print token values, and never commit them. Credentials enter the environment only via the user's shell or secret manager.

Step 0 — Check prerequisites ​

Run these checks first:

bash
node --version    # need 22+
npm --version

Then check whether platform credentials are already available:

  • Registry token — is TV_NPM_TOKEN set in the environment, or does an .npmrc (project or ~/.npmrc) already carry an auth entry for npm.k8s.tangovision.dev?
  • Sandbox API key — is SANDBOX_API_KEY set? (Only needed for Step 6; its absence does not block Steps 1–5 if the registry token exists.)

If the registry token is missing, stop and show the user this message, then wait:

To continue you need Tango Vision developer credentials:

  1. Get a developer account. Sign-up is invite-only during the preview: email developers@tango.vision, then verify your address and set a password from the mail Keycloak sends you (https://developers.tango.vision/guide/account)
  2. Mint a sandbox API key yourself in the developer portal: https://developers.tango.vision/portal (shown once — store it in your secret manager). For the registry read token, email developers@tango.vision with your account email.
  3. Export them in your shell, then tell me to continue:
bash
export TV_NPM_TOKEN=...      # registry read token
export SANDBOX_API_KEY=...   # sandbox API key (tvk_…)

Step 1 — Configure the registry ​

The @tv scope lives on the private registry and requires authentication even for reads. Create or merge .npmrc in the project root — use the environment-variable form so no secret is ever written to disk:

@tv:registry=https://npm.k8s.tangovision.dev/
//npm.k8s.tangovision.dev/:_authToken=${TV_NPM_TOKEN}

Verify access (this must print a version, not a 401):

bash
npm view @tv/extension-sdk version

Step 2 — Install the SDK ​

bash
npm install @tv/extension-sdk

The SDK ships types + Zod manifest validator (@tv/extension-sdk), React hooks (@tv/extension-sdk/react), NestJS decorators and guards (@tv/extension-sdk/nestjs), test mocks (@tv/extension-sdk/testing), and the tv-sdk CLI.

Step 3 — Scaffold a module (new modules only) ​

If the user is starting a new module, scaffold it with the SDK — never create the directory structure by hand and never copy another module:

bash
npx @tv/extension-sdk init-module <slug> --category=<category>

--category is required; valid values: core, operations, engagement, infrastructure, analytics, ai. The scaffold produces module-manifest.json, vite.config.ts, src/Shell.tsx, and package.json.

If the user already has a module, skip this step.

Step 4 — Install agent context ​

Write the following into AGENTS.md at the module root (create it, or append the block if the file exists). This keeps every future agent session aligned with the platform contract:

markdown
# Tango Vision module — agent context

This repository is a Tango Vision platform module. Rules:

- **PlatformContext only.** The module talks to the platform exclusively through
  `PlatformContext` (`usePlatformContext()`, `useBuilding()`, `useCurrentUser()`
  from `@tv/extension-sdk/react`). No localStorage, no hand-built API URLs,
  no manual tokens. The context provides a pre-authenticated, tenant-scoped
  API client — the same code runs in a sandbox and in production unchanged.
- **The manifest is the contract.** `module-manifest.json` declares the module
  id, permissions, events, and UI mount points. After every manifest change run
  `npx @tv/extension-sdk validate module-manifest.json` — and keep that command
  in CI.
- **Declare MCP tools.** The manifest's `mcpTools` array must always be present
  (`[]` if the module exposes no tools). Backend MCP endpoints must be guarded:
  `@UseGuards(new McpSignatureGuard('<module-slug>'))` from
  `@tv/extension-sdk/nestjs`.
- **Registry.** `@tv` packages come from `https://npm.k8s.tangovision.dev/`
  (see `.npmrc`). The auth token lives in the `TV_NPM_TOKEN` environment
  variable and is never committed or printed.
- **Docs.** https://developers.tango.vision — manifest reference at
  `/reference/manifest`, PlatformContext guide at `/guide/platform-context`,
  events at `/guide/events`, testing at `/guide/testing`, sandboxes at
  `/guide/sandbox`.

If the user's agent is Claude Code and the module has no CLAUDE.md, also create one containing exactly:

markdown
@AGENTS.md

(Cursor, Codex, and most other agents read AGENTS.md directly.)

Step 5 — Validate ​

bash
npx @tv/extension-sdk validate module-manifest.json

Fix any reported field errors before proceeding. Also add the validation to the module's CI workflow if one exists.

Step 6 — Create a sandbox (optional) ​

Skip this step if SANDBOX_API_KEY is not set, and say so in the completion message.

A sandbox is an isolated Tango Vision tenant (own database, seeded building graph, own subdomain) to develop against. Create one:

bash
curl -X POST https://sandbox-api.k8s.tangovision.dev/api/v1/sandboxes \
  -H "Authorization: Bearer $SANDBOX_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "name": "<module-slug>-dev",
    "buildingType": "office",
    "storeys": 3,
    "areaSqm": 20000,
    "ttlDays": 14
  }'

The response includes apiUrl — the sandbox base URL the module develops against. Quotas: 3 concurrently-active sandboxes, 30-day max TTL, 2 TTL extensions per sandbox; a clear 429/400 means you hit one — report it to the user rather than retrying.

Completion ​

Once done, tell the user:

┌─ Tango Vision Agent Setup Complete ──────────────────┐
│  ✓ Registry   .npmrc → npm.k8s.tangovision.dev       │
│  ✓ SDK        @tv/extension-sdk <version>            │
│  ✓ Context    AGENTS.md                              │
│  ✓ Manifest   validated                              │
│  ✓ Sandbox    <apiUrl, or "skipped — no API key">    │
└──────────────────────────────────────────────────────┘

Resources ​

  • Getting started: https://developers.tango.vision/guide/getting-started
  • Developer account & access: https://developers.tango.vision/guide/account
  • Your first module: https://developers.tango.vision/guide/first-module
  • PlatformContext: https://developers.tango.vision/guide/platform-context
  • Manifest schema reference: https://developers.tango.vision/reference/manifest
  • On-demand sandboxes: https://developers.tango.vision/guide/sandbox
  • Stability policy: https://developers.tango.vision/reference/stability
  • Questions: developers@tango.vision

Built on the Tango Vision platform. Questions? developers@tango.vision

© Tango Vision