Configuration

The DEJA Server stores all of its configuration in the ~/.deja/ directory inside your home folder. The installer sets this up automatically.

The easiest way to change settings is deja config — an interactive walkthrough for the WebSocket server, WiThrottle, MQTT, cloud sync, console log level, and standby timeout:

deja config                              # interactive walkthrough
deja config get                          # show all settings
deja config set log.level verbose        # change one value
deja config set standby.timeout 45       # standby after 45 idle minutes

Settings saved by deja config live in config.json and take priority over the environment variables below. The reference that follows is for troubleshooting and advanced setups — you generally won't need to edit these files by hand.

Directory Structure

~/.deja/
├── bin/
│   └── deja              # The deja CLI command
├── server/               # Server runtime files
│   ├── index.js          # Server entry point
│   └── version.txt       # Installed version
├── config.json           # Account and layout configuration
├── .env                  # Environment variables
├── server.pid            # Process ID of running server
└── logs/
    ├── server.log        # Current server log
    └── server.log.1      # Previous log (rotated at 10 MB)

config.json

Your account, layout, and secure authentication credentials, plus any subsystem settings saved by deja config (in ws, withrottle, mqtt, and log sections). This file is created during installation and updated when running deja login or deja config.

[!WARNING] Secure File Permissions: config.json contains a sensitive Firebase Authentication refreshToken used to fetch custom tokens for your layout access. This file is automatically written with restricted owner-only permissions (0600 / rw-------) to prevent other local users on the machine from reading its contents.

{
  "uid": "your-user-id",
  "layoutId": "your-layout-id",
  "serverId": "01J0...",
  "refreshToken": "AIzaSy..."
}

Field	Description
`uid`	Your DEJA account user ID
`layoutId`	The layout this server is connected to
`serverId`	Secure server instance identifier generated during login
`refreshToken`	Long-lived authentication token used to sync layout state

You don't need to edit this file by hand — it's managed automatically. If it is missing or corrupt, the server logs a [CONFIG] error and exits; run deja login again to rebuild it.

Standby

Saved by deja config in the standby section of config.json:

Setting	Default	Description
`standby.timeout`	`30`	Minutes of inactivity before the server enters standby (stops trains, cuts track power to the EX-CommandStation, and pauses DEJA Cloud sync). `0` disables idle standby. Loop protection (immediate standby on a runaway command loop) is always on, regardless of this setting.

deja config set standby.timeout 45       # standby after 45 idle minutes
deja config set standby.timeout 0        # never idle-standby (loop protection stays on)

See the Standby section of the CLI reference for the full warning/wake flow, and Troubleshooting if it's triggering unexpectedly.

Environment Variables (.env)

The ~/.deja/.env file controls which features are enabled and how the server connects to external services. The installer creates this file with sensible defaults.

Core Settings

Variable	Default	Description
`LAYOUT_ID`	(from install)	Your layout identifier — matches `config.json`
`ENABLE_DEJACLOUD`	`true`	Connect to Firebase for real-time cloud sync
`ENABLE_WS`	`false`	Start the WebSocket server at boot and admit non-device clients. Off by default — no browser app uses it, and it isn't needed for WebSocket IO devices: the listener opens on its own, device-only, whenever the layout has one
`ENABLE_MQTT`	`true`	Enable MQTT — runs the built-in broker and connects the client, for IoT devices
`ENABLE_WITHROTTLE`	`true`	WiThrottle protocol server for ProtoThrottle, Engine Driver, and other JMRI-compatible throttles — on by default; set `false` to turn it off. Always runs on port `12090`, the standard WiThrottle port
`WITHROTTLE_NAME`	(WS id)	mDNS/service name shown to WiThrottle clients
`VITE_WS_PORT`	`8082`	Port for the WebSocket server
`WS_ID`	`DEJA`	Server identifier string

Firebase Credentials

These are public client SDK keys set automatically during installation to connect the server to your DEJA Cloud layout.

Variable	Description
`VITE_FIREBASE_API_KEY`	Firebase API key (public)
`VITE_FIREBASE_AUTH_DOMAIN`	Firebase auth domain
`VITE_FIREBASE_PROJECT_ID`	Firebase project ID
`VITE_FIREBASE_DATABASE_URL`	Firebase Realtime Database URL
`VITE_FIREBASE_STORAGE_BUCKET`	Firebase storage bucket
`VITE_FIREBASE_MESSAGING_SENDER_ID`	Firebase messaging sender ID
`VITE_FIREBASE_APP_ID`	Firebase app ID

[!NOTE] No Service Account Keys Required: Historically, the server required a service account email and private key (FIREBASE_CLIENT_EMAIL and FIREBASE_PRIVATE_KEY). These are deprecated for end-user installations and have been removed. Authentication is now handled dynamically and securely via deja login.

Optional Settings

Variable	Description
`MQTT_BROKER`	MQTT broker URL (default: `mqtt://localhost`). The server runs its own broker here unless this points at another machine
`MQTT_PORT`	MQTT broker port (default: `1883`)
`MQTT_EMBEDDED`	Run the built-in MQTT broker (default: `true`). Set `false` to only connect to an external broker at `MQTT_BROKER`
`AUDIO_CACHE_SIZE_MB`	Max size of the server's sound-effect cache in MB (default: `200`)
`AUDIO_CACHE_DIR`	Directory for cached sound files (default: `temp-sounds-cache`)
`WS_ALLOWED_ORIGINS`	Comma-separated allowlist of origins permitted to open a WebSocket connection
`WS_AUTH_TOKEN`	Optional shared secret clients must present to connect over WebSocket — hardening for the LAN WebSocket

Editing Configuration

The safest way to change the settings the server exposes is the settings command in the console (deja, then type settings), or deja config from any terminal. Both write the same keys straight to config.json — no manual file editing.

Setting	What it controls
MQTT	Toggle the MQTT subsystem on/off
WebSocket	Toggle the WebSocket server on/off
MQTT Port	Broker port (default `1883`)
MQTT Broker	Broker URL (default `mqtt://localhost`)
WS Port	WebSocket server port (default `8082`)

Use ↑/↓ to move, ↵ or Space to change a field, and Esc to close. For text fields, ↵ saves and Esc cancels. Changes take effect on restart.

For anything settings doesn't cover (Firebase credentials, LAYOUT_ID, audio cache settings, etc.), edit ~/.deja/.env directly in a text editor:

nano ~/.deja/.env

After making changes, restart the server for them to take effect:

deja restart

Log Rotation

Server logs are stored at ~/.deja/logs/server.log. When the log file reaches 10 MB, it's automatically rotated — the current log is saved as server.log.1 and a new log file is started.