Saltar al contenido
SVEDA
ES
Menú

HOST

Node

Native fetch. startHostSession habla con el sidecar.

Node

Native fetch. startHostSession habla con el sidecar.

@sveda-ai/node-sdk, startHostSession, POST /sveda/session desde Express, Nest, Next o http.

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:

2. Install @sveda-ai/node-sdk

ESM, Node 20+, native fetch. npm: @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

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',
})

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],
)

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' }))
})

7. NestJS

Register the controller on the root module. Missing env → 503 naming both variables. 

@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)
}

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>

Mint from the host.

Install the language SDK. Expose POST /sveda/session. Open JS chat or an iframe.

Host SDKs