DEVICE REFERENCE

Daemon & CLI

The daemon connects outward from your computer to Caterm. It runs your local agents and enables the remote capabilities you configure.

Install or upgrade Caterm using Getting started. This page covers commands and configuration for an installed CLI.

Connect and reconnect

These examples assume caterm is installed and available on your PATH. These are simulated examples. Replace the server and 8-digit code with values from your Caterm workspace.

caterm connect --server https://your-caterm.example \
  --enrollment-code 00123456
caterm connect --saved
caterm --help
caterm --version

Background operation and logs

On Linux, every connect command runs in the background by default and keeps reconnecting after network failures. Startup confirms local readiness; check the logs for server connection status. Stop the current daemon before changing its options or switching modes.

caterm logs
caterm logs -f
caterm stop
caterm connect --saved -i
# Equivalent foreground option:
caterm connect --saved --interactive

Foreground mode runs until Ctrl-C. Following logs with -f ends on Ctrl-C while the daemon continues running. Logs shows the latest 100 lines; use --lines N to change the count. Background logs live in $XDG_STATE_HOME/caterm or ~/.local/state/caterm, with private permissions and rotation at 5 MiB plus one previous file. No boot autostart or automatic crash restart is configured. Rejected device credentials stop the daemon. Other platforms keep connections in the foreground.

Remote Linux updates

On a Linux device’s Info page, its owner can choose Software updates → Update and reconnect. Remote updates are enabled by default and need no confirmation on the device. Caterm downloads and verifies the latest stable release, preserves your connection and permissions, and restarts automatically. Active terminal, desktop and agent sessions end. Download failures keep the old daemon running; replacement or startup failures restore the old version. Shared members cannot initiate updates, and paused devices must be enabled first.

Older Linux clients need one local caterm upgrade and restart before their first Web update. Updates need a writable installation directory and never invoke sudo. An interactive connection resumes in the background. Update logs are saved as update.log beside the daemon logs. macOS release apps also support the Web update action with no local confirmation. The app must be owned by its user in a writable folder; older Mac apps need one local update first. The Caterm app menu still offers local updates.

Local AI agent configuration

Install and sign in to Codex on this device first. These are simulated paths; set the actual executable and project directory.

export CATERM_CODEX_BINARY=/absolute/path/to/codex
export CATERM_CODEX_WORKSPACE=/absolute/path/to/projects
caterm connect --saved

Without an explicit path, the daemon searches trusted local installation directories and its inherited PATH. The workspace defaults to the file root. Set CATERM_ALLOW_CODEX=false to opt out. Claude Code has equivalent CATERM_CLAUDE_BINARY, CATERM_CLAUDE_WORKSPACE, and CATERM_ALLOW_CLAUDE settings. Read the conversation guide →

Scoped file access

File access is enabled by default. Set one root directory for remote file operations. Requested paths must remain inside it. The default is the daemon user's home directory; choose a narrower folder when possible.

# Example path: replace it with your own directory.
CATERM_FILE_ROOT=/path/to/allowed/files caterm connect --saved

Browser terminal

Terminal access is enabled by default. Set the daemon environment to false to disable remote shell access.

caterm connect --saved
# Disable terminal access:
CATERM_ALLOW_TERMINAL=false caterm connect --saved

Separate execution boundaries

A terminal runs the daemon user's shell and is not confined by the file root. The agent root restricts the selected project directory; agent tools follow the local CLI permission policy. The daemon and agent processes may run as root or an ordinary user and inherit that account’s OS privileges. Review approvals in the local CLI.

Optional Linux desktop

Linux shares your existing local X11 desktop. Run caterm desktop doctor as its owner and install/configure any missing prerequisites yourself. Enable sharing with caterm connect --desktop. It checks prerequisites and exits without connecting if they are not satisfied. Follow the Linux setup guide →

Credential location

Saved enrollment credentials live at $XDG_CONFIG_HOME/caterm/credentials.json, or ~/.config/caterm/credentials.json. The daemon creates the file with mode 600 and its directory with mode 700. Rotate or revoke the device credential if it may have been exposed.