Install Treeport

The Treeport backend supports macOS and Linux.

Install these required tools before you install Treeport:

Node.js 24 or a newer version
npm
Git
tmux 3.2 or a newer version

Treeport does not install these tools.

The desktop client supports macOS 12 Monterey or a newer version. It supports Apple Silicon and Intel Macs.

Install the macOS desktop client

Download the DMG from the latest GitHub Release.
Open the DMG.
Drag Treeport to the Applications folder.

The universal application has an Apple Developer ID signature and Apple notarization.

The desktop client connects to a separate Treeport backend. It does not contain the backend.

Install the backend on this Mac with npm. Alternatively, connect to a private HTTPS backend on another computer.

The desktop client checks for stable updates automatically. After it downloads an update, it shows Update & restart in the title bar.

Select this control to restart the client and install the update.

A desktop update does not upgrade or restart the selected backend.

Install the backend

Install Treeport globally:

npm install --global @treeport/treeport

Open a folder or Git repository:

cd /path/to/project
treeport .

Treeport starts the backend when necessary.

For a repository, Treeport registers the repository and finds its trees.

For an ordinary folder, Treeport creates one folder tree.

In a managed terminal, it opens the selected tree in the current Treeport client.

From another terminal, it opens the macOS desktop client or the default browser.

To start only the backend, run:

treeport start

This command prints the local URL. The default URL is http://127.0.0.1:8733.

Update the backend

Treeport checks for stable backend updates approximately every ten minutes.

When an update is available, a Download control appears before the notification bell. Select the control. Then, select Update Treeport.

Treeport verifies the release before it stops the daemon. It preserves running tmux terminals and restarts the same daemon lifecycle.

The page reconnects after the restart. It then opens the same workspace with the new web assets.

The macOS desktop client shows this backend control when it uses a local backend. It does not show the control for a remote backend.

You can also update the backend with this command:

treeport update

Use this command for automation or recovery. An enabled service stays enabled. An intentionally stopped daemon or service stays stopped.

Your user must have write access to the global npm prefix. Treeport never uses sudo for an update.

If the prefix is not writable, install Node and npm under your user account. Then, install Treeport globally again.

Installations older than the first release that supports updates need one final manual npm update.

Connect the desktop client

At first start, the desktop client tries This computer at http://127.0.0.1:8733.

If Treeport is active, the desktop client opens your projects.

If Treeport is not active, open a folder or repository from a terminal:

treeport /path/to/project

This command starts the backend and opens the selected tree.

To use another computer, select Connect to another computer…. Enter a private HTTPS Treeport URL.

The desktop client saves the last computer that you selected. See Remote access for the supported Tailscale Serve configuration.

Check the installation

Run these checks:

treeport status
treeport doctor
treeport version

The command treeport stop stops the daemon but keeps persistent tmux sessions. A later treeport start connects them again.

Start Treeport automatically

A normal installation does not register an operating-system service.

On macOS, enable startup after login:

treeport service enable

This command installs a per-user LaunchAgent without sudo or an administrator request.

Service mode also restarts Treeport after an unexpected exit.

For startup before login on macOS, select advanced headless mode explicitly:

treeport service enable --headless

Advanced headless mode uses a system LaunchDaemon and requires administrator approval.

On Linux, Treeport installs a systemd user unit.

If user lingering is off, Treeport prints the necessary loginctl enable-linger administrator command. This setting permits startup without login.

Check service mode:

treeport service status
treeport doctor

See Service supervision for service behavior, logs, updates, recovery, and removal.

Remove Treeport

Disable service mode before you remove the CLI:

treeport service disable
npm uninstall --global @treeport/treeport
rm -rf "$(npm prefix --global)/lib/treeport"

The final command removes only the Treeport-owned update versions. Run it after npm removes the global command.

If service mode was not enabled, treeport service disable is safe. It reports that the service is disabled.

An npm removal keeps application data by default.

npm cannot run a reliable package removal hook. Thus, always use the explicit service disable command.

Do not expose Treeport directly to the public internet.