HOST
Ruby
gem 以 Bearer host 认证 mint embed token。Rails 为控制器与布局。
Ruby
gem 以 Bearer host 认证 mint embed token。Rails 为控制器与布局。
gem sveda-ruby-sdk、Sveda::Client.start_host_session，从 Rails 或 Rack 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 Ruby project.
Read:
- https://sveda.dev/docs/hosts/ruby
- https://sveda.dev/docs/client
- https://sveda.dev/docs/deploy
- https://sveda.dev/llms.txt
Follow the numbered steps on the Ruby page. If unsure which frontend this repo uses, ask the user.1. Run sveda-server
# 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. Add gem sveda-ruby-sdk
RubyGems:
sveda-ruby-sdk.
No Rails required for the gem itself.
gem "sveda-ruby-sdk"gem "sveda-ruby-sdk"
3. Env
Load
.env
in
config/boot.rb
(Rails) or at process start (plain Ruby).
SVEDA_CLIENT_BASE_URL=http://127.0.0.1:8787
SVEDA_CLIENT_HOST_API_KEY=replace-meSVEDA_CLIENT_BASE_URL=http://127.0.0.1:8787 SVEDA_CLIENT_HOST_API_KEY=replace-me
4. Plain Ruby
Empty base URL or key raises
Sveda::ConfigurationError.
Any Rack app can JSON-encode the hash.
Pass optional
policy
on mint when mapping roles to a named document —
embed policies.
session = Sveda::Client.start_host_session(
base_url: ENV.fetch("SVEDA_CLIENT_BASE_URL"),
host_api_key: ENV.fetch("SVEDA_CLIENT_HOST_API_KEY"),
visitor_id: "ruby-host"
)session = Sveda::Client.start_host_session(
base_url: ENV.fetch("SVEDA_CLIENT_BASE_URL"),
host_api_key: ENV.fetch("SVEDA_CLIENT_HOST_API_KEY"),
visitor_id: "ruby-host"
) 5. Rails
Keep
csrf_meta_tags
in the layout so
sveda-host.js
can send
X-CSRF-TOKEN.
Hide buttons unless
SVEDA_CLIENT_BASE_URL
is set.
# config/routes.rb
post "/sveda/session", to: "sveda_sessions#create"
# app/controllers/sveda_sessions_controller.rb
def create
render json: Sveda::Client.start_host_session(
base_url: ENV["SVEDA_CLIENT_BASE_URL"].to_s.strip,
host_api_key: ENV["SVEDA_CLIENT_HOST_API_KEY"].to_s.strip,
visitor_id: "rails-playground"
)
rescue Sveda::Error => error
render json: { message: error.message }, status: :service_unavailable
end# config/routes.rb
post "/sveda/session", to: "sveda_sessions#create"
# app/controllers/sveda_sessions_controller.rb
def create
render json: Sveda::Client.start_host_session(
base_url: ENV["SVEDA_CLIENT_BASE_URL"].to_s.strip,
host_api_key: ENV["SVEDA_CLIENT_HOST_API_KEY"].to_s.strip,
visitor_id: "rails-playground"
)
rescue Sveda::Error => error
render json: { message: error.message }, status: :service_unavailable
end 6. 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>