Get started

1. Install the client

The attach surface is @sveda-ai/core. Vue (@sveda-ai/vue) and web components (@sveda-ai/element) are optional UI. Core does not require them. See JS client.

npm i @sveda-ai/core

2. Run sveda-server

The binary is sveda-server (Axum). It binds SVEDA_BIND, default 0.0.0.0:8787. Token minting is off until SVEDA_EMBED_ENABLED=true — otherwise POST /sveda/embed/token returns 404. Turns need a model key; the default catalog reads DEEPSEEK_API_KEY. Full route list: runtime. Postgres + Redis + image: deploy ( docker compose up --build ).

export SVEDA_EMBED_ENABLED=true
export SVEDA_BIND=0.0.0.0:8787
export DEEPSEEK_API_KEY=sk-...
sveda-server

3. Health

GET /sveda/health is unauthenticated. Body is { "ok": true, "runtime": "rust" }.

curl -s http://127.0.0.1:8787/sveda/health

4. Mint an embed token

Mint on the host, not in the browser. POST /sveda/embed/token with JSON visitor_id (optional; the runtime allocates a UUID when omitted). Response: token, visitor_id, expires_in. Tokens are prefixed sveda_embed_. If SVEDA_EMBED_HOST_API_KEY is set, send it as x-sveda-host-key. Handshake rules: embed token. Production hosts should mint from a backend SDK instead of curl — see step 6.

curl -s http://127.0.0.1:8787/sveda/embed/token \
  -H 'content-type: application/json' \
  -d '{"visitor_id":"visitor-123"}'

5. Send a turn

endpoints.stream is required. Point it at the runtime (or a reverse-proxy path). The client sends Accept: application/vnd.sveda.stream+json and the token as x-sveda-embed-token. Public verb is session.send, not stream. Events: stream protocol.

import { SvedaClient } from '@sveda-ai/core'

const token = 'sveda_embed_…'

const client = new SvedaClient({
  endpoints: {
    stream: 'http://127.0.0.1:8787/sveda/stream',
  },
  headers: {
    'x-sveda-embed-token': token,
  },
})

const session = client.session('chat_1')
await session.send('What does this workspace do?')

6. Connect a host SDK

Curl is for local. A real page mints on the server, then opens JS chat or an iframe. Each guide is numbered.

1. No framework — HTML, iframe, tiny HTTP.
2. PHP / Laravel
3. Python — Flask, Django, FastAPI, or plain Python.
4. Node — Express, NestJS, Next.js, or http.
5. Ruby / Go / Java / .NET