HOST

Node

Native fetch。startHostSession が sidecar と通信。ページは data-sveda-open でチャットを開く。

Node

Native fetch。startHostSession が sidecar と通信。ページは data-sveda-open でチャットを開く。

@sveda-ai/node-sdk、startHostSession、Express、Nest、Next または http から POST /sveda/session。

AGENT PROMPT

Paste into Cursor

Copy this into Cursor, Claude Code, or any coding agent. It installs Sveda against this stack using public packages.

Install Sveda into this Node project.

Read:
- https://sveda.dev/docs/hosts/node
- https://sveda.dev/docs/client
- https://sveda.dev/docs/deploy
- https://sveda.dev/llms.txt

Follow the numbered steps on the Node page. If unsure which frontend this repo uses, ask the user.

1. Run sveda-server

CORS origin is the Node host (8015–8017 in the playground). Next.js loads .env itself; Express and Nest should load it at boot.

# ghcr.io/neresson/sveda-server:latest
# curl -fsSL https://raw.githubusercontent.com/neresson/sveda/main/deploy/compose.yaml -o compose.yaml && curl -fsSL https://raw.githubusercontent.com/neresson/sveda/main/deploy/compose.env -o .env && # Edit .env: a model key, SVEDA_EMBED_HOST_API_KEY, SVEDA_CORS_ORIGINS &&  && docker compose up -d && curl -s http://127.0.0.1:8787/sveda/ready

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: sveda
      POSTGRES_PASSWORD: sveda
      POSTGRES_DB: sveda
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U sveda -d sveda"]
      interval: 5s
      timeout: 3s
      retries: 10
    volumes:
      - sveda-postgres:/var/lib/postgresql/data
  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 10
  sveda-server:
    image: ghcr.io/neresson/sveda-server:latest
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    ports:
      - "8787:8787"
    environment:
      SVEDA_BIND: 0.0.0.0:8787
      SVEDA_EMBED_ENABLED: "true"
      SVEDA_DATABASE_URL: postgres://sveda:sveda@postgres:5432/sveda
      SVEDA_REDIS_URL: redis://redis:6379
      SVEDA_APP_KEY: ${SVEDA_APP_KEY:-dev-app-key-change-me}
      SVEDA_ADMIN_API_KEY: ${SVEDA_ADMIN_API_KEY:-dev-admin-key-change-me}
      SVEDA_EMBED_HOST_API_KEY: ${SVEDA_EMBED_HOST_API_KEY:-dev-host-key-change-me}
      SVEDA_CORS_ORIGINS: ${SVEDA_CORS_ORIGINS:-*}
      DEEPSEEK_API_KEY: ${DEEPSEEK_API_KEY:-}
volumes:
  sveda-postgres:

# ghcr.io/neresson/sveda-server:latest
# curl -fsSL https://raw.githubusercontent.com/neresson/sveda/main/deploy/compose.yaml -o compose.yaml && curl -fsSL https://raw.githubusercontent.com/neresson/sveda/main/deploy/compose.env -o .env && # Edit .env: a model key, SVEDA_EMBED_HOST_API_KEY, SVEDA_CORS_ORIGINS &&  && docker compose up -d && curl -s http://127.0.0.1:8787/sveda/ready

services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: sveda
      POSTGRES_PASSWORD: sveda
      POSTGRES_DB: sveda
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U sveda -d sveda"]
      interval: 5s
      timeout: 3s
      retries: 10
    volumes:
      - sveda-postgres:/var/lib/postgresql/data
  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 10
  sveda-server:
    image: ghcr.io/neresson/sveda-server:latest
    depends_on:
      postgres:
        condition: service_healthy
      redis:
        condition: service_healthy
    ports:
      - "8787:8787"
    environment:
      SVEDA_BIND: 0.0.0.0:8787
      SVEDA_EMBED_ENABLED: "true"
      SVEDA_DATABASE_URL: postgres://sveda:sveda@postgres:5432/sveda
      SVEDA_REDIS_URL: redis://redis:6379
      SVEDA_APP_KEY: ${SVEDA_APP_KEY:-dev-app-key-change-me}
      SVEDA_ADMIN_API_KEY: ${SVEDA_ADMIN_API_KEY:-dev-admin-key-change-me}
      SVEDA_EMBED_HOST_API_KEY: ${SVEDA_EMBED_HOST_API_KEY:-dev-host-key-change-me}
      SVEDA_CORS_ORIGINS: ${SVEDA_CORS_ORIGINS:-*}
      DEEPSEEK_API_KEY: ${DEEPSEEK_API_KEY:-}
volumes:
  sveda-postgres:

2. Install @sveda-ai/node-sdk

ESM, Node 20+, native fetch. npm: @sveda-ai/node-sdk.

npm i @sveda-ai/node-sdk

npm i @sveda-ai/node-sdk

3. Env

SVEDA_CLIENT_BASE_URL=http://127.0.0.1:8787
SVEDA_CLIENT_HOST_API_KEY=replace-me

SVEDA_CLIENT_BASE_URL=http://127.0.0.1:8787
SVEDA_CLIENT_HOST_API_KEY=replace-me

4. Mint helper

No framework required: http.createServer can call startHostSession and return JSON.

import { startHostSession } from '@sveda-ai/node-sdk'

const payload = await startHostSession({
  baseUrl: process.env.SVEDA_CLIENT_BASE_URL,
  hostApiKey: process.env.SVEDA_CLIENT_HOST_API_KEY,
  visitorId: 'node-host',
})

import { startHostSession } from '@sveda-ai/node-sdk'

const payload = await startHostSession({
  baseUrl: process.env.SVEDA_CLIENT_BASE_URL,
  hostApiKey: process.env.SVEDA_CLIENT_HOST_API_KEY,
  visitorId: 'node-host',
})

5. Policy and tools

Roles stay in your app. Map them to a named policy on mint with policyUsing. resolveToolsUsing is a second host-side filter; the runtime still enforces the token policy. Policy documents live under sveda.yaml. Full contract: embed policies.

const host = new HostManager({
  baseUrl: process.env.SVEDA_CLIENT_BASE_URL,
  hostApiKey: process.env.SVEDA_CLIENT_HOST_API_KEY,
  mcpPath: '/mcp/sveda',
})

host.policyUsing((user) => (user.role === 'agent' ? 'agent' : 'reader'))

host.resolveToolsUsing((user) =>
  user.role === 'agent' ? [search, create] : [search],
)

const host = new HostManager({
  baseUrl: process.env.SVEDA_CLIENT_BASE_URL,
  hostApiKey: process.env.SVEDA_CLIENT_HOST_API_KEY,
  mcpPath: '/mcp/sveda',
})

host.policyUsing((user) => (user.role === 'agent' ? 'agent' : 'reader'))

host.resolveToolsUsing((user) =>
  user.role === 'agent' ? [search, create] : [search],
)

6. Express

app.post('/sveda/session', async (req, res) => {
  const baseUrl = String(process.env.SVEDA_CLIENT_BASE_URL ?? '').replace(/\/$/, '')
  const hostApiKey = String(process.env.SVEDA_CLIENT_HOST_API_KEY ?? '')
  if (!baseUrl || !hostApiKey) {
    return res.status(503).json({ message: 'Set SVEDA_CLIENT_BASE_URL and SVEDA_CLIENT_HOST_API_KEY' })
  }
  res.json(await startHostSession({ baseUrl, hostApiKey, visitorId: 'express-playground' }))
})

app.post('/sveda/session', async (req, res) => {
  const baseUrl = String(process.env.SVEDA_CLIENT_BASE_URL ?? '').replace(/\/$/, '')
  const hostApiKey = String(process.env.SVEDA_CLIENT_HOST_API_KEY ?? '')
  if (!baseUrl || !hostApiKey) {
    return res.status(503).json({ message: 'Set SVEDA_CLIENT_BASE_URL and SVEDA_CLIENT_HOST_API_KEY' })
  }
  res.json(await startHostSession({ baseUrl, hostApiKey, visitorId: 'express-playground' }))
})

7. NestJS

@Controller()
export class SvedaController {
  @Post('sveda/session')
  async startSession(@Res() res: Response) {
    const session = await startHostSession({
      baseUrl: process.env.SVEDA_CLIENT_BASE_URL,
      hostApiKey: process.env.SVEDA_CLIENT_HOST_API_KEY,
      visitorId: 'nestjs-playground',
    })
    res.json(session)
  }
}

@Controller()
export class SvedaController {
  @Post('sveda/session')
  async startSession(@Res() res: Response) {
    const session = await startHostSession({
      baseUrl: process.env.SVEDA_CLIENT_BASE_URL,
      hostApiKey: process.env.SVEDA_CLIENT_HOST_API_KEY,
      visitorId: 'nestjs-playground',
    })
    res.json(session)
  }
}

8. Next.js

App Router route app/sveda/session/route.js. Put origin on <html> in the root layout; put the buttons in the shell. Use force-dynamic so env is read per request.

// app/sveda/session/route.js
export async function POST() {
  const session = await startHostSession({
    baseUrl: process.env.SVEDA_CLIENT_BASE_URL,
    hostApiKey: process.env.SVEDA_CLIENT_HOST_API_KEY,
    visitorId: 'nextjs-playground',
  })
  return Response.json(session)
}

// app/sveda/session/route.js
export async function POST() {
  const session = await startHostSession({
    baseUrl: process.env.SVEDA_CLIENT_BASE_URL,
    hostApiKey: process.env.SVEDA_CLIENT_HOST_API_KEY,
    visitorId: 'nextjs-playground',
  })
  return Response.json(session)
}

9. Page markup

<html
  lang="en"
  data-sveda-origin="http://127.0.0.1:8787"
  data-sveda-session="/sveda/session"
>
  <body>
    <button type="button" data-sveda-open="js">Open JS chat</button>
    <button type="button" data-sveda-open="iframe">Open iframe chat</button>
    <script type="module" src="/sveda-host.js"></script>
  </body>
</html>

<html
  lang="en"
  data-sveda-origin="http://127.0.0.1:8787"
  data-sveda-session="/sveda/session"
>
  <body>
    <button type="button" data-sveda-open="js">Open JS chat</button>
    <button type="button" data-sveda-open="iframe">Open iframe chat</button>
    <script type="module" src="/sveda-host.js"></script>
  </body>
</html>

Host SDKs

Every language, same handshake.

Embed token

POST /sveda/embed/token, policies, capabilities.

Appearance

Host JS wins; sveda.yaml if omitted.

No framework

HTML, iframe, tiny HTTP.

Product: host SDKs

Why minting stays on the server.

Node

Node

Paste into Cursor

1. Run sveda-server

2. Install @sveda-ai/node-sdk

3. Env

4. Mint helper

5. Policy and tools

6. Express

7. NestJS

8. Next.js

9. Page markup

Related

Mint from the host.