Quickstart

What this page covers

Deploy the latest release (from 1.14.0) on Linux x86_64 or aarch64, sign in, create an asset, and open a managed connection. See Release package and offline installation for full package and offline steps.

What you need

• A Linux host with Docker and Docker Compose, plus release files for its architecture.
• The guide needs curl (or wget) and sha256sum (or shasum); manual package signature verification also needs cosign.
• Persistent storage for DATA_PATH and an initial administrator password.
• At least 40 GB of free disk, of which about 10 GB is the Docker data folder (the images of the current and the previous version, plus room for an upgrade). Recordings and backups come on top of that.

How to set it up

1. Download and install

From 1.14.0, the release download guide gets the latest package and SHA256SUMS on a Linux host, checks the package SHA-256 before unpacking, and opens the custodexa.sh menu. Choose Install there.

set -o pipefail
curl -fsSL https://github.com/custodexa/custodexa/releases/latest/download/get-custodexa.sh | sudo bash

To use another deployment folder, add --dir:

set -o pipefail
curl -fsSL https://github.com/custodexa/custodexa/releases/latest/download/get-custodexa.sh | sudo bash -s -- --dir /srv/custodexa

Without --version the guide installs the latest release. To install a specific release, add --version <version> after --.

To inspect the guide first, download and run the same file:

curl -fsSLO https://github.com/custodexa/custodexa/releases/latest/download/get-custodexa.sh
sudo bash get-custodexa.sh

In Bash or Zsh, set -o pipefail makes a failed guide download return a nonzero status for the whole pipeline. For the download-then-run form, run the second command only after the download succeeds. Setting CX_GET_RELEASE_BASE to another release endpoint trusts that source for both the package and SHA256SUMS; matching hashes alone do not verify the publisher.

The guide checks SHA-256 only. Release package and offline installation gives the manual package signature check and full download and unpack steps; custodexa.sh handles image signatures. An existing deployment is handed to its own custodexa.sh without overwriting files. With no interactive terminal, pass a child command such as install --yes after --.

After installation, check status:

sudo /opt/custodexa/custodexa.sh status

The installer checks the environment, prepares .env, obtains and verifies images, starts services, and waits for health checks. Image sources are local images, offline bundles, GHCR, Docker Hub, and source builds, in that order. Run custodexa.sh without arguments for the menu, which on an installed deployment offers status, start, stop, upgrade, backup, restore, and image loading. Use --help for commands, or --lang zh-TW|en|ja to select its language. In an offline environment, run custodexa.sh load with the architecture-specific image bundle first.

For a source deployment, run bash scripts/quickstart.sh --up in the source tree.

Use custodexa.sh for Linux package installation and upgrades. scripts/quickstart.sh is for developers and macOS or Windows evaluation. --images-from source builds the package backend and frontend locally; upstream images and build dependencies must still be obtained. Long steps print progress before they run and a result when they finish.

2. First login and asset

Use the URL and initial password shown by the installer to sign in as admin, then change the password. Complete initial unsealing as described in Key management. In Assets, create an asset with its name, protocol, host, port, and connection account. Credentials can be asset-specific or selected from the credential library. To create many at once, use Bulk add; see SSH terminal.

3. Open a connection

Select Connect on an asset and complete its policy requirements. Session details show the recording and command list. Use Command audit to search across sessions.

What auditors can see

Login results, session times, asset and account snapshots, recordings, and reconstructable commands are available for review. The recording is the source of truth for text sessions, and input without echo leaves no command-text record. The query console’s structured statement record is the source of truth for that query.