Set up

Configuration

Most settings are on the dashboard's Settings and Agents pages. They're saved in one small JSON file that you can also edit by hand, and a few environment variables cover the rest.

config.json

Settings live in ~/.dotpals/config.json and are shared by the pal, the notch, the dashboard and the bridge. Changes made on the dashboard (or the tray) apply at once. If you edit the file by hand, restart dotpals to pick them up.

{
  "character": "custom",
  "sounds": true,
  "notifications": true,
  "history": true,
  "historyDays": 14,
  "approvals": true,
  "approvalWait": 30,
  "agents": { "cursor": false },
  "custom": { "name": "Pip", "shape": "bean", "eyes": "googly", "top": "crown", "color": "#16c6ae", "fur": true }
}

Only the keys below are kept, and only with valid values. Anything else is ignored, and dropped the next time dotpals saves the file. A key you leave out uses its default.

Keys

The bridge sends the full settings to every open view (GET /api/config returns them too), with agents filled in for every id. The one exception is the API key: it's never sent back. Instead, checker says keySet, keyLast4 (its last 4 characters) and keyFrom ("settings" or "env"). It also carries laya, the status of the Laya dotpals set up: { installed, running, phase, message, line, error, port, log }, where phase is idle, python, venv, install, starting, ready or error.

Laya's folder

Set up Laya keeps everything in ~/.dotpals/laya (or <DOTPALS_HOME>/laya): .venv (a Python environment with Laya and PyTorch), hf (its model), server.log (what it prints, cut back past 5 MB) and server.pid. Remove Laya or dotpals laya --remove deletes the folder. dotpals runs it with LAYA_HOST=127.0.0.1, LAYA_PORT from localUrl and LAYA_MODELS=english, and ignores any other LAYA_* variables you have set.

The TypeSafe API key

Enter it in Settings → Double-check unclear test results → Cloud (Jev): paste it into the TypeSafe API key field and click Save. The page then shows “Saved ••••1234”. Saving with the field empty keeps the saved key; Remove key deletes it. You can also set TYPESAFE_API_KEY in the environment the bridge runs in; a key saved on the Settings page wins over it.

The key is stored in config.json, which dotpals writes readable by you only (mode 600) on macOS and Linux. On Windows the file keeps your user folder's permissions. The key is only ever sent to TypeSafe, by its official SDK (@typesafe-ai/sdk, installed by dotpals setup as an optional package); it isn't logged, shown, or stored with your activity.

Environment variables

Environment variables win over config.json. Set them where the process that reads them runs: bridge variables for the desktop app (or dotpals bridge), and hook variables in your agent's environment, since that's where the hook command runs.

For the bridge and the app

For the hooks

Changing the port

dotpals uses port 5175 everywhere by default. To use another one, every part has to agree:

1. Set DOTPALS_PORT for the desktop app and the dotpals command, or PORT for a bridge you run on its own.
2. Set DOTPALS_URL=http://127.0.0.1:<port>/hook in the environment of Claude Code, and of any agent you've connected (for OpenCode, the environment OpenCode runs in). This also turns off auto-start. If you use Share with your agents, also set DOTPALS_BRIDGE=http://127.0.0.1:<port> for Claude Code.
3. Point your own agents' POST /event at the new port. The dashboard's Any agent card shows the right address.

If something else is using 5175, see Port 5175 is in use.

Where files live

Everything dotpals writes for itself is in ~/.dotpals (or DOTPALS_HOME):

Also:

• Window position, size, small mode and notch mode are kept by the desktop app in window.json in its user-data folder: %APPDATA%\dotpals on Windows, ~/Library/Application Support/dotpals on macOS, ~/.config/dotpals on Linux.
• Other tools' files that dotpals can change, each only when you ask, with the original kept as <file>.dotpals-backup: ~/.claude/settings.json (dotpals statusline), ~/.cursor/hooks.json, ~/.gemini/settings.json, ~/.config/opencode/plugins/dotpals.js and ~/.copilot/hooks/dotpals.json (Connect).
• The Claude Code plugin is installed and managed by Claude Code.
• The pal page, in the desktop app or a browser, remembers the sound toggle, your first pal and the Tools filter in its local storage.

To remove everything, see Resetting everything.