Environment Variables

Configure CloudCLI UI using environment variables or a .env file.

CloudCLI UI is configured using environment variables. For local development and self-hosted setups, you can define these in a .env file at the project root. Settings are read once at startup — change a value and restart the server (or your PM2/systemd unit) for it to take effect.

Getting Started

bash

cp .env.example .env

Then edit .env with your preferred settings.

Precedence

Settings resolve in this order (first match wins):

CLI flags passed when starting the server — highest priority, one-shot overrides.
Process environment — variables set in your shell or by your supervisor (PM2, systemd, Docker).
.env file — committed defaults for a project. Never commit real secrets here.
Built-in defaults — what you get when nothing else is set.

This means cloudcli --port 8080 overrides any PORT value in .env, which is the pattern you want for one-off testing without editing files.

Available Variables

Variable	Default	Description
`PORT`	`3001`	Port the server listens on
`WORKSPACES_ROOT`	`~`	Root directory for project discovery
`ENABLE_HTTPS`	`false`	Enable HTTPS (requires cert setup)

Custom Port

To run on a different port:

bash

# Via .env
PORT=8080

# Via CLI flag (overrides .env)
cloudcli --port 8080

Running more than one CloudCLI UI on the same machine? Give each a distinct port (3001, 3002, …) and they will coexist without conflict. This is useful when you want one instance pinned to your daily workflow and a second instance tracking the main branch for feature preview.

Restricting Project Discovery

By default CloudCLI UI discovers all sessions under your home directory. To restrict it to a specific workspace:

bash

WORKSPACES_ROOT=/home/user/projects

Enabling HTTPS

bash

ENABLE_HTTPS=true

Turns on HTTPS serving. You will also need to supply certificate paths (see the self-hosting guide). For remote deployments, the simplest path is a reverse proxy (Caddy, Nginx, or Traefik) that handles TLS and forwards plain HTTP to the CloudCLI UI on localhost:3001 — fewer moving parts than terminating HTTPS in Node.

Production tips

Run under a process supervisor (PM2, systemd) so it restarts on crash and reboot.
Put a reverse proxy in front (Caddy/Nginx) for HTTPS, compression, and request logging.
Pin WORKSPACES_ROOT to the specific directory you want exposed; leave ~ only for single-user laptop installs.

Troubleshooting

Port already in use. Something else is bound to 3001. Either stop that process or set PORT= to a free port.
Projects are not showing up. Check that WORKSPACES_ROOT actually contains the directories you expect and that Claude Code has created sessions under them.
Changes to .env do not take effect. The server reads .env once at startup — restart the process (or pm2 restart claudecodeui) after editing.