Configuration
The assistant's module option, its environment variables, agent providers and remote access.
Module option
| Key | Type | Default | Description |
|---|---|---|---|
backendUrl | string | http://localhost:5010 | Origin the sidecar calls the DMS backend on, for its pages registry and logs. Set it to ${@api.API_LOCAL_BASE_URL}. |
The module ignores an empty or non-string backendUrl, and the sidecar then uses the default. Everything else is set on the Settings page and saved as you change it: the agent, thinking, approvals, local skills, Safe mode and history. The default approval mode is stored for each agent: Claude Code starts new chats on Auto review and Codex on Ask first.
Environment variables
| Variable | Read by | Effect |
|---|---|---|
DMS_ASSISTANT=0 | Backend | The backend starts without the sidecar. |
NODE_ENV=production | Backend and sidecar | The backend starts no sidecar, and a sidecar started by hand exits. |
ANTHROPIC_API_KEY | Claude Code | Credentials for Claude Code when it is not logged in. The sidecar passes the backend's environment to Claude Code. |
OPENAI_API_KEY | Sidecar | Ignored. Codex runs on a ChatGPT sign-in, and the sidecar logs a warning once per start when the variable is set. |
DMS_ASSISTANT_CODEX_ALLOW_VERSION_MISMATCH=1 | Sidecar | Runs a codex binary at a version other than the pinned one, and logs the mismatch. |
XDG_CONFIG_HOME, APPDATA | Sidecar | Base folder of the ChatGPT sign-in file. See Sign in with your plan. |
Agent providers
The assistant runs on Claude Code, the default, or on Codex. The Coding agent setting on the Settings page picks the provider. Both providers behave the same in the chat, with tool calls, permission prompts and file-change animations.
A provider that cannot run, because its package is missing or its sign-in is gone, fails the turn and shows the reason in the chat. The assistant never hands the conversation to the other provider, because a person who picked one provider may have picked it so their code does not reach the other.
A provider switch ends the live sessions of the previous provider. An open conversation loses the agent's memory, and its transcript stays.
Enable codex
Codex needs two things, the codex CLI at the pinned version and a ChatGPT sign-in.
The codex CLI is an optional peer dependency, and installing the module never installs it. Its platform binary takes several hundred megabytes. The sidecar runs only the exact version that peerDependencies["@openai/codex"] in the module's package.json pins:
pnpm add @openai/codex@<pinned version>
The sidecar reads codex --version and refuses a mismatch. The reason in the chat names both versions and the version to install. The sidecar checks the installation once per start, so restart the backend after you install the CLI. Then pick Codex under Coding agent on the Settings page.
Sign in with your plan
Codex runs on your ChatGPT plan through Sign in with ChatGPT, and uses no OpenAI API key. Sign in with ChatGPT on the Settings page opens OpenAI's consent page. After you allow access, OpenAI sends the browser back to http://127.0.0.1:<sidecar port>/auth/chatgpt/callback.
- On the machine that runs the DMS, that address is the sidecar, and the sign-in completes in that tab.
- On a DMS that runs elsewhere, such as a cloud development server, the address points at your own computer and the page does not load. Copy the whole address from the address bar, press Paste the return address on the Settings page, and paste it. The code in the address works once, within 10 minutes, and only with the secret that the sidecar kept for this attempt.
The sign-in belongs to the user and the machine, and every DMS project on that machine shares it. The sidecar stores it in chatgpt-auth.json, with file mode 0600, never in the project:
| Platform | Folder |
|---|---|
| Windows | %APPDATA%\dms-assistant |
Other, with XDG_CONFIG_HOME set | $XDG_CONFIG_HOME/dms-assistant |
| Other | ~/.config/dms-assistant |
An access token lasts an hour. The sidecar refreshes it before it expires and hands it to Codex. The refresh token lasts 30 days and rotates on each refresh. Codex usage counts toward your plan's limits, which you can cap per app in ChatGPT's settings. When a limit is reached, turns fail with OpenAI's message, and nothing switches to paid API usage.
Sign out on the Settings page revokes the session. Codex then stops working in every DMS project on the machine until you sign in again. To remove the dms-assistant app from your ChatGPT account entirely, disconnect it in ChatGPT's settings.
Safe mode, under the hood
In Safe mode, the agent changes the project only through the builder tools of the dms MCP server, whatever the approval mode.
- On Claude Code, a
PreToolUsehook lets through only reads, web access, sub-agents, the MCP tools the chat runs without a prompt, and tools that change nothing outside the chat.Read,GlobandGreprun without a prompt inside the workspace and ask outside it. The hook refuses every other tool: file edits, shell commands, scheduled tasks, tools that act outside the chat, and any tool it does not know, such as one a Claude Code update adds. - On Codex, the sandbox stays read-only, without network, and the sidecar declines every escalation.
- In Auto review, Safe mode still blocks raw edits and shell commands, and web access still asks. In Code mode the safety check handles only reads inside the workspace, ordinary edits, web access and sub-agents. Every other tool asks, and so does every edit of
package.json, a lockfile,pnpm-workspace.yaml,.npmrc,.pnpmfile.cjs,.yarnrc,.yarnrc.ymlorbunfig.tomlwhile Always ask for covers dependencies. Every edit ofantelope.config.ts, anantelope.*.jsonfile or a file under.antelope/asks too, in every mode and with no rule to keep, since AntelopeJS core reads each module's configuration, the URL of each database included, from them.
A switch between Safe mode and Code mode applies from the next tool call on Claude Code and from the next turn on Codex. The conversation stays.
Where the chat's tools come from
Every chat session, on Claude Code and on Codex, gets two MCP servers:
| Server | Tools | How the session reaches it |
|---|---|---|
dms | The builder, database, mockup, typecheck, query_logs, list_pages and page_verify tools of @antelopejs/dms | node <project root>/node_modules/.cache/dms/mcp-bridge.cjs, the launcher the DMS writes in development |
dms-assistant | ask_user, get_current_page, find_pages_using, navigate_to_page and preview_blocks, which drive the dashboard tab or the chat | The sidecar |
The agent sees the tools as mcp__dms__builder_add_block, mcp__dms-assistant__ask_user and the like. The dms server also serves a navigate_to_page and a preview_blocks. The chat hides those two, so the agent sees one tool of each name.
The DMS writes the launcher only when its MCP server is on, which by default means in development. Set mcp.backendUrl in the dms module's config to ${@api.API_LOCAL_BASE_URL}, as MCP server in the DMS docs shows. Without the launcher, the chat has no builder tools, and Safe mode can change nothing.
The chat runs the tools of both servers without a prompt, in every approval mode. Two cases still involve you:
- The
dmsserver holds a deletion, a project configuration change, a mapping that would remove pages,builder_remove_queryandbuilder_remove_field. It refuses the first call and says what the call would do. The agent then asks you withask_user, and only the same call repeated within 10 minutes runs. - While Always ask for covers block removals,
builder_remove_blockandbuilder_move_blockask on a card first.
Any other MCP tool asks on Claude Code. Codex refuses it.
A Claude Code or Codex session you start yourself in the project gets the same dms server from the project's .mcp.json, with no assistant installed. MCP server in the DMS docs covers it. Outside the chat, the approval modes, Safe mode, Activity and Changes do not apply.
Secret files
The project's database URLs and other credentials live in .env. With Codex, the sandbox refuses to read .env and .env.* files anywhere in the project and its local modules, in every approval mode, in Safe and Code mode alike. .env.example, .env.sample and .env.template stay readable. Codex checks again before each command, so a secret file created during the chat is covered too, and a command you approve to run outside the sandbox still cannot read them. The sidecar also declines, without asking, a Codex patch that writes one of these files or renames a file onto one, through a symbolic link too, whatever rule you kept. Claude Code's hook refuses a read or an edit that names one of these files, or a symbolic link to one, even before the file exists.
Remote access
The sidecar listens only on 127.0.0.1. The browser reaches it through the DMS frontend server, so the assistant works wherever the dashboard does, and the sidecar's port and credential stay on the server.
| Route | Use |
|---|---|
GET /ai/channel/events | Event stream from the sidecar |
POST /ai/channel/:connectionId/messages | Messages from the browser |
The module declares /ai/** as a backend proxy of the frontend server (backendProxies), with the session of the signed-in member. The views, the blocks and the chat call the module's routes on the dashboard's own origin, and the frontend server forwards them to the backend. The DMS frontend has to support backendProxies.
Browsers keep at most six HTTP/1.1 connections per origin, and each dashboard tab already holds two. The assistant adds one in a visible tab while its panel is open, while a chat in it works or waits for you, or while the command palette streams an answer. Over HTTPS with HTTP/2, the limit does not apply.