Server Deployment
Updated August 2026 (SAGE3 server v1.6)
The SAGE3 server can be deployed on a Window, Mac or Linux machine with a fully qualified name and a SSL certificate to support HTTPS. It includes a series of containers running the services required for the SAGE3 platform (using docker compose).
- For reference, SAGE3 is composed of
- `redis-server`: in-memory database
- `node-server`: web server
- `fluentd-server`: logging server
- `kernelserver`: jupyter kernel management
- `jupyter`: jupyter server
- `chromadb`: Vector database for AI services
- `seer`: Python backend for AI services
- `livekit-server`: self-hosted video server (SFU) for screen sharing, optional
To update a server, here are the files to keep/move/backup:
- Your assets (images, PDF, movies, …) are in the
configurations/node/assetssub folder.- Files to save if you want to backup your server.
- Your plugins are in the
configurations/node/pluginssub folder.- Files to save if you want to backup your server.
- The database data (rooms, boards, users, …) is in
configurations/redis/data/dump.rdbfile- File to save if you want to backup your server.
- Your SSL certificate is in
configurations/traefik/certs:certificate.crtandprivate.key(see SSL certificate)- Files to save, and to copy into the new installation when you update.
Requirements
- Windows, MacOS, or Linux operating system
- Docker installation
- Fully Qualified Domain Name (FQDN)
- i.e. A hostname recognized on a public network or your institutions private network
- Ex. myserver.mycompany.com
- Ex. myserver.cs.university.edu
- i.e. A hostname recognized on a public network or your institutions private network
- SSL certificate for the server (or a wildcard certificate for the domain) and its private key, copied into
configurations/traefik/certsduring installation (see SSL certificate) - Optional services:
- Google OAuth credentials, for authentication
- CILogin OAuth credentials, for authentication
- Apple with 'Sign in with Apple' credentials, for authentication
- For screen sharing: UDP port 7882 and TCP port 7881 reachable on the host — see Screen sharing. Servers already on Twilio may keep using it.
- LLM provider credentials (API keys and/or endpoints), for AI services — see AI Configuration
Installation
Linux is the main platform for SAGE3 production deployment. MacOS and Windows are supported for development and testing. The following instructions are for Linux, MacOS, and Windows.
Linux
We are mostly using Ubuntu, but the instructions should be similar for other distributions.
- Install Docker for ubuntu
- Do not install
Docker Desktopfor Ubuntu. Instead, installDocker Enginefor Ubuntu - Have a
sudocapable user account (not root)
# Open a Terminal
# Install docker
sudo apt-get install docker.io docker-compose-plugin
# Add the user to the docker group
sudo usermod -aG docker [username]
# Create the new group
newgrp docker
# Close terminal and open a new one
- Test docker installation
# Open a Terminal
# Check docker status
docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
# Run the test container hello-world
docker run --rm hello-world
# It pulls hello-world image
# It runs the image
# It deletes the container after it is done
- Install NodeJS 20.xx
- Installation using NodeSource repository
# Open a Terminal
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
- Test NodeJS installation
# Open a Terminal
node -v
- Download a SAGE3 server package:
- SAGE3 AMD64 Server Package for Intel CPUs — this permanent link always serves the newest release; versioned packages are listed under Releases.
# Open a Terminal
# Download the package into your user's home folder
cd ~
curl -LO https://github.com/SAGE-3/next/releases/download/server-latest/SAGE3-amd64.tgz
# Optional: verify the download
curl -LO https://github.com/SAGE-3/next/releases/download/server-latest/SAGE3-amd64.tgz.sha256
sha256sum -c SAGE3-amd64.tgz.sha256
# Extract file — the archive extracts to a folder named after the packaged version
tar xvfz SAGE3-amd64.tgz
cd SAGE3-1.6
- Copy your SSL certificate and its private key into the Traefik folder,
configurations/traefik/certs. Traefik handles HTTPS for the whole server and reads exactly these two file names:certificate.crtandprivate.key. See SSL certificate for the file format and for renewals.
# Open a Terminal
# Copy your certificate and private key into the Traefik certs folder, renaming them
cp CERTIFICATE_FILE ~/SAGE3-1.6/configurations/traefik/certs/certificate.crt
cp PRIVATE_KEY_FILE ~/SAGE3-1.6/configurations/traefik/certs/private.key
- Generate JWT Keys and Token
# Open a Terminal
# Switch to the SAGE3 Node Keys Directory
cd ~/SAGE3-1.6/configurations/node/keys
# Generate JWT Keys and Token
./genJWT_keys.sh
./genJWT_token.sh
- Edit the
.envFile
# Open a Terminal
# Change directory to the SAGE3 Server Folder
cd ~/SAGE3-1.6
# Edit .env file and add the name of your server and the token you just generated. Leave other variables as is.
vim .env
SAGE3_SERVER=YOUR_SERVERS_HOST_NAME
TOKEN= # token value copied without “” from: configurations/node/keys/token.json
LIVEKIT_API_SECRET= # optional, turns on screen sharing: any value of 32+ characters, e.g. the output of `uuidgen`. See "Screen sharing" below.
CHROMA_SERVER_AUTHN_CREDENTIALS=...
CHROMA_CLIENT_AUTH_CREDENTIALS=...
- Edit the Configuration file
sage3-prod.hjson
# Open a Terminal
# Change directory to the SAGE3 Server Node Folder
cd ~/SAGE3-1.6/configurations
# Edit the sage3-prod.hjson file with your preferred editor
# The file is documented with instructions.
vim sage3-prod.hjson
- Pull the Docker Images
# Open a Terminal
# Change to the SAGE3 Server Directory
cd ~/SAGE3-1.6
# Pull images
docker compose pull
# Might take a while but results should be:
✔ redis-server Pulled 0.3s
✔ node-server Pulled 0.3s
✔ seer Pulled 0.3s
✔ fluentd-server Pulled 0.3s
✔ jupyter Pulled 1.1s
✔ chromadb Pulled 0.3s
✔ kernelserver Pulled 0.2s
✔ livekit-server Pulled 0.4s
- Start the Server
# Open a Terminal
# Change to the SAGE3 Server Directory
cd ~/SAGE3-1.6
# Start Server
./GO
# To Stop the Server
./STOP
Windows
-
Install Docker Desktop for Windows
-
Install Windows Subsystem for Linux WSL using distribution Ubuntu 22.04
# Open Powershell
wsl --install -d Ubuntu-22.04
- (optional) You can install Visual Studio Code WSL Extension to edit files inside WSL.
- Install Node.js within the WSL subsystem
# Open Powershell and switch to WSL
wsl
# Ensure Curl is installed
sudo apt-get install curl
# Install Node.js repository
curl -sL https://deb.nodesource.com/setup_20.x | sudo -E bash -
# Install Node.js
sudo apt-get install -y nodejs
# Test
node -v
- Download the SAGE3 AMD64 Server Package and extract it within the WSL subsystem
# Open Powershell and switch to WSL
wsl
# Download the package into your user's home folder
cd ~
curl -LO https://github.com/SAGE-3/next/releases/download/server-latest/SAGE3-amd64.tgz
# Optional: verify the download
curl -LO https://github.com/SAGE-3/next/releases/download/server-latest/SAGE3-amd64.tgz.sha256
sha256sum -c SAGE3-amd64.tgz.sha256
# Extract file — the archive extracts to a folder named after the packaged version
tar xvfz SAGE3-amd64.tgz
cd SAGE3-1.6
- Copy your SSL certificate and its private key into the Traefik folder,
configurations/traefik/certs. Traefik handles HTTPS for the whole server and reads exactly these two file names:certificate.crtandprivate.key. See SSL certificate for the file format and for renewals.
# Open Powershell and switch to WSL
wsl
# Copy your certificate and private key into the Traefik certs folder, renaming them
cp CERTIFICATE_FILE ~/SAGE3-1.6/configurations/traefik/certs/certificate.crt
cp PRIVATE_KEY_FILE ~/SAGE3-1.6/configurations/traefik/certs/private.key
- Generate JWT Keys and Token
# Open Powershell and switch to WSL
wsl
# Switch to the SAGE3 Node Keys Directory
cd ~/SAGE3-1.6/configurations/node/keys
# Generate JWT Keys and Token
./genJWT_keys.sh
./genJWT_token.sh
- Edit the
.envFile
# Open Powershell and switch to WSL
wsl
# Change directory to the SAGE3 Server Folder
cd ~/SAGE3-1.6
# Edit .env file with your preferred editor
vim .env
SAGE3_SERVER=YOUR_SERVERS_HOST_NAME
TOKEN= # token value copied without “” from: configurations/node/keys/token.json
LIVEKIT_API_SECRET= # optional, turns on screen sharing: any value of 32+ characters, e.g. the output of `uuidgen`. See "Screen sharing" below.
- Edit the Configuration file
sage3-prod.hjson
# Open Powershell and switch to WSL
wsl
# Change directory to the SAGE3 Server Node Folder
cd ~/SAGE3-1.6/configurations/node
# Edit the sage3-prod.hjson file with your preferred editor
# The file is documented with instructions.
vim sage3-prod.hjson
-
Start Docker Desktop within Windows
-
Pull the Docker Images
# Open Powershell and switch to WSL
wsl
# Change to the SAGE3 Server Directory
cd ~/SAGE3-1.6
# Pull images
sudo docker compose pull
# Might take a while but the results should be similar to:
Pulling redis-server ... done
Pulling node-server ... done
Pulling python ... done
Pulling jupyter ... done
Pulling fluentd ... done
pulling fastapi ... done
- Start the Server
# Open Powershell and switch to WSL
wsl
# Change to the SAGE3 Server Directory
cd ~/SAGE3-1.6
# Start Server
./GO
# To Stop the Server
./STOP
MacOS
- Install Docker Desktop for macOS
- Make sure to select the architecture (M1 or Intel) that matches your machine
- Install NodeJS 20.xx
- Navigate to NodeJS Downloads and download the latest v20.x of NodeJS for your machine
- Download a SAGE3 server package:
- SAGE3 ARM64 Server Package for Arm CPUs (Apple Silicon, Ampere, ...) and extract it
- SAGE3 AMD64 Server Package for Intel CPUs and extract it
These permanent links always serve the newest release; versioned packages are listed under Releases.
# Open a Terminal
# Download the package into your user's home folder
cd ~
curl -LO https://github.com/SAGE-3/next/releases/download/server-latest/SAGE3-arm64.tgz
# Optional: verify the download
curl -LO https://github.com/SAGE-3/next/releases/download/server-latest/SAGE3-arm64.tgz.sha256
shasum -a 256 -c SAGE3-arm64.tgz.sha256
# Extract file — the archive extracts to a folder named after the packaged version
tar xvfz SAGE3-arm64.tgz
cd SAGE3-1.6
- Copy your SSL certificate and its private key into the Traefik folder,
configurations/traefik/certs. Traefik handles HTTPS for the whole server and reads exactly these two file names:certificate.crtandprivate.key. See SSL certificate for the file format and for renewals.
# Open a Terminal
# Copy your certificate and private key into the Traefik certs folder, renaming them
cp CERTIFICATE_FILE ~/SAGE3-1.6/configurations/traefik/certs/certificate.crt
cp PRIVATE_KEY_FILE ~/SAGE3-1.6/configurations/traefik/certs/private.key
- Generate JWT Keys and Token
# Open a Terminal
# Switch to the SAGE3 Node Keys Directory
cd ~/SAGE3-1.6/configurations/node/keys
# Generate JWT Keys and Token
./genJWT_keys.sh
./genJWT_token.sh
- Edit the
.envFile
# Open a Terminal
# Change directory to the SAGE3 Server Folder
cd ~/SAGE3-1.6
# Edit .env file with your preferred editor
vim .env
SAGE3_SERVER=YOUR_SERVERS_HOST_NAME
TOKEN= # token value copied without “” from: configurations/node/keys/token.json
LIVEKIT_API_SECRET= # optional, turns on screen sharing: any value of 32+ characters, e.g. the output of `uuidgen`. See "Screen sharing" below.
- Edit the Configuration file
sage3-prod.hjson
# Open a Terminal
# Change directory to the SAGE3 Server Node Folder
cd ~/SAGE3-1.6/configurations
# Edit the sage3-prod.hjson file with your preferred editor
# The file is documented with instructions.
vim sage3-prod.hjson
-
Start Docker Desktop for macOS
-
Pull the Docker Images
# Open a Terminal
# Change to the SAGE3 Server Directory
cd ~/SAGE3-1.6
# Pull images
docker compose pull
# Might take a while but the results should be similar to:
✔ redis-server Pulled 0.3s
✔ node-server Pulled 0.3s
✔ seer Pulled 0.3s
✔ fluentd-server Pulled 0.3s
✔ jupyter Pulled 1.1s
✔ chromadb Pulled 0.3s
✔ kernelserver Pulled 0.2s
✔ livekit-server Pulled 0.4s
- Start the Server
# Open a Terminal
# Change to the SAGE3 Server Directory
cd ~/SAGE3-1.6
# Start Server
./GO
# To Stop the Server
./STOP
Configuration
The server configuration file is located here: /configurations/node/sage3-prod.hjson.
This is a JSON file that support comments and slightly more relaxed syntax. Make sure to stop the server (./STOP) before editing the file, and restart the server afterwards (./GO)
This file allows you to configure your server to your specific needs.
{
// Is the server in production mode.
// Leave as true if you are deploying your server.
"production": true,
// Name of the server to show in the UI
"serverName": "My Local Server",
// Internal ports of the SAGE3 services, behind Traefik. Leave as is.
// HTTPS (port 443) and the SSL certificate are handled by Traefik,
// see "SSL certificate" below: there is no certificate setting in this file.
"port": 3000,
"port_yjs": 3001,
"port_files": 3002,
// These can be left alone, they are used to find the assets
"root": ".",
"public": "dist/apps/homebase/assets",
"assets": "dist/apps/webapp/assets/",
// Redis Database Config
"redis": {
// The Redis Database URL.
// If using the default deployment, leave as such.
"url": "redis://redis-server:6379"
},
// Fluentd log configuration
"fluentd": {
"server": "fluentd-server",
"port": 24224,
"databaseLevel": "partial" // all | partial | none
},
// Webserver configuration
"webserver": {
"logLevel": "all", // all | partial | none,
"uploadLimit": "5GB" // file upload size limit in string, optional units: KB, MB, GB, TB
},
// Fastapi python server for kernels
"kernels": {
"url": "http://kernelserver:8000"
},
// Fastapi python server for agents
"agents": {
"url": "http://seer:9999"
},
// VEO VNC container orchestration server (optional, required for CoBrowser app)
"veoServer": {
"url": ""
},
// External Services
"services": {
// Screen sharing: nothing to configure here. It runs on the self-hosted LiveKit
// server included in the deployment and is turned on by setting LIVEKIT_API_SECRET
// in the .env file (see the "Screen sharing" section of this guide).
// The twilio block is only for servers that still use Twilio Video; leave it
// empty otherwise. When both are configured, LiveKit is used.
twilio: {
// Your Account SID from www.twilio.com/console
accountSid: "",
// API Key.
apiKey: "",
// API Secret
apiSecret: ""
},
// AI / LLM configuration — a capability-driven model registry.
// See the "AI Configuration" section below for details.
"models": {
// One entry per provider. Each provider lists one or more models, and
// each model declares what it can do via "capabilities":
// chat | code | vision | imagegen | embeddings
"providers": {
"azure": {
"apiKey": "",
"url": "https://my-resource.openai.azure.com",
"models": {
"chat": {
"model_id": "gpt-5.2-chat",
"capabilities": ["chat", "code", "vision"],
"max_tokens": 4096,
"context_window": 128000,
"api_version": "2025-04-01-preview"
},
"imagegen": {
"model_id": "gpt-image-1.5",
"capabilities": ["imagegen"],
"api_version": "2025-04-01-preview"
}
}
},
"openai": {
"apiKey": "",
"models": {
"gpt4": {
"model_id": "gpt-4-turbo",
"capabilities": ["chat", "code", "vision"],
"max_tokens": 4096,
"context_window": 128000
}
}
},
// Any OpenAI-compatible endpoint (e.g. a LiteLLM / vLLM gateway hosting Llama)
"litellm": {
"url": "https://my-gateway.example.edu/",
"models": {
"llama4": {
"model_id": "meta/llama-4-scout-17b-16e-instruct",
"capabilities": ["chat", "code", "vision"],
"max_tokens": 4096,
"context_window": 32768
}
}
}
},
// Shared retrieval infrastructure for PDF question-answering (not a
// per-provider capability). NeMo Retriever embedding + reranking NIMs.
"embed": {
"url": "http://localhost:8000",
"model": "nvidia/llama-nemotron-embed-1b-v2"
},
"rerank": {
"url": "http://localhost:8001",
"model": "nvidia/llama-nemotron-rerank-1b-v2"
},
// Optional: olmOCR PDF -> Markdown via a remote vLLM server.
// Omit this block to fall back to pymupdf4llm text extraction.
"pdf2md": {
"url": "https://my-gateway.example.edu/olmocr/v1",
"model": "allenai/olmOCR-2-7B-1025-FP8"
},
"settings": {
// Provider used by default when a user has not picked one
"default_provider": "azure",
"timeout_seconds": 60,
"max_retries": 3,
"log_requests": true
}
}
},
// How to enable/disable some features for safety
"features": {
// Enable Plugins. Allows uploading of Webapps.
plugins: true,
// Which Apps to enable. Available Apps:
apps: ["Chat", "CodeEditor", "Map", "Notepad", "SageCell", "Stickie", "Screenshare", "Webview", "Poll", "Drawing", "Calculator", "Hawaii Mesonet"]
},
// Auth Configuration
"auth": {
// Secret HASH for the sessions. Change this to something unique.
"sessionSecret": "SUPERSECRET!!$$",
// Max age for a session per user. In milliseconds. 7 days
"sessionMaxAge": 604800000,
// Which login strategies to enable for the server.
// Available: google, apple, cilogon, keycloak, ldap, guest, spectator, jwt
// If you enable them ensure you add the relevant config information below.
"strategies": [
"google",
"apple",
"cilogon",
"keycloak",
"ldap",
"guest",
"spectator",
"jwt"
],
// A List of emails to enable those users to be admins.
// This will enable a ADMIN page for these users.
"admins": [ "toto@example.com", "john@google.com" ],
// Guest configuration
"guestConfig": {
// Endpoint for the guest login. No need to change this
"routeEndpoint": "/auth/guest"
},
// Spectator configuration
"spectatorConfig": {
// Endpoint for the spectator login. No need to change this
"routeEndpoint": "/auth/spectator"
},
// Google configuration
"googleConfig": {
// Client ID from the Google Developer Console
"clientID": "",
// Client Secret from the Google Developer Console
"clientSecret": "",
// Endpoint for the google login
"routeEndpoint": "/auth/google",
// Callback URL for the google login
"callbackURL": "/auth/google/redirect"
},
// Apple configuration
"appleConfig": {
// It is the service id name
"clientID": "",
// Your Apple developer team ID
"teamID": "",
// Key ID
"keyID": "",
// Private key file location
"privateKeyLocation": "./keys/apple-key.p8",
"callbackURL": "/auth/apple/redirect",
"routeEndpoint": "/auth/apple"
},
// JWT configuration
"jwtConfig": {
// The issuer of the JWT
"issuer": "sage3app@gmail.com",
// The audience of the JWT
"audience": "sage3.app",
// Public key location. Leave this alone
"publicKey": "./keys/jwt_public.pem",
// JWT Route endpoint
"routeEndpoint": "/auth/jwt"
},
// CILogon configuration
"cilogonConfig": {
// Client ID from CILogon
"clientID": "",
// Client Secret from CILogon
"clientSecret": "",
// Endpoint for the cilogon login
"routeEndpoint": "/auth/cilogon",
// Callback URL for the cilogon login
"callbackURL": "/auth/cilogon/redirect"
},
// Keycloak (or any OpenID Connect provider) configuration
"keycloakConfig": {
// Full Keycloak realm URL — all OIDC endpoints are autodiscovered from this
"issuerURL": "https://keycloak.example.com/realms/sage3",
// Client ID created in the Keycloak realm
"clientID": "sage3",
// Client Secret (leave empty for public clients)
"clientSecret": "",
// Endpoint to initiate Keycloak login
"routeEndpoint": "/auth/keycloak",
// Must match the redirect URI configured in your Keycloak client
"callbackURL": "/auth/keycloak/redirect"
},
// LDAP / Active Directory configuration
"ldapConfig": {
// ldap:// for plain (port 389) or ldaps:// for TLS (port 636)
"url": "ldaps://ldap.example.com:636",
// Service account used to search the directory (read access is enough)
"bindDN": "cn=svc-sage3,ou=ServiceAccounts,dc=example,dc=com",
"bindCredentials": "CHANGE_ME",
// Base DN under which users are searched
"searchBase": "ou=People,dc=example,dc=com",
// {{username}} is replaced at login time.
// OpenLDAP: "(uid={{username}})" — Active Directory: "(sAMAccountName={{username}})"
"searchFilter": "(uid={{username}})",
// Map LDAP group DNs (from the user's memberOf attribute) to SAGE3 roles.
// Checked in priority order admin > user > spectator; omit a key to skip it.
"groupMapping": {
"admin": "cn=sage3-admins,ou=Groups,dc=example,dc=com",
"user": "cn=sage3-users,ou=Groups,dc=example,dc=com",
"spectator": "cn=sage3-readonly,ou=Groups,dc=example,dc=com"
},
// Role assigned when the user matches no groupMapping entry: admin | user | spectator
"defaultRole": "spectator",
// TLS options passed to Node.js tls.connect.
// Set "rejectUnauthorized": false only for self-signed certs in dev/test.
"tlsOptions": {
"rejectUnauthorized": true
}
}
},
// Namespace for signing UUID v5 keys: generate yours or https://www.uuidtools.com/generate/v4
"namespace": "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
}
SSL certificate
Traefik, the reverse proxy in front of all SAGE3 services, handles HTTPS on port 443. It reads the certificate from two files in configurations/traefik/certs, with these exact names (set in configurations/traefik/dynamic.yml):
-
certificate.crt: your server certificate in PEM format. If your certificate authority gave you intermediate certificates (a "CA bundle" or "chain"), put them in the same file after your server certificate, so that browsers and the SAGE3 clients can verify it:cat YOUR_SERVER_CERTIFICATE YOUR_CA_BUNDLE > configurations/traefik/certs/certificate.crt -
private.key: the private key of that certificate in PEM format, without a passphrase.
There is no certificate setting in sage3-prod.hjson, and the configurations/node/keys folder holds only the JWT keys and token. To check the files, see the FAQ.
To renew the certificate, replace both files and restart Traefik:
cd ~/SAGE3-1.6
cp NEW_CERTIFICATE_FILE configurations/traefik/certs/certificate.crt
cp NEW_PRIVATE_KEY_FILE configurations/traefik/certs/private.key
docker compose restart traefik
Authentication
Login methods are enabled through the auth.strategies list; each strategy reads its own config block (shown above). Google, Apple, and CILogon are OAuth services that require credentials from the respective provider; guest and spectator need no external setup; jwt is for API/service access using the keys generated during install.
Keycloak (keycloakConfig) works with Keycloak or any OpenID Connect provider. Create a client in your realm, set its redirect URI to https://YOUR_SERVER/auth/keycloak/redirect, and put the realm URL and client ID/secret in the config — all OIDC endpoints are autodiscovered from the issuer URL. To try it locally: docker run -p 8080:8080 -e KC_BOOTSTRAP_ADMIN_USERNAME=admin -e KC_BOOTSTRAP_ADMIN_PASSWORD=admin quay.io/keycloak/keycloak:latest start-dev, then create a realm and client at http://localhost:8080.
LDAP / Active Directory (ldapConfig) authenticates users with a username + password form against your directory (via POST /auth/ldap). It needs a read-only service account (bindDN/bindCredentials), a search base and filter to locate users (use (sAMAccountName={{username}}) for Active Directory), and can optionally map directory groups to SAGE3 roles through groupMapping — users matching no mapped group get defaultRole. Use ldaps:// in production; certificate checking is on by default via tlsOptions.
AI Configuration
AI is configured under services.models as a capability-driven model registry. Instead of one fixed entry per provider, you declare any number of providers, each listing one or more models, and each model advertises what it can do. The web app and the Seer agent then pick a model by matching the task to the model's capabilities — so adding a provider or model is a config change, not a code change.
Migrating from an older server? The previous
openai/llama/codellama/yoloblocks have been replaced by the singlemodelsblock shown above. Move your keys and endpoints intomodels.providers.
Capabilities a model can declare:
| Capability | Used for |
|---|---|
chat | General chat and document (PDF) question-answering |
code | Code generation / explanation (CodeEditor, SageCell) |
vision | Image question-answering (describe, compare, filter/select) |
imagegen | Image generation |
embeddings | Text embeddings (Azure/OpenAI option for PDF retrieval) |
Tasks are matched to capabilities automatically: chat → chat, coding → code, image → vision, image_generation → imagegen, and pdf_processing → chat (PDF retrieval uses the shared embed/rerank infrastructure below, so it does not require a per-provider embeddings model). The web app only offers a task to the user when the selected provider has a model with the required capability.
Each provider entry takes an apiKey and/or a url:
apiKeyonly — a hosted service keyed by provider (e.g. OpenAI).urlonly — an unauthenticated or network-local endpoint (e.g. a self-hosted gateway).url+apiKey— an authenticated custom endpoint (e.g. Azure OpenAI, a LiteLLM/vLLM gateway). Any OpenAI-compatible endpoint works.
How the endpoint is spoken to is inferred from the config: a model with an api_version and a provider url is treated as Azure OpenAI; a url without api_version is treated as a generic OpenAI-compatible endpoint (/v1 is appended automatically, so "http://myhost:11434" is enough for e.g. Ollama); no url at all means openai.com. The model_id must match the name the endpoint reports under /v1/models.
Per-model fields: model_id (the provider's actual model name), capabilities (array), and optional max_tokens, api_version, cost_per_1k_input, cost_per_1k_output. context_window is optional but recommended for chat models — it budgets how much PDF text is stuffed for summary questions. If unset it defaults to 32768 (with a warning in the Seer log), and long or multi-PDF summaries may be truncated.
Shared PDF retrieval infrastructure (top-level under models, not per provider):
embed— NeMo Retriever embedding NIM ({ url, model }), used to index and search PDF text.rerank— NeMo Retriever reranking NIM ({ url, model }), used to re-order retrieved passages.pdf2md— optional olmOCR PDF→Markdown vLLM server ({ url, model }). The URL must include the/v1path (e.g.http://host:8002/v1) — olmocr appends only/chat/completionsto it. If omitted, Seer falls back topymupdf4llmtext extraction.
Switching embedding models requires a fresh Chroma collection, because the vector dimension changes.
settings holds the default_provider (used when a user has not chosen one) plus timeout_seconds, max_retries, and log_requests.
Users bringing their own key
Alongside the providers configured above, a user can supply their own OpenAI-compatible API key from Settings → Intelligence, where it appears as an extra provider named my-own-key in the same list as the server's providers.
The form takes three things:
| Field | Meaning |
|---|---|
| API key | The user's key. Required. |
| Base URL | Optional. Blank means https://api.openai.com/v1. Any OpenAI-compatible endpoint works; /v1 is appended if missing, so https://myhost is enough. An Azure OpenAI resource address (https://myresource.openai.azure.com) is completed to its /openai/v1 surface. |
| Model | The model to call. Chosen from a dropdown when the endpoint can be queried, typed by hand otherwise. |
As soon as a key and base URL are entered, the browser calls GET {baseUrl}/models with the key and offers the result as a dropdown. The lookup is debounced, and any lookup still in flight is cancelled when either field changes again. If the endpoint does not answer — no /models route, a rejected key, or a network or CSP failure — the field falls back to free text so the model name can be typed instead.
Capabilities. A user-supplied model is assumed to handle chat, code, and vision, which enables the chat, coding, image and pdf_processing tasks. It never advertises imagegen or embeddings: there is no way to ask an arbitrary endpoint what its model supports, so claiming those would light up UI that then fails at request time. Image generation therefore stays on the server's providers.
Where the key lives. Only in that browser, never in the SAGE3 database and never in the user's account record. It is sent with each AI request the user makes, used for that one request, and never persisted server-side. It is kept out of the s3_user_settings bundle deliberately, so that Restore Default Settings cannot silently delete it. Clearing the browser's site data for the server removes it, and so does logging out of SAGE3, so a key does not outlive its owner's session on a shared machine. How it is stored is described next.
How the key is protected. The key is stored encrypted, using only what the browser provides:
- On the first save, the browser generates a 256-bit AES-GCM key with the WebCrypto API, marked non-extractable, and keeps it in IndexedDB (database
s3_user_llm_keys). A non-extractable key can be used by scripts on that origin to encrypt and decrypt, but its bytes can never be read out, exported, copied, or backed up in usable form. The browser enforces this, not SAGE3. - The API key is encrypted with it, using a fresh random 96-bit IV each time it is saved, and the result is written to
localStorageunders3_user_llmas{ v: 2, modelId, baseUrl, enc }, whereencis the IV followed by the ciphertext, base64-encoded. The model id and base URL are not secrets and stay readable, so the settings form and the provider list do not depend on a decryption. - Decryption happens only when a request needs the key or the settings panel opens. Ciphertext whose IndexedDB key is gone (site data partially cleared, storage synced without IndexedDB) is discarded and the panel behaves as if no key was ever saved; the user re-enters it once.
- Removing the key, and a successful logout, delete both the ciphertext and the IndexedDB key.
- A key saved by a SAGE3 version older than this one, in clear, is re-saved encrypted the first time it is read.
- Where IndexedDB or WebCrypto is unavailable (strict private modes, some kiosks), the key is held in memory for the session only rather than written in clear.
What this protects against: reading the key out of localStorage in DevTools, out of a copied browser profile, or out of a backup, and any tool that scrapes local storage. What it does not protect against: a script running on the SAGE3 origin in that browser while the key is stored, which can decrypt it exactly as SAGE3 does. That is the nature of any credential a browser holds; the mitigations are the content-security policy the server already sends and the removal on logout. Nothing is asked of the user: no passphrase, no prompt, no permission dialog.
To confirm on a running server: save a key, then in the browser's developer tools look at Application > Local Storage for the server's origin. The s3_user_llm entry should show an enc value and no recognisable key, and Application > IndexedDB should list s3_user_llm_keys.
Two consequences worth stating plainly to users: requests made this way are billed to their own account, and while the key is stored it can be used by anything running SAGE3 in that browser profile, which is why it is removed on logout.
Who may use it. Registered users and admins only. Guests and spectators are refused: they are transient, unverified accounts, and a key pasted into a shared guest session would outlive whoever pasted it. Opening Settings as a guest also clears any key a previous account left behind in that browser.
Which endpoints work. A key with no base URL is spoken to as OpenAI; a base URL is treated as a generic OpenAI-compatible endpoint. Azure OpenAI works through its OpenAI-compatible /openai/v1 surface: enter the resource address and the form completes the path; the model field takes the deployment name. The classic Azure API with api-version is not used here. If the model lookup fails, the form says why (key rejected, wrong address, endpoint unreachable or not allowing browser requests) and the model can still be typed by hand.
Turning it off. There is no server switch for this today. Leaving models.providers empty disables AI entirely, including user-supplied keys.
To disable AI, leave models.providers empty (or remove the models block).
See the models block in the configuration listing above for a complete example.
Status and problem solving
To check if the state of the system, you can use docker commands:
- List the docker images present on the system:
> docker images
REPOSITORY TAG IMAGE ID CREATED SIZE
REPOSITORY TAG IMAGE ID CREATED SIZE
ghcr.io/sage-3/agents dev_arm64 ffaf2a339c7b 22 hours ago 3.73GB
ghcr.io/sage-3/next dev_arm64 1305e9592af5 22 hours ago 2.14GB
fluent/fluentd edge-debian 899f6c4f419f 5 weeks ago 235MB
chromadb/chroma 0.5.16 ec7fe55aac18 2 months ago 479MB
redis/redis-stack-server latest a5ac850ed6cb 3 months ago 403MB
ghcr.io/sage-3/sagekernelserver arm64 324f16bba2e9 6 months ago 1.07GB
quay.io/jupyter/datascience-notebook 2024-05-27 0752ac24b52d 7 months ago 5.53GB
- Check system status
> docker ps
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
f1a2b3c4d5e6 traefik:v2 "/entrypoint.sh trae…" 22 hours ago Up 22 hours 0.0.0.0:443->443/tcp traefik
20a136469e25 ghcr.io/sage-3/sagekernelserver:arm64 "python src/main.py …" 22 hours ago Up 22 hours (healthy) 8000/tcp sage3-10-kernelserver-1
b93c18e46325 ghcr.io/sage-3/next:arm64 "docker-entrypoint.s…" 22 hours ago Up 22 hours (healthy) 3000/tcp sage3-10-node-server-1
e3a6448d6df2 ghcr.io/sage-3/agents:arm64 "fastapi run main.py…" 22 hours ago Up 22 hours (healthy) 9999/tcp sage3-10-seer-1
5bc7b93c6bf5 quay.io/jupyter/datascience-notebook:2024-05-27 "tini -g -- start.sh…" 22 hours ago Up 22 hours (healthy) 8888/tcp sage3-10-jupyter-1
b6a3ae3c7244 chromadb/chroma:0.5.16 "/docker_entrypoint.…" 22 hours ago Up 22 hours (healthy) 8000/tcp sage3-10-chromadb-1
4776cdcfedf9 redis/redis-stack-server:latest "redis-server /conf/…" 22 hours ago Up 22 hours 6379/tcp sage3-10-redis-server-1
b2d60836dee3 fluent/fluentd:edge-debian "tini -- /bin/entryp…" 22 hours ago Up 22 hours 5140/tcp, 24224/tcp sage3-10-fluentd-server-1
Note: only Traefik publishes a host port (443), plus livekit-server (7881/tcp and 7882/udp for WebRTC media) when screen sharing is enabled. All the other services communicate over the internal Docker network using service names, so their ports are not reachable from the host. To poke at an internal service, go through its container, e.g. docker compose exec seer curl localhost:9999/status or docker compose exec redis-server redis-cli.
- See logs of a container
> docker logs sage3-10-node-server-1
Mode> production
HTTPS> listening on port 443
Google Login> Setup done
Apple Login> Setup done
JWT> Login setup done
Guest Login> Setup done
CILogon Login> Setup done
...
Services
Google Login
To enable Google Login for users from the Login page you must setup a Google Cloud account. Google OAuth is a free service that allows users to sign into SAGE3 with their Google Accounts.
-
Login to your Google account from the Google Cloud Platform website.
-
Click
Consolein the upper right corner.
- Create a
New Projectfrom theManage Resourcespage. Can be found using the search box at the top of the page.
- Click
CREATE PROJECT.
- Enter the information and click
Create. (The information here is just organization/hierarchy information.) It might take a few minutes for it to be created.
-
Go back to the homepage by clicking the Google Cloud icon in the upper left corner.
-
From the drop down menu at the top of the page select your newly created project.
- Open the
Credentialspage from the main dropdown menu.
- Click
Create Credentialsand selectOAuth client ID
-
If it requests to
Configure Consent Screenclick the button. If not continue to step 15. -
OAuth Consent Screen. Select External and click create. Enter the information below. All the other fields can be left blank.
- App name: The Name of the SAGE3 Server.
- User support email: The email of the person managing your SAGE3 server.
- Authorized Domain: The
domainof your SAGE3 Server. (Ex. Forhttps://sage3.manoa.hawaii.eduit ishawaii.edu) - Developer contact information: The email of the person managing your SAGE3 server.
- Scopes. Click
ADD OR REMOVE SCOPESand select../auth/userinfo.emailand../auth/userinfo.profilethen clickUPDATE. Then clickSAVE AND CONTINUE
-
Test Users. Click
SAVE AND CONTINUE -
Summary. Click
BACK TO DASHBOARD -
Create OAuth client ID.
- Application Type:
Web application. - Name: The name of your OAuth 2.0 client. This name is only used to identify the client in the console and will not be shown to end users.
- Authorized JavaScript origin: Click
ADD URIand enter you server's URL. (Ex.https://sage3.manoa.hawaii.edu) - Authorized Redirect URIs: Click
ADD URIand enter you server's URL with the route/auth/google/redirectattached. (Ex.https://sage3.manoa.hawaii.edu/auth/google/redirect)
- Click
CREATEand you should be shown the following screen with yourCLIENT_IDandCLIENT_SECRET.
-
Copy the
CLIENT_IDandCLIENT_SECRETinto the SAGE3 Server Configuration file located here:/configurations/node/sage3-prod.hjson. They should be copied in theauth.googleConfigfields underclientIDandclientSecret. -
Ensure within the SAGE3 Server Configuration you have
googlelisted in theauth.strategiesarray.
Test logging into your SAGE3 server using the Login with Google button on the homepage.
Apple Login
- Need an Apple Developer Account: https://developer.apple.com/account
- Documentation:
- Official documentation: "Sign in with Apple JS" https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_js
- Module documentation: https://github.com/ananay/apple-auth/blob/master/SETUP.md
- You will need several items:
- Create a new App ID:
- Navigate down to "Capabilities", and select "Sign in with Apple".


- Create a service ID
- Fill out the details, and click configure on "Sign in with Apple".
- "Domains and Subdomains": the hostname of your server (e.g.
sage3.hawaii.edu) - "Return URLs": the URL called back by Apple after login (e.g. https://sage3.hawaii.edu/auth/apple/redirect)

- "Domains and Subdomains": the hostname of your server (e.g.
- Fill out the details, and click configure on "Sign in with Apple".
- Create a key:
- Go to the "Keys" section in your Developer account and create a key and configure on the "Sign in with Apple" option. Click continue and register. Click on
Download(your only chance) and rename itapple-key.p8. 
- Go to the "Keys" section in your Developer account and create a key and configure on the "Sign in with Apple" option. Click continue and register. Click on
- Create a new App ID:
- Configuring SAGE3:
// Apple configuration
"appleConfig": {
// This is actually called the "Service ID" that you created in the 'Identifiers' section
"clientID": "something com.sage3.blabla",
// Your Apple developer team ID: 10-character string, upper-case letters and numbers
"teamID": "XXXXXXXXXX",
// keyID is the identifier for the private key you generated: 10-character string, upper-case letters and numbers
"keyID": "XXXXXXXXXX",
// Private key file location that you downloaded
"privateKeyLocation": "./keys/apple-key.p8",
// The URL that Apple will call back after login, no need to change
"callbackURL": "/auth/apple/redirect",
"routeEndpoint": "/auth/apple"
},
CILogon
To enable CILogon Login for users from the Login page you must request a CILogon. CILogon provides a standards-compliant OpenID Connect (OAuth 2.0) interface to federated authentication for cyberinfrastructure.
Instructions to do so are located here:
CILogon OpenID Connect (OAuth 2.0)
To register, use this link: CILogon Client Registration
- Client Name: The Client Name is displayed to end-users on the Identity Provider selection page.
- Contact Email: This email address is used for operational notices regarding your client and for validating your affiliation. A mailing list address for your operations team is recommended.
- Home URL: URL of the Server (Ex. https://sage3.manoa.hawaii.edu)
- Callback URLs: To ensure CILogon redirects back to the SAGE3 server after the user logins, postfix your server URL with:
/auth/cilogon/redirect. (Ex. https://sage3.manoa.hawaii.edu/auth/cilogon/redirect) - Client Type: Confidential
- Scopes: Ensure
openidandemailare selected. - Refresh Tokens: No
After Registering the Client you should be shown a Client Identifier and Client Secret.
Copy this down somewhere safe. OpenID OIDC should email you at the contact email from above within a day or two to confirm your request has been approved.
With in the Server Configuration file configurations/node/sage3-prod.hjson under the auth.cilogonConfig paste the Client Identifier and the Client Secret into their respective fields. Also ensure the array auth.strategies contains cilogon to enable the feature.
Test logging into your SAGE3 server using the Login with CILogon button on the homepage.
Which should redirect to a page that looks like:
Screen sharing
Screen sharing runs on a self-hosted LiveKit server (an SFU: users send their screen once, the server relays it to everyone on the board). It is part of the standard deployment, and there is nothing to configure in sage3-prod.hjson: no URL, no key. Clients always reach the video server at /sfu on the SAGE3 server they loaded the page from, so a SAGE3 server can only ever use its own.
To enable it, set one value in .env:
# Any value of 32 characters or more; a UUID is 36
LIVEKIT_API_SECRET=$(uuidgen)
That is the whole configuration. The same secret is handed to both the livekit-server container and the SAGE3 server by the compose file. Keep it out of version control and backups you share.
Leave it empty and there is no screen sharing: the server mounts no screen-sharing routes and the Screenshare panel tells users it is not enabled on this server. The livekit-server container refuses to start without a secret, so if you run without screen sharing, also comment out the livekit-server service in docker-compose.yml, otherwise it will restart in a loop.
Open these ports on the host firewall, forwarded to the machine if it is behind NAT. Signaling needs no new port: it rides the existing HTTPS port through Traefik.
| Port | Purpose |
|---|---|
7882/udp | All WebRTC media, multiplexed on one port. Screenshares connect but show no video without it. |
7881/tcp | Media fallback for clients on networks that block UDP. |
Verifying. After ./GO, the node-server log reports which screen-sharing backend is active:
Configuration> screenshare backend: livekit
twilio means the secret did not reach the container; none means neither backend is configured. Then share a screen from a client on a different network than the server: joining proves signaling works, but only video actually flowing proves the media ports are open. Stopping a share should remove its window within a second or two; if it lingers, the video server cannot reach node-server for its webhooks.
If video never appears (the window opens but stays black), the media path is the problem. Confirm 7882/udp is open and forwarded. If the host has no outbound STUN access, or STUN reports the wrong address, edit configurations/livekit/livekit.yaml and set both use_external_ip: false and node_ip: <the address clients actually reach>; node_ip is ignored while use_external_ip is true.
Existing servers upgrading from a Twilio-only version: the step-by-step is in configurations/livekit/ADDING-LIVEKIT.md, included in the package. Nothing is needed in features.apps: screen sharing is started from the Screenshare panel, not the Applications panel.
Twilio (legacy screen sharing)
Servers that have not moved to the self-hosted video server above may keep using Twilio by filling in the services.twilio block. When both are configured, LiveKit is used; existing Twilio screenshare windows on boards keep working either way. Twilio support will be removed in a future release.
Twilio provides programmable communication tools for handling the Screenshare portion of SAGE3. It's an affordable option and allows multiple screenshares within board. SAGE3 uses Twilio's Video Groups and more information about it can be found here.
To enable screen sharing on your SAGE3 server:
-
Signup for a Twilio Account. Twilio Registration
-
Verify your account.
-
After creating you should be shown the page below. Select:
VideoOtherWith codeJavaScriptNo, I want to use my own hosting service
Then click Get Started with Twilio.
- Navigate to the
Auth Token & API Keys
-
Click
Create API key -
Fill in the form.
- Friendly name: A friendly name for this
API Keythat shows in the Twilio console. - Region: Select the region that is closest to the majority of your SAGE3 users.
- Key type: Standard
-
You will then be shown your
SIDandSecret. Copy these down somewhere safe. ClickDone. -
Navigate to the
Auth Token & API Keys -
Under
Live credentialscopy down theAccount SID. -
You will now have three keys/tokens.
Account SID,SID, andSecret. -
Copy these keys/tokens to the SAGE3 Server Configuration file located
/configurations/node/sage3-prod.hjson. Under theservices.twilioenter the three keys/tokens into the following fields:
- accountSid:
Account SID - apiKey:
SID - apiSecret:
Secret
- Nothing is needed in
features.apps: screen sharing is started from the Screenshare panel, not the Applications panel.
CoBrowser
CoBrowser is a shared web browser app that streams a live Firefox session to all users on the board. It requires a separate VEO server — a container orchestration service that manages the Firefox VNC instances.
To enable CoBrowser on your SAGE3 server:
-
Obtain access to or deploy a VEO server. Contact the SAGE3 team if you need access to a shared VEO instance.
-
Add the VEO server URL to your
sage3-prod.hjsonconfiguration file:
// VEO VNC container orchestration server
"veoServer": {
"url": "https://your-veo-server-url"
}
- Add
"CoBrowser"to thefeatures.appsarray in the same configuration file:
"features": {
"apps": ["CoBrowser", "Chat", ...]
}
- Restart the server (
./STOPthen./GO) for changes to take effect.
Without the veoServer URL configured, the CoBrowser app will appear in the Applications panel but will not function.