Configuration

Studium needs no configuration to start: the MCP server keeps lessons and progress under ~/.studium and works without any model. This page lists every environment variable the servers and services read, with its default, and the VS Code extension's settings. A commented template of all of them is in .env.example; nothing loads that file automatically, so copy the lines you need into your shell, your harness configuration or your service manager.

An empty value (VAR=) counts as unset for the variables of the MCP server.

Where lessons and progress live

Variable Default Read by Purpose
STUDIUM_HOME ~/.studium lesson-mcp, VS Code extension, teacher dashboard Root of the learner's library (<STUDIUM_HOME>/library) and data (<STUDIUM_HOME>/data).
BUNDLES_ROOT lesson-mcp: <STUDIUM_HOME>/library; see the other components below lesson-mcp and every server Folder a bundle_ref is looked up in first. lesson-mcp also searches the library. prepare_sources and create_lesson never write here: they always write to <STUDIUM_HOME>/library.
STUDIUM_DATA_DIR <STUDIUM_HOME>/data lesson-mcp, lesson-server, HTTP API Durable learner state. Set it to choose another folder; it is kept even with STUDIUM_EPHEMERAL=1. lesson-server and the HTTP API keep state in memory unless it is set.
STUDIUM_EPHEMERAL unset lesson-mcp 1 (or true, yes, on) keeps learner state in memory, lost at restart. Use it for tests, demos and CI.
STUDIUM_LEARNER_ID anonymous lesson-mcp Learner id used when a call names none.

Dates in tool results and in the text shown to the learner are calendar days in the time zone of the process, reported as get_server_info.time_zone. There is no Studium variable for it; Node.js follows the system setting, or TZ when it is set.

Privacy and pseudonyms

Variable Default Read by Purpose
STUDIUM_PSEUDO_SECRET per-install file <data dir>/.studium-secret (mode 0600) lesson-mcp, lesson-server, HTTP API HMAC secret behind the pseudonyms that name learner folders on disk. A fresh data folder gets its own random secret; an older folder that already holds learners keeps the legacy secret so nobody loses progress. In-memory servers use dev-secret.
NODE_ENV, STUDIUM_ENV unset lesson-mcp, lesson-server, HTTP API production refuses to start a session without a real pseudonym secret (as does a configured model).
STUDIUM_TELEMETRY_CONSENT unset (off) lesson-mcp, lesson-server, HTTP API 1, true, granted or yes writes pseudonymised class telemetry (telemetry.jsonl, no free text) next to the learner's state. Needs a durable data folder. The VS Code extension sets it from its setting only.
STUDIUM_PER_LEARNER_SHUFFLE unset lesson-mcp, lesson-server, HTTP API Any value gives each learner their own, reproducible order of quiz choices. By default every learner sees the same order.
STUDIUM_MASTERY_DIR unset lesson-mcp, lesson-server, HTTP API In memory-only mode, a folder to write mastery claims to. A durable data folder overrides it.

Keep a copy of .studium-secret with the data folder: without it, existing learner folders cannot be matched to their learners again.

Judge model (optional)

Without a model, open answers get the reference to compare with and self-rating schedules reviews; nothing claims a coverage no judge measured. A model is reached through an OpenAI-compatible endpoint such as a LiteLLM proxy.

Variable Default Read by Purpose
LITELLM_BASE_URL empty (no model) lesson-mcp, lesson-server, planner Model endpoint. Non-empty turns on the judge, the Socratic tutor and the audit judge. The planner defaults to http://localhost:4000 but only calls it with STUDIUM_LLM_MODE=litellm.
LITELLM_API_KEY unset lesson-mcp, lesson-server, planner Bearer key for the endpoint.
LITELLM_MODEL studium/audit-judge lesson-mcp, lesson-server Model name of the audit judge. The scorer and tutor use the alias studium/runtime-tutor.
STUDIUM_LLM_TIMEOUT_MS 20000 lesson-mcp, lesson-server Timeout of a scoring or tutoring call, in milliseconds.

The MCP server uses the endpoint when LITELLM_BASE_URL is not empty; the HTTP API also requires STUDIUM_API_LIVE=1. Keep keys in your local secret store and check the fallback flags of a live run: an HTTP 200 does not prove that a model answered. A proxy must route the model aliases Studium calls: studium/planner, studium/critic, studium/graph-builder, studium/scene-synth, studium/teacher-review and studium/runtime-tutor.

HTTP API of lesson-mcp

See HTTP API. Started with pnpm --filter @studium/lesson-mcp api.

Variable Default Read by Purpose
STUDIUM_API_TOKEN none (required) HTTP API and its client Bearer token, at least 32 characters.
STUDIUM_API_PORT 8130 HTTP API Port, on 127.0.0.1 only.
STUDIUM_API_LIVE unset HTTP API 1 enables the model of LITELLM_BASE_URL; otherwise the API never calls a model.
STUDIUM_API_URL http://127.0.0.1:8130 api:call client Loopback origin of the API.
BUNDLES_ROOT ../../fixtures (from apps/lesson-mcp) HTTP API Lessons served.

lesson-server

The REST server of the teacher dashboard's peer rooms and course pages (pnpm --filter @studium/lesson-server start).

Variable Default Read by Purpose
BUNDLES_ROOT the current directory lesson-server Lessons served.
PORT 8010 lesson-server Port, on 127.0.0.1.
LITELLM_BASE_URL empty lesson-server As above.

Teacher dashboard and analytics

Variable Default Read by Purpose
BUNDLES_ROOT <STUDIUM_HOME>/library teacher dashboard Lessons shown in the library and review pages.
ANALYTICS_BASE_URL http://localhost:8003 teacher dashboard analytics-collector service.
SCENE_SYNTH_BASE_URL http://localhost:8002 teacher dashboard scene-synth service (learner contributions).
STUDIUM_REVIEW_TOKEN none (decisions disabled) teacher dashboard (server only) Teacher review token sent to scene-synth on a decision; at least 32 characters, same value as on scene-synth. Never sent to a browser.
LESSON_SERVER_BASE_URL http://localhost:8010 teacher dashboard lesson-server (peer rooms, courses).
OBSERVATORY_BASE_URL http://localhost:8004 teacher dashboard Observatory, linked from a lesson when it answers.
ANALYTICS_DATA_DIR data (relative to the working directory) analytics-collector Where collected telemetry is stored.
ANALYTICS_MIN_LEARNERS 5 analytics-collector Smallest cohort a class figure is computed over. Server-side only, never a query parameter.

The dashboard's end-to-end tests also read DASHBOARD_PORT (default 3001), DASHBOARD_PORT_EXTERNAL, PLAYWRIGHT_CHANNEL and CI. The Observatory has its own variables (STUDIUM_OBS_*), described in services/observatory/observatory_config.py.

scene-synth

Variable Default Read by Purpose
BUNDLES_ROOT the repository's fixtures/ scene-synth One folder per course, each with its lesson.json.
COMMUNITY_BUNDLES_ROOT BUNDLES_ROOT scene-synth Where approved learner contributions are written (<root>/<course>/community/).
LEARNER_DATA_ROOT /tmp/studium-learner-items scene-synth Store of submitted learner items.
LEARNER_PSEUDONYM_SECRET dev-insecure-secret scene-synth HMAC secret of author pseudonyms. Set it in any real deployment.
STUDIUM_REVIEW_TOKEN none (decisions refused) scene-synth Bearer token required on POST /learner-items/{id}/decide, at least 32 characters, distinct from any course id. Unset or shorter, every decision gets 503.
BUNDLE_DIR the demo's default folder demo_fresh.py Where the demo bundle is staged.

Planner

The planner answers 503 until a model is configured.

Variable Default Read by Purpose
STUDIUM_LLM_MODE unset planner litellm calls the model; mock uses the deterministic mock (tests and demos only).
STUDIUM_LWG_BUILD unset planner on builds the learning workflow graph of each plan.
STUDIUM_LWG_OUT_DIR .lwg planner, Observatory Output folder of those graphs.
STUDIUM_EVIDENCE_ENRICH unset planner on enriches plans with literature evidence.
STUDIUM_PERSPICACITE_ENABLED unset planner on enables the Perspicacité literature client.
STUDIUM_PERSPICACITE_MODE unset planner mock uses a mock client.
PERSPICACITE_MCP_URL http://localhost:8000/mcp planner Perspicacité MCP endpoint.
PERSPICACITE_DOMAIN_KB empty planner Default knowledge base.
STUDIUM_PERSPICACITE_CACHE on planner off disables the on-disk search cache.
STUDIUM_PERSPICACITE_CACHE_DIR .cache/perspicacite planner Cache folder.

Build identity

Variable Default Read by Purpose
STUDIUM_BUILD_INFO unset lesson-mcp run from sources JSON {origin, built_at, git_sha} that get_server_info reports instead of asking git. A bundled server reports its compiled identity and ignores it.

VS Code extension settings

Set in VS Code's settings (studium.*). The extension starts its own MCP server with BUNDLES_ROOT from studium.bundlesRoot, STUDIUM_DATA_DIR set to its VS Code storage folder, and STUDIUM_TELEMETRY_CONSENT from studium.telemetryConsent; the rest of its environment is inherited.

Setting Default Purpose
studium.repoRoot the folder two levels above the extension A Studium checkout; when found, the server runs from its sources. Otherwise the embedded dist/lesson-mcp.cjs runs.
studium.bundlesRoot empty: the checkout's fixtures/, else <STUDIUM_HOME>/library Lessons folder.
studium.bundleRef atomistique-l1/lesson.json Lesson opened by default.
studium.communityBundlesRoot empty: studium.bundlesRoot Root of approved learner contributions.
studium.assets vendor vendor (offline viewers) or cdn.
studium.learnerId vscode-learner Learner id.
studium.telemetryConsent false Consented, pseudonymised class telemetry.
studium.showGraph true Companion learning workflow graph panel.
studium.graphView student student (around the current concept) or teacher (whole graph).
studium.showMastery false Live mastery bar; a teacher signal that can leak answers during a quiz.
studium.modalityPreference balanced visual, textual or balanced ordering of a scene's supports.

Progress made in the VS Code pane is kept in the extension's storage, separate from <STUDIUM_HOME>/data used by a terminal assistant. "Studium: Forget my data" erases only the extension's own data.

View the source of this page on GitHub