Install the Termix CLI with npm for Fleet Management

How the Termix CLI workflow fits together

Termix is a self-hosted server-management platform with a browser interface for SSH terminals, remote desktops, file management, SSH tunnels, containers, host metrics, alerts, automations, and fleet operations. The separate Termix CLI provides a command named termix. That command talks to an existing Termix server and uses the hosts, credentials, permissions, and other resources already configured there.

This distinction matters during installation. Installing @termix-cli/cli does not install the Termix server and does not create an SSH inventory by itself. You need a reachable Termix server before termix login can succeed. If your organization already runs Termix, you can skip the server-build section and install the CLI directly. If not, this guide includes the documented manual source build and a source-built Docker image workflow.

For local-only operation, the CLI can connect directly to a Termix URL reachable from the same machine or private network. For remote operation, the CLI needs a URL it can reach from its current location. A Localtonet HTTP tunnel can provide that public address after the Termix service has been installed, started, and verified locally.

Prerequisites for the server, CLI, and tunnel

The prerequisites depend on which parts of the workflow you need. The Termix CLI requires Node.js 20.11 or newer when installed through npm. Termix also documents standalone CLI downloads for Windows, Linux, and macOS that do not require Node.js, but the supplied installation evidence does not include their exact download filenames or installation commands. This guide therefore uses the fully documented npm method.

The manual Termix server build has a different baseline. Its documented prerequisites are Git, Node.js 18 or higher, npm, Docker, Docker Compose, and OpenSSL when HTTPS is used. Because the CLI requires the newer Node.js baseline, use Node.js 20.11 or newer when one machine will build the server and run the npm-installed CLI. That version satisfies both documented minimums.

Confirm Node.js and npm

Check the installed versions before installing the CLI. The first command should report Node.js 20.11 or newer for the npm-based CLI path. The second should return an npm version rather than a command-not-found error.

node --version
npm --version

If Node.js is older than 20.11, upgrade it using the supported process for your operating system or environment before continuing. This guide does not prescribe an operating-system package command because repository names, package versions, and installation methods differ among platforms.

Decide where the Termix service will run

The Termix server can run on the same machine as the CLI, on another device on the local network, or on a host reachable over another authorized network path. The Localtonet client must run on a device that can reach the Termix IP address and port selected as the tunnel target. It does not have to be the exact same device, although colocating them often simplifies local addressing.

Prepare a Termix server if you do not already have one

Readers who already have a working Termix URL can continue to the CLI installation section. If you need a server, the official manual workflow supports compiling the project from source. Termix documents a default local URL of http://localhost:8080, or the equivalent address using whichever port you configure.

The manual documentation reports approximately 118 MB of memory while idle and states that one CPU core with 1 GB of memory covers most setups. Actual requirements can grow with fleet size and activity, so treat those figures as project-provided starting guidance rather than a universal capacity guarantee.

Manual development-style source workflow

git clone https://github.com/Termix-SSH/Termix.git
cd Termix

npm install
npm run build

npm run preview

npm run dev:backend

Keep both required processes running while testing. Termix recommends serving the website through Nginx for production environments and points to the Nginx configuration in the repository's Docker directory. The preview and development backend commands are useful for following the documented manual build, but they should not be mistaken for a complete production operations design.

Build a Termix Docker image from source

Termix also documents building a Docker image from the cloned source. This path produces an image named termix:latest, maps host port 8080 to container port 8080, and persists application data in a named volume.

git clone https://github.com/Termix-SSH/Termix.git
cd Termix

npm install

npm run build

docker build -t termix:latest -f docker/Dockerfile .

services:
  termix:
    image: termix:latest
    container_name: termix
    restart: unless-stopped
    ports:
      - '8080:8080'
    volumes:
      - termix-data:/app/data
    environment:
      PORT: '8080'

volumes:
  termix-data:
    driver: local

docker-compose up -d

Understand the default database behavior

Termix uses SQLite by default and creates the database under db/data on first start. No separate database provisioning or migration command is required for that default path. The documented container configuration mounts /app/data to a named Docker volume so application data can persist when the container is replaced.

PostgreSQL and MySQL are also documented options. They require a database and user to be created before Termix starts, followed by the appropriate database dialect and connection configuration. Exact production credentials, TLS settings, MySQL options, and connection-pool choices depend on the deployment. Do not copy a sample password into a real environment or commit a database connection string to source control.

Verify the local web service

Open http://localhost:8080 in a browser on the server machine when using the documented default port. If Termix runs on another device, replace localhost with the authorized local IP address or hostname of that server. Complete the application setup, create or select an appropriate user, and confirm that you can sign in.

Do not proceed to public tunneling merely because a process is running. Confirm that the login page loads, authentication works, and the expected Termix interface appears. Add at least one test host only when you have permission to access that host, then verify the connection locally before introducing another network layer.

Install the Termix CLI globally with npm

Once Node.js 20.11 or newer is available, install the Termix CLI as a global npm package. A global installation places the termix executable in npm's global binary location so it can be called from ordinary terminal sessions.

node --version

npm install -g @termix-cli/cli

termix --help

If the installation finishes but termix is not found, close and reopen the terminal first. If that does not help, inspect npm's global installation location and verify that its executable directory is included in your shell's PATH. Avoid changing global permissions blindly or running unrelated commands with elevated privileges. npm configuration differs across operating systems, version managers, and managed workstations.

Log in to Termix and verify the connection

The CLI needs the base URL of your Termix server. For a locally running instance on the documented default port, that may be http://localhost:8080. For a server already protected by HTTPS, use its HTTPS URL. Later, if you publish Termix through Localtonet, you can use the public HTTPS address assigned to the running HTTP tunnel.

termix login --url https://termix.example.com

termix hosts

Host output includes IDs. Most resource-oriented commands use those IDs to identify the target. If the list is empty, that does not necessarily mean authentication failed. The account may not have any hosts configured or shared with it. Confirm the inventory and role assignments in the Termix web interface.

Open an interactive SSH session

After identifying an authorized host ID, use termix ssh to open a terminal. The official example uses host ID 3:

termix ssh 3

Replace 3 with an ID returned by your own termix hosts output. An ID is instance-specific, so never assume that a number from an example refers to the same server in another environment.

Execute one command and return

Use termix exec for a non-interactive command. This example runs uptime on host ID 3 and returns after execution:

termix exec 3 uptime

Start with a read-only command while validating a host. The CLI operates with the access represented by the Termix host configuration and account permissions, so a successful login should never be treated as permission to make unrestricted changes.

Use the CLI for hosts, fleets, files, and automation

Termix fleets group hosts either by explicit selection or by tag rules. Tag-based membership can allow new matching hosts to join automatically. Fleet operations can run one command across every member, push or pull files, install packages, and collect inventory information such as operating system, kernel, architecture, and uptime.

Before executing a fleet-wide action, inspect the available commands and verify the target fleet. Built-in help is the authoritative description of the options supported by your installed CLI version.

termix fleets --help
termix fleets exec --help

Use built-in help before a high-impact command

Every command has built-in help. Use the top-level help to discover command groups and append --help to a specific command for its current syntax:

termix --help
termix hosts --help
termix fleets exec --help

This is particularly important for fleets. A command aimed at one host has a limited blast radius, while a fleet command can affect every selected or tag-matched member. Check dynamic membership, review permissions, and test on a small non-production fleet before applying a change broadly.

Produce output suitable for scripts

The Termix CLI displays a readable table when its output goes to a terminal. When output is piped, it automatically switches to JSON. This behavior makes the same command convenient for interactive use and shell automation.

termix hosts | jq '.[].name'

You can force JSON output with --json, force the non-JSON form with --no-json, or use -q when only IDs are needed. Explicit output flags are preferable in long-lived automation because they make the expected data format clear.

For scripts and continuous integration, Termix recommends an API key instead of an interactive username and password login. Create keys with the narrowest practical scope and expiration, store them in the secret-management facility provided by the automation system, and never print them in logs. The evidence available for this article does not establish the exact environment-variable or configuration-file syntax for supplying a Termix API key, so consult the installed CLI's help and current Termix scripting documentation rather than guessing.

Expose the working Termix web service with Localtonet

Complete this section only after Termix loads and accepts authentication through its local address. With Localtonet, our client application establishes an outbound connection from the device to a relay server. An HTTP tunnel then provides a public HTTPS address and forwards requests to the Termix IP address and port reachable from that client device.

This removes the need for inbound router port forwarding, firewall changes, VPN setup, or a public IP address. The tunnel remains available only while the selected Localtonet client or device is connected and the tunnel is running.

HTTP tunnels can use a generated subdomain, a selected subdomain where supported, or a custom domain. Exact custom-domain DNS requirements must be checked against the current Localtonet documentation before making DNS changes. Do not assume that every process type, relay region, or domain option is included in every plan.

Point the Termix CLI at the public URL

Once the Localtonet URL works in a browser, use that assigned HTTPS address with the documented login syntax:

termix login --url https://termix.example.com

Replace the example URL with the actual public address assigned to your Localtonet HTTP tunnel. The login flow prompts for your Termix username, password, and 2FA code when enabled. The Localtonet device token is not a Termix login credential and must never be entered into this prompt.

After login, run termix hosts and compare the result with the inventory visible through the local connection. If the public page works but the CLI does not, inspect the CLI error and server logs before changing the tunnel target. Authentication failures, application routing problems, and local connectivity failures are separate issues.

Secure Termix remote access and fleet operations

A server-management platform deserves stronger controls than a low-risk demonstration page. Termix can provide access to terminals, remote desktop sessions, files, containers, metrics, tunnels, credentials, automations, users, and audit logs. Exposing its login page publicly should therefore be a deliberate administrative decision supported by account security and least-privilege design.

Enable strong Termix authentication

Termix supports local accounts as well as OIDC, LDAP, GitHub, and Google sign-in. It also supports two-factor authentication with TOTP, passkeys through WebAuthn, and trusted devices. Choose the authentication method appropriate for your organization and enable a second factor for privileged users where possible.

Review active sessions and revoke sessions that are no longer expected. If multiple people use the instance, avoid sharing one administrator account. Individual identities improve permission assignment and make the audit log more useful.

Apply least privilege to hosts and fleets

Termix roles can share hosts with users or roles at four levels: connect, view, edit, and manage. Assign the lowest level that supports the intended task. A user who only needs to open a permitted SSH session should not automatically receive the ability to edit host definitions, manage credentials, or administer every shared resource.

Fleet permissions need particular care because one action can reach many systems. Separate production and test fleets, review tag-based membership, and avoid broad rules that silently include sensitive hosts. Test automations safely before allowing scheduled, webhook-triggered, or threshold-triggered workflows to affect a large fleet.

Protect every credential type

This workflow can involve several unrelated secrets: Termix user passwords, 2FA codes, SSH credentials, Termix API keys, database credentials, and the Localtonet device authentication token. They serve different trust boundaries and should not be reused.

Keep secrets out of shell history, Compose files committed to repositories, screenshots, issue reports, and copied command output. Use protected secret stores for automation. If a secret is exposed, rotate or revoke it through the system that issued it rather than assuming that deleting a terminal line removes the risk.

Limit tunnel availability

A Localtonet tunnel is available only while its selected client is connected and the tunnel is running. Stop the tunnel when remote access is no longer required, or delete it when the configuration will not be reused. Confirm that the public URL stops serving the application after shutdown.

Troubleshoot installation, login, fleet, and tunnel issues

npm install rejects the Node.js version

Run node --version in the same terminal used for npm. The CLI requires Node.js 20.11 or newer. If you use a version manager, a different shell may activate a different Node.js version. Upgrade or select a compatible runtime, then repeat the installation.

The installation succeeds but termix is not found

Open a new terminal so the shell reloads its environment. If the problem remains, verify npm's global executable location and ensure it is present in PATH. A version manager may keep global packages separate for each Node.js version, so confirm that the installation and execution happen under the same active runtime.

termix login cannot reach the server

Open the same base URL in a browser from the CLI machine. If the browser also fails, resolve the server or tunnel connectivity problem first. Check that Termix is running, the hostname is correct, the intended port is listening, and the URL scheme matches the working endpoint.

For local testing, verify http://localhost:8080 only when the CLI and Termix service run on the same machine with the documented default port. From another device, localhost points to that other device, not to the Termix server.

The Termix page loads but login fails

This usually moves the investigation from transport to application authentication. Confirm the username, password, account status, and 2FA code. Check whether the account is expected to use local login or another configured identity provider. Do not repeatedly retry unknown credentials against a public endpoint.

termix hosts returns no hosts

Verify that hosts have been created in the Termix web interface and shared with the current user or role. Use termix whoami and termix status to inspect the current CLI identity and state. An empty inventory can be a valid permissions result rather than a network failure.

An SSH or exec command fails for one host

Confirm that the host ID came from the current server's termix hosts output. Then test the same host through the Termix web interface. Review the host address, credential assignment, jump-host configuration, permissions, and network reachability. The Localtonet HTTP tunnel reaches the Termix web service; it does not automatically repair Termix-to-host SSH connectivity.

A fleet command targets unexpected machines

Stop before rerunning it. Review whether the fleet uses explicit host selection or tag rules. A tag-based rule may add newly matching hosts automatically. Inspect membership and test the command on a smaller fleet or single host before repeating the broad operation.

The Localtonet public URL does not load

First verify the local Termix target directly from the Localtonet client device. Then confirm that the correct device is connected, the intended tunnel configuration exists, and the tunnel was explicitly started. Check the local IP address and port, especially if Termix is on another LAN device or uses a non-default port.

Do not hardcode a relay code from an old guide. Select a currently available server or region from the dashboard. Remember that the public endpoint stops working when the selected client disconnects or the tunnel stops.

The public page works but the CLI behaves differently

Run termix --help, termix status, and termix whoami. Verify that the saved CLI session belongs to the expected Termix instance and user. If you previously logged in to a local URL and then moved to a public URL, repeat the documented login flow with the intended server URL.

JSON processing fails in a script

Piped output should switch to JSON automatically, but long-lived scripts should request the intended format explicitly with --json. Validate the output before destructive processing and use the command's built-in help to confirm flag placement for the installed version. Also confirm that jq, if used, is installed independently and that the filter matches the returned structure.

Frequently asked questions