Início

1. Install the client

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

npm i @sveda-ai/core

npm i @sveda-ai/core

2. Run sveda-server

The runtime is a Docker sidecar, image ghcr.io/neresson/sveda-server:latest. It binds 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 on the sidecar — an OpenAI or Anthropic key, a custom Responses / Anthropic URL, or the optional DeepSeek wrapper. See models. Install uses GitHub raw compose files (curl-safe). Browser copies: sveda.dev/compose.yaml — no clone or cargo build unless you are developing the runtime. Full route list: runtime. Postgres + Redis + Helm: deploy.

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

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

3. Health

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

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

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

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

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