Skip to main content

Server

One call gives you the dashboard API, the agents' endpoints (/v1/agents/:id), the dashboard's sign-in and, on Node, the dashboard itself. All behind one fetch(request).

Run it​

npx sideagent runs it from environment variables. Without DATABASE_URL it uses an in-memory database (dev only).

Variable
SIDEAGENT_SECRETAt least 32 characters (openssl rand -base64 32). Required in production.
DATABASE_URLPostgres with the pgvector extension. Required in production.
PUBLIC_URLThe URL people type in the browser. Default http://localhost:$PORT.
PORTDefault 8788.
SIGNUPtrue lets new people create accounts. Default: only existing accounts sign in.
GITHUB_CLIENT_ID, GITHUB_CLIENT_SECRET, GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRETSocial sign-in.
SIDEAGENT_LOG_SIGN_IN_LINKStrue prints email sign-in links to the log. There is no mail sender here. Anyone who can read the log can sign in.

In your own code:

import { createServer } from "sideagent/server/node";

const server = createServer({
database: process.env.DATABASE_URL!,
publicUrl: "https://agent.example.com",
secret: process.env.SIDEAGENT_SECRET!,
auth: { sendMagicLink: (email, url) => mailer.send(email, url) },
});
await server.listen(8788);

createServer from sideagent/server is the same without the dashboard's files and listen: mount server.fetch in Hono, Next, Workers or anything that hands you a Request. See Cloudflare Workers.

Options​

OptionDefault
databaserequiredA Postgres URL (Node), a Drizzle Postgres database (Workers with Hyperdrive, PGlite, node-postgres, Neon...) or your own AdminStore. The tables are created and migrated on first use, except for your own store.
publicUrlrequiredThe server's public origin. Publishable keys name its host, and dashboard writes must carry it as Origin.
secretrequiredOne master secret. The key that wraps stored LLM keys and the one that signs sign-in cookies are derived from it, so rotating it signs everyone out and makes stored LLM keys unreadable.
authbundled sign-inEither { sendMagicLink, github, google, signup } for the bundled sign-in, or { session(request) } to use your own (SSO proxy, Auth.js...) instead.
scope(user, request)one shared workspaceWhich agents a user sees. Users with the same scope share them. Return user.id for one workspace per user, or an organisation id for teams. Another scope's agent answers 404.
builtinModelnoneYour own model, offered next to each owner's endpoint and metered per owner (BuiltinModel). On Cloudflare, see the Workers AI recipe.
challengenoneA bot challenge anonymous visitors solve before they chat (turnstileChallenge). Without it, anonymous agents are open.
rateLimit, clientIpper-process limiter, x-forwarded-forBehind a proxy that sets another header, read that one.
anonDailyMessages25Anonymous messages one agent answers per UTC day.
background(work)runs at onceKeeps work alive after the response, e.g. waitUntil.
onErrornoneHears every failed turn: { agentId, code, threadId, error }. The error can echo keys and customer text: log it, never return it.

createServer throws at once on a missing database, a publicUrl that is not a URL, or a missing secret; a secret shorter than 32 characters rejects server.ready. Email sign-in links are only printed to the log on localhost. Elsewhere, without sendMagicLink, email sign-in is refused (GitHub and Google keep working).

What it serves​

PathWhat
/api/agents…The dashboard API. Session required; writes must carry the server's own Origin.
/api/auth/*, /api/auth-providersThe bundled sign-in.
/api/health{ "ok": true }.
/v1/agents/:idAn agent's endpoint for end users. Needs the agent's publishable key.
the dashboardNode: served by sideagent/server/node. Elsewhere: upload dist/admin-ui as static assets, or pass ui.

Another database​

A database is an implementation of AdminStore (agents, usage counters, audit and traces, knowledge with vector search, threads and checkpoints). sideagent/server/store exports the type and runStoreContract / runThreadContract, the behaviour every store must have (they need vitest); run them against yours.

How a conversation behaves​

  • Follow-ups and unclear questions. A message that matches the knowledge only weakly is not refused at once. If it, together with the previous question, is close to the knowledge, the model gets it with the scope rules and may ask what the user means. Only a message with nothing close to it gets the fixed "off topic" reply, and the model is not called. Refusals stay visible to the user but are not shown to the model on later turns. Set the reply under Off-topic reply on the Knowledge page. It accepts Markdown (for example a link to your support page) and is sent as written; left empty, the model writes a short decline in the user's language, falling back to "I can't help with that."
  • Anonymous visitors continue a conversation through the id of its thread, which only that visitor holds. The conversation is stored in your database, like a signed-in user's, and deleted an hour after its last message (a visitor who returns later starts a new one, which the chat does by itself). It holds the visitor's messages, so count it in your privacy notice. Anonymous visitors have no history list.
  • One turn per thread. A second message sent to a thread while its turn is still running is refused with 409. Turns per user are limited too (429). Both limits are per process: behind several instances, send each thread to the same instance or add a shared limit in rateLimit.
  • A turn the browser abandons (tab closed, request aborted) stops the model and tools and is recorded in the audit log with the reason client_aborted. A tool call that never finished is shown to the model as interrupted, so the thread keeps working.

Security defaults​

  • Every dashboard query is scoped by scope. Another scope's agent answers like a missing one: 404.
  • Customer URLs (model, knowledge pages, token endpoints) pass an SSRF guard that also resolves DNS, and redirects are refused.
  • LLM keys are sealed with envelope encryption and are write-only in responses, logs and audit rows.
  • Provider errors never reach the end user. The owner previewing sees a coarse reason; the audit log gets a fixed one.
  • Traces keep no text at metadata, redact credentials at full, and expire after 7 and 3 days.
  • The agent's only tool is knowledge search; any other tool name the model asks for is refused.