Configuration
Module option
| Key | Type | Default | Description |
|---|---|---|---|
backendUrl | string | http://localhost:5010 | Origin the sidecar calls the DMS backend on (its pages registry, logs and Builder client). Set it to ${@api.API_LOCAL_BASE_URL}. |
Everything else (agent, thinking, approvals, scope, skills, history) is set on the Settings page and saved as you change it.
Environment variables
| Variable | Effect |
|---|---|
DMS_AI=0 | Start the backend without the sidecar. |
NODE_ENV=production | The backend and the sidecar refuse to run. |
ANTHROPIC_API_KEY | Credentials for Claude Code, when it is not logged in. |
OPENAI_API_KEY | Credentials for Codex. |
DMS_AI_CODEX_ALLOW_VERSION_MISMATCH=1 | Run a Codex binary other than the pinned version (logged once). |
DMS_COOKIE_SECURE=false | On the frontend server, when the dashboard is reached over plain HTTP on an address other than localhost. |
Agent providers
The assistant runs on Claude Code (the default) or Codex, picked on the Settings page. Both behave the same in the chat: tool calls, permission prompts and file-change animations.
A provider that cannot run (its package missing, its key gone) fails the turn with the reason in the chat. The conversation is never handed to the other provider: someone who picked one provider may have picked it precisely so their code does not reach the other. Switching provider ends the live sessions of the previous one: an open conversation loses the agent's memory, its transcript stays.
Enable Codex
Install the CLI at the pinned version
The codex CLI is an optional peer dependency (about 324 MB), never installed for you. Use the exact version peerDependencies["@openai/codex"] pins:
pnpm add @openai/[email protected]
The sidecar checks codex --version at spawn and refuses a mismatch, naming both versions.
Provide an API key
Export OPENAI_API_KEY in the backend's environment. The sidecar writes it into an auth.json (mode 0600) in a CODEX_HOME dedicated to the conversation. ChatGPT login is not supported.
Restart the sidecar and pick Codex
Restart from the Overview, then pick Codex on the Settings page.
Safe mode, under the hood
Safe mode lets the agent change the project only through the Builder tools, whatever the approval mode:
- On Claude, a
PreToolUsehook refusesWrite,Edit,MultiEdit,NotebookEditandBash. Reading, listing and searching stay available throughRead,GlobandGrep, allowed inside the workspace and asked outside it. - On Codex, the sandbox stays read-only, without network, and every escalation is declined.
- Safe mode caps Full auto at Accept edits, so the prompts that remain (reads outside the workspace, web access) still reach you.
Switching between Safe and Code mode applies from the next tool call on Claude and from the next turn on Codex, without discarding the conversation.
Remote access
The sidecar only listens on 127.0.0.1. The browser reaches it through the DMS frontend server (GET /ai/channel/events for the event stream, POST /ai/channel/:connectionId/messages for client messages), so the assistant works wherever the dashboard does, and the sidecar's port and credential stay on the server.
The module declares /ai/** as a backend prefix of the frontend server (backendProxies, with the signed-in member's session): the views, the blocks and the chat call its routes on the dashboard's own origin, and the frontend server forwards them to the backend. This needs @antelopejs/dms-frontend 0.6.