How to Install Claude Command Center on Linux

What Claude Command Center does

CCC is a source-available dashboard for developers managing multiple coding agents. The project describes a local board that reads agents' on-disk session state, including sessions launched outside the dashboard. It can help distinguish work that is active, waiting for attention, dormant, or archived. Claude Code is described as the first-class integration; other engines have documented gaps.

The dashboard is more than a status display. Its advertised capabilities include transcript views, session organization, history search, context indicators, and sending instructions to supported sessions. An installation that renders a web page has not necessarily established working session discovery or safe remote control. We test those separately.

Version and verification boundary

The project overview reviewed for this guide identifies version 5.43.0. The repository listing identifies commit ad7acb80ee78fa17a0410dd8056b521d38c5107f. These are separate observations, not proof that the commit is the release tag. The listing confirms files including run.sh, pyproject.toml, README.md, LICENSE, and a systemd directory.

The contents of the current startup and service-installation scripts could not be independently verified here. Consequently, this guide does not certify a Python minimum, automatic dependency installation, a systemd unit name, or a CCC data directory. It provides commands to inspect those details before execution. If you need an unattended, version-certified installation, stop at that review gate rather than treating the conditional commands below as a tested installer.

Use the maintained CCC repository and README alongside your checkout. The project overview explains the intended workflows. Source installation is the scope here; Homebrew, downloaded shell installers, and Docker deployment are not interchangeable with this procedure.

Separate dashboard requirements from agent requirements

Use a normal, non-root Linux account with a durable writable installation directory. That account should also own the coding-agent sessions you intend to inspect. Running CCC as root to work around permissions increases exposure and can put it in a different home directory from your agent state.

Git is needed for the source workflow. Python is relevant to the project, but the previously stated Python 3.9 minimum is not independently established by the current file listing. Determine the requirement from the checked-out metadata, README, and launcher before installing or changing runtimes. Do not replace your distribution's system Python.

id
git --version
command -v python3
python3 --version
curl --version
command -v ss

Install missing general-purpose tools through your distribution's maintained package manager. Package names differ between distributions, and a Python virtual-environment package may be separate. Whether CCC needs it depends on the inspected launcher; do not install a guessed dependency list.

Claude Code is a separate prerequisite

For the first-session exercise, use an already installed and authenticated Claude Code CLI. Its runtime requirements, account access, model availability, and provider credentials are separate from CCC's requirements. Installing the dashboard does not establish that Claude Code is installed, logged in, or authorized to use a model.

This guide does not specify a Claude Code installer or account entitlement because neither is verified in the available primary project material. If the agent is not already operational, complete its maintained installation and sign-in process before attempting the session exercise. Never paste provider credentials into a dashboard field unless that field's purpose and storage behavior are understood.

Retrieve and review the Linux source installation

Use one absolute repository location throughout the procedure. The example below chooses $HOME/src/claude-command-center; that is our working-directory convention, not a CCC requirement. Repeating cd claude-command-center from inside the checkout would incorrectly look for a nested directory.

mkdir -p "$HOME/src"
git clone https://github.com/amirfish1/claude-command-center.git \
  "$HOME/src/claude-command-center"
cd "$HOME/src/claude-command-center"
git remote -v
git status --short
git rev-parse HEAD

cd "$HOME/src/claude-command-center"
less README.md
less pyproject.toml
less run.sh
less LICENSE
less LICENSE-MIT
less NOTICE

grep -nEi 'requires-python|python|venv|pip|install-service|systemd|8090' \
  pyproject.toml run.sh README.md

cd "$HOME/src/claude-command-center"
./run.sh

Before executing the launcher, establish which Python version it selects, what it downloads, whether it creates an environment, whether it modifies shell files, and whether it starts persistent processes. If the script delegates those actions, inspect the delegated scripts too. Do not use sudo merely because setup reports a permission error.

Leave the first process visible in the terminal. If it exits, diagnose the earliest error rather than repeatedly starting additional copies. A script returning to the prompt can also mean it launched a background process; check the socket and process state before concluding that it failed.

Verify HTTP access and one harmless agent session

First establish that CCC, not another process, owns the expected endpoint. In a second terminal on the Linux host, run:

ss -ltnp 'sport = :8090'
curl --noproxy '*' --max-time 10 -sS -o /dev/null \
  -w 'HTTP %{http_code}\n' http://127.0.0.1:8090/

The socket output shows the bind address. A listener on 127.0.0.1 or ::1 is loopback-only; 0.0.0.0 or [::] generally indicates broader binding. Do not assume that a localhost URL proves a loopback-only listener. Process details may be limited by ownership and system permissions.

An HTTP response proves reachability, not application health. A redirect may be expected, while a server error requires investigation. Open http://localhost:8090 on the same machine, confirm the dashboard renders, refresh it, and visit non-destructive views. If only the numeric IPv4 address works, compare IPv4 and IPv6 listener behavior before changing CCC settings.

A reproducible first-session acceptance test

This exercise uses CCC's advertised discovery of externally launched sessions. It avoids guessing dashboard buttons, plugin installation commands, or hooks. Run it only after Claude Code already works independently.

1. Create a disposable project under the same Linux user as CCC.
2. Start your installed Claude Code CLI there, with its normal permissions and authentication.
3. Ask for a harmless response, then look for that session in CCC.
4. Compare its directory, transcript, and completion state with the terminal session.
5. Only after discovery succeeds, test a harmless follow-up through the dashboard if your installed version supports it.

mkdir -p "$HOME/ccc-smoke-test"
cd "$HOME/ccc-smoke-test"
git init
printf '%s\n' '# CCC local smoke test' > README.md
command -v claude
claude --version
claude

Use this initial prompt: Reply with CCC local smoke test OK. Do not edit files, run commands, or access the network. The request still uses your agent's configured model and may incur usage charges. Do not disable approval controls for this test.

Locate the resulting session in CCC and compare the exact response. If a supported composer is available, send a second request such as Reply with CCC follow-up OK without using tools. Confirm the response appears once and belongs to the intended session. Do not repeatedly resend an uncertain action.

If the session does not appear, record this as an integration failure even if the dashboard loads perfectly. Check user identity, agent installation, session persistence, and engine-specific instructions in your checkout. Automatic discovery is an advertised capability, not proof that every local version combination needs no configuration.

Identify and manage the actual Linux user service

The earlier installation workflow used ./run.sh --install-service, but the current script contents are not independently verified here. Treat that command as conditional: use it only if your reviewed launcher and README explicitly support it. If they do not, keep the interactive installation rather than substituting an invented unit file.

Before installing a service, stop the foreground instance using its documented shutdown method. For a genuinely foreground process, Ctrl+C is the usual first attempt; confirm that the listener closes. Closing a browser tab does not stop the server or necessarily stop its agents.

systemctl --user list-unit-files --type=service
cd "$HOME/src/claude-command-center"
grep -nEi 'install-service|systemctl|\.service' run.sh
find systemd -maxdepth 2 -type f -print

Inspect the relevant installer and unit files before proceeding. If the flag is confirmed, the conditional installation command is:

cd "$HOME/src/claude-command-center"
./run.sh --install-service

Discover the unit instead of guessing its name

Read the installer's output, list user units again, and inspect candidates. CCC may involve more than one component. Do not assume a dashboard unit also manages a worker.

systemctl --user list-unit-files --type=service
systemctl --user list-units --all --type=service

For each candidate, inspect its executable and working directory. The following prompt deliberately requires the actual name from your machine:

read -r -p "Exact CCC user-service unit name: " CCC_UNIT
systemctl --user cat "$CCC_UNIT"
systemctl --user show "$CCC_UNIT" \
  -p FragmentPath -p ExecStart -p WorkingDirectory -p EnvironmentFiles
systemctl --user status "$CCC_UNIT" --no-pager
journalctl --user -u "$CCC_UNIT" -n 100 --no-pager

Confirm that the executable and paths belong to your installation before using administrative commands. Unit definitions or logs can contain secrets; redact them before sharing.

Status, logs, stop, and restart

systemctl --user is-active "$CCC_UNIT"
systemctl --user is-enabled "$CCC_UNIT"
journalctl --user -u "$CCC_UNIT" -f

Ctrl+C ends log following without stopping the service. During a maintenance window, these generic systemd commands operate on the verified unit:

systemctl --user stop "$CCC_UNIT"
systemctl --user start "$CCC_UNIT"
systemctl --user restart "$CCC_UNIT"

A systemd restart is not necessarily an application-aware drain. The CCC v5.41.0 release notes document ccc restart [all|dashboard|worker] with drain-aware behavior and merging of restart requests within five minutes. Prefer the supported application restart workflow when available and confirmed in your installation. Do not interpret a deferred restart as permission to issue repeated forced restarts.

Check logout behavior separately with loginctl show-user "$USER" -p Linger. An enabled user unit does not by itself guarantee startup before login. Changing lingering affects account lifecycle policy; coordinate it with the host administrator rather than silently enabling it.

Updates, backups, and recovery

A recoverable installation needs more than a copy of its source code. Separate the checkout, CCC configuration and state, coding-agent history and credentials, and the repositories agents modify. These assets may live in different locations and may have different confidentiality requirements.

Build a backup inventory before updating

No canonical CCC data directory or complete restore procedure is verified here. Identify actual paths from the installed version's documentation, configuration, service definition, and startup output. Do not infer a data directory from a similarly named folder in the source tree.

• Record the source commit, runtime versions, installation path, and confirmed unit names.
• Identify every persistent configuration and state location, including paths outside the checkout.
• Determine whether databases require a native backup or a stopped application for consistency.
• Back up agent workspaces and histories separately where needed.
• Protect backups containing credentials, transcripts, or source code with appropriate access controls and encryption.

If you cannot identify state locations or a consistency method, you do not yet have a reliable application backup. Postpone an important upgrade until that gap is resolved. A live directory copy can capture inconsistent database files.

Inspect an update before applying it

cd "$HOME/src/claude-command-center"
git status --short
git rev-parse HEAD
git branch --show-current
git fetch --tags origin
git log -5 --oneline

Save the current commit in your maintenance record. Review upstream changes, migrations, requirements, and release notes before choosing a target. Fetching does not modify the working tree. Do not use a blind git pull on a modified or detached checkout.

For a clean branch intentionally tracking a reviewed upstream branch, git pull --ff-only avoids creating an unexpected merge. It is not a CCC migration procedure. Stop or drain the relevant components, take a consistent backup, update using the installed version's supported procedure, then repeat the local HTTP and disposable-session tests.

Recovery is code plus compatible state

If an update fails, keep public access disabled and preserve logs. Restoring an old source revision alone may not reverse a state migration. Recover the known-good code, compatible runtime dependencies, configuration, and matching state backup together. Test restoration in an isolated environment that cannot accidentally resume production agents or reuse active credentials.

Use the same checks after recovery: the intended process owns the listener, the dashboard loads, sessions are discovered, and a harmless interaction succeeds. Only then reconsider service persistence or remote access.

Establish access control before any public tunnel

CCC can reveal transcripts and repository context and may instruct coding agents. Treat unauthorized dashboard access as potentially consequential development-system access. HTTPS protects transport to an endpoint; it does not decide who may read a transcript or send an instruction.

A possible design uses a separately managed authentication gateway in front of CCC. This is an architectural option, not a validated CCC integration or an assertion that a particular gateway configuration works. The protected entry point must cover HTML, APIs, live connections, and state-changing operations without leaving a direct route around it.

• With a clean browser profile, verify that protected content and actions are denied before authentication.
• Test direct requests to sensitive routes observed during normal use, not just the homepage.
• Verify that an authenticated user is authorized for the intended projects and controls.
• Test logout, session expiry, and revoked access.
• Ensure the tunnel target is the protected entry point, not the unprotected backend.
• Verify that CCC is not unintentionally reachable through another LAN or public listener.

If the application cannot enforce the privilege separation you need, an outer login screen cannot invent those permissions. Do not proceed with public access.

A private-access alternative

For a host you already reach through authorized SSH, a loopback-bound SSH forward can provide private browser access without publishing an HTTP URL. This is a general networking technique, not verified CCC compatibility or an SSH setup guide. It requires an existing, authenticated SSH connection and server policy that permits forwarding.

ssh -N -o ExitOnForwardFailure=yes \
  -L 127.0.0.1:18090:127.0.0.1:8090 your-existing-ssh-host

Replace your-existing-ssh-host with your configured SSH host. Open http://127.0.0.1:18090 on the computer running SSH. Keep the SSH process alive and verify the full dashboard workflow. Other local users or processes may still reach that local port, so use a trusted device.

Our VPN Manager provides private mesh networking with granular firewall rules, but its compatibility with this specific CCC deployment is not validated here. Standard Localtonet HTTP tunnels are not VPN functionality.

Conditional HTTP tunneling with Localtonet

With Localtonet, our client establishes an outbound connection to a relay and can expose an HTTP service through a public HTTPS address without inbound router port forwarding or a public IP address. Availability requires both a connected client and a running tunnel. Connectivity does not supply missing CCC authentication or prove upstream integration support.

The following is conditional on passing every security check above. Follow our HTTP tunnel documentation for the current interface. Exact client installation commands and custom-domain DNS records are not reproduced here because they have not been verified for a particular Linux client version.

After authorized exposure, test from a clean external browser before using sensitive sessions. Confirm denied unauthenticated requests, authorized rendering, live updates, and one harmless interaction. This external test supplements the prerequisite local tests; it is not the first time authentication should be checked.

Stop the tunnel on any unexpected access or behavior. CCC can remain available locally while the tunnel is stopped. Delete unused tunnel configurations and keep device tokens out of repositories, screenshots, and issue reports.

Practical diagnostics by failure layer

Check disk and directory ownership

cd "$HOME/src/claude-command-center"
pwd
ls -ld . "$HOME"
ls -l run.sh
df -h .
git status --short
git ls-files --stage run.sh

A full filesystem or files owned by another account can break setup. Do not recursively change ownership of your home directory as a generic repair. Determine how the incorrect files were created and correct only the affected installation paths.

Compare local and remote behavior

If an interaction fails both locally and remotely, troubleshoot CCC or the agent first. If it fails only through a protected route, inspect browser network errors and relevant gateway logs. Do not guess proxy headers, disable origin checks, or expose the backend to make a failed test pass.

For a useful support report, include the CCC commit, agent version, Linux distribution, launch mode, exact failing operation, sanitized error, and whether HTTP, discovery, and interaction tests passed. Exclude tokens, credentials, transcript contents, and private project paths.

Frequently asked questions