Install the Safeguard CLI on Linux: Desktops, Servers and CI

To install the Safeguard CLI on Linux, run curl -fsSL https://cli.safeguard.sh/install | bash. The script detects x86_64 or arm64, verifies the release checksum and puts safeguard on your PATH. It is one static binary, so the distribution does not matter. Then run safeguard, type /login and scan with /scan ..

This guide covers the full first session on Linux, on a laptop, on a headless server and in a CI pipeline: picking the build, installing and verifying, signing in without a browser, scanning code and container images, approving a first fix, running the assistant in CI, and adding the Linux desktop AppImage.

You also keep the AI you already pay for. Bring the Claude, ChatGPT or Codex plan you already pay for and use it inside the Safeguard CLI. Safeguard adds no extra charge for that usage; your plan's own usage limits and terms still apply. And you can connect Claude or ChatGPT to the Safeguard MCP server to use Safeguard from the chat you already use.

Which Linux machines are supported

The Safeguard CLI ships as a single static binary with no runtime dependencies: no Node, Python or JVM. The support matrix puts it plainly: what matters is the operating system and architecture, not the distribution. Two Linux targets are published, x86_64 (amd64) and arm64. Plan for about 40MB for the binary, plus the scanners it downloads on first use.

Check your architecture with:

uname -m
# x86_64            -> Linux x86_64 (amd64) build
# aarch64 or arm64  -> Linux arm64 build

Here is what the download page lists for Linux, side by side.

So an arm64 server gets the full CLI, while the desktop window is an x86_64 AppImage only. On arm64 desktops, use the CLI, the web interface or the cloud options.

Do the work properly with the Safeguard CLI

The Safeguard CLI scans code, container images and SBOMs on your own machine, sends only the results to the platform, and includes an assistant that can fix what it finds. It writes code as well as scanning. The assistant has tools for your local files and for your Safeguard data, and anything that changes something, such as writing a file, editing code or running a command, asks before it acts.

Step 1: Install

On a workstation or a server, the command is the same:

curl -fsSL https://cli.safeguard.sh/install | bash

The installer fetches the current release for your architecture, checks it against the published checksum file and places safeguard on your PATH. The shell installer fails closed if that checksum file is missing. By default it tries /usr/local/bin and falls back to ~/.local/bin.

The installation docs suggest reading the script before running it, which is a good habit on any server:

curl -fsSL https://cli.safeguard.sh/install -o safeguard-install.sh
less safeguard-install.sh
bash safeguard-install.sh

Two environment variables shape the install:

# Install into a folder you own, and pin a release (recommended for CI and golden images)
curl -fsSL https://cli.safeguard.sh/install | \
  SAFEGUARD_INSTALL_DIR="$HOME/.local/bin" SAFEGUARD_VERSION="pinned-release" bash

Replace pinned-release with a real release name; the docs say the current version is listed in latest.txt on the releases site. SAFEGUARD_SKIP_CHECKSUM=1 exists as an explicit opt-out for cases such as air-gapped mirrors. Leave it unset unless you have a reason and another way to verify the file.

Step 2: Confirm the install

safeguard --version
which -a safeguard

which -a shows every copy on your PATH; the first match wins. If nothing appears, open a new shell. If the script used ~/.local/bin and your shell still cannot find it, add it to your PATH in ~/.bashrc or the profile for your shell:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

safeguard --help lists every command and safeguard scan --help shows one. The docs treat --help as authoritative when it disagrees with the written pages.

Step 3: First run and sign in, with or without a browser

Run safeguard once with no arguments. It opens the interactive terminal and, on first run, downloads the scanner tools (syft, grype and trivy) into a tools folder beside the binary, plus the vulnerability database. safeguard update only refreshes databases for scanners you already have, so this first run matters.

On a desktop, type:

/login

Your browser opens, you approve the session and the terminal picks it up. /whoami shows the account and /logout signs out and takes the runner offline.

On a server reached over SSH there is usually no browser. Use:

safeguard login --no-browser

The CLI prints a URL and a code. Open the URL on your laptop or phone, enter the code and approve. Setting SAFEGUARD_NO_BROWSER stops /login from trying to open a browser at all. The CLI does not read an API key from the environment for interactive sign-in; it uses /login or safeguard login.

Where does the token go? By default it is ~/.scanner/token.json with mode 0600, readable only by you. On a desktop with Secret Service, set SAFEGUARD_CREDENTIAL_STORE=native to keep it in the OS credential store, or auto to use it when available.

Step 4: First scan

From a project folder in the interactive terminal:

/scan .

While you are signed in, a scan from the interactive terminal appears in the platform, and only the SBOM and findings are uploaded. /status shows user, tenant, runner, job counts and approval mode; /jobs shows recent scans.

Without the interactive terminal, safeguard scan builds an SBOM, matches it against vulnerability databases and writes JSON files. One target per run:

safeguard scan --dir .
safeguard scan --repo https://github.com/your-org/your-repo
safeguard scan --image registry.example.com/team/api:1.8
safeguard scan --sbom ./bom.spdx.json

Results go under ./output by default, with vuln.json, license.json, collection.json and more in a folder per scan. Private images take --registry-username and --registry-password; private repos take --git-token. Exit codes report whether the scan ran: 0 ran, 1 failed, 2 results were written but the vulnerability scan did not run. Pass/fail gating on findings happens in the platform through policies and gates.

Linux brings two scan targets worth knowing:

# Podman: start the user socket, then scan running containers
systemctl --user enable --now podman.socket
safeguard podman inventory
safeguard podman scan --running

# Apptainer / Singularity images, without running or mounting them
safeguard sif scan ./tool.sif

Podman results stay on the machine, and sif scan also writes sif-provenance.json. To check SBOMs produced elsewhere, safeguard validate handles CycloneDX, SPDX and VEX:

safeguard validate ./sboms --recursive --strict

Step 5: First fix, with your approval

Ask the assistant in plain language:

how many critical vulns do we have
fix the lodash CVE in this repo

It answers the first from your Safeguard data and works on the second in your local files. When it wants to edit a manifest, update a lockfile or run your package manager, it asks. You approve or decline, and esc interrupts a running task without leaving the terminal. Type @ to attach a file from the folder you started in, and ctrl+j for a new line.

After the change, check it like any other commit: git diff, your test suite, then /scan . again. The same assistant handles ordinary machine work too, with your approval: finding and reading files, editing code and running commands. The docs' own example is "what's the latest file in ~/Downloads". For dependency work from the shell, safeguard fix --help and safeguard review --help describe the commands for fixing vulnerable dependencies and reviewing working-tree changes. If another agent wrote the change, see how to check coding agent changes with the Safeguard CLI.

This demo shows the same idea from the platform side: attach a computer running the Safeguard CLI and a folder, ask for a fix, review the diff and approve the command before it runs.

Click through it at your own pace, or open it full screen.

The demo itself notes that computer work from Search is available and expanding.

Step 6: Use your Claude, ChatGPT or Codex plan

Bring the Claude, ChatGPT or Codex plan you already pay for and use it inside the Safeguard CLI. Safeguard adds no extra charge for that usage; your plan's own usage limits and terms still apply.

/model shows or switches the AI model: with no argument it opens a picker, with a name it switches directly. For connecting a model from your own plan, see the CLI docs and /model. The platform also lets you choose the model per conversation, as this demo shows: choose the model for each conversation; Zero z20 answers with no language model at all by turning the question into a platform query; Griffin, Eagle and Lion are Safeguard's models; a tenant admin chooses which model families people may use; and you can bring your own model on your own provider account and route jobs such as chat or summaries to it.

Click through it at your own pace, or open it full screen.

If you would rather stay in Claude or ChatGPT, connect it to the Safeguard MCP server with OAuth and choose which tools it can use. For how the two assistants differ for coding work, see Claude vs ChatGPT for coding.

Step 7: Pick an approval mode

/permissions sets the mode, shown in the bar below the input:

On a shared server, Ask is the sensible start. Repository settings in .safeguard/settings.json apply only after safeguard trust in that repository and cannot set sign-in, provider or server URLs.

Step 8: Servers, the headless runner and CI

The local runner ships inside the CLI. Once signed in, it polls the platform for scan jobs assigned to the machine, runs them locally and uploads the SBOM and findings, never the source. All traffic is outbound HTTPS opened by the runner; nothing connects in. To run it without the terminal UI on a server:

safeguard runner start --workspace /srv/app
safeguard runner status
safeguard runner stop      # drains in-flight work, then stops

On networks that do not allow held connections, add --poll-wait 0 to poll at a fixed interval set by SAFEGUARD_POLL_INTERVAL (default 10 seconds).

In CI, safeguard exec runs one non-interactive assistant turn and exits:

safeguard exec "summarise the critical findings in this repository" --output-format json

Its default permission mode is strict, denying anything a policy file has not pre-approved, and it needs a git repository unless you pass --skip-git-repo-check. For scan artifacts in a pipeline:

safeguard scan --dir . --output safeguard-results

In a fresh CI container, safeguard scan needs syft and grype on the PATH or in TOOLS_DIR. Pin SAFEGUARD_VERSION, and set SAFEGUARD_INSTALL_DIR to a writable folder. The CI/CD integration docs cover pipeline authentication (a secret key stored as SAFEGUARD_API_KEY) and include GitHub Actions, GitLab and Bitbucket examples. Output is plain text without colour in CI, or whenever NO_COLOR is set or output is piped.

For golden images and managed fleets, SAFEGUARD_DISABLE_SELF_UPDATE=1 turns off binary self-updates and SAFEGUARD_NO_UPDATE_CHECK=1 skips the release check. On offline machines, safeguard update --scanner grype --import followed by the archive path loads a database downloaded elsewhere.

Updating and uninstalling

safeguard self-update updates the binary (--check only checks), and re-running the installer does the same. safeguard update refreshes the vulnerability databases. To remove everything, run safeguard logout --yes, delete the binary, and remove ~/.sg, ~/.scanner and ~/.cli. Platform data is unaffected.

Add the Linux desktop app (AppImage)

The desktop app, version 3.2.2, lets you ask your supply chain anything in plain English in a native window. On Linux it is an AppImage for x86_64 that runs without installing. The download page lists two requirements: 64-bit x86 Linux with FUSE available, and the Safeguard CLI installed and on your PATH. So install the CLI first.

Then:

cd ~/Downloads
sha256sum Safeguard-3.2.2-x86_64.AppImage
# expect 46685975126a0d017e5c6ee0a4ca19c07c04155e0695fd15a70b176544f97000
chmod +x Safeguard-3.2.2-x86_64.AppImage
./Safeguard-3.2.2-x86_64.AppImage

If the AppImage says it needs FUSE, the AppImage project's troubleshooting page has the fix. On Ubuntu 22.04 and newer, install FUSE 2 alongside FUSE 3 with sudo apt install libfuse2; on Ubuntu 24.04 the package is named libfuse2t64. On Arch it is sudo pacman -S fuse2. As a last resort, most AppImages can run with --appimage-extract-and-run, which the AppImage docs describe as expensive.

With the CLI and the desktop app in place, the rest of Safeguard follows you around. Start in the terminal, continue on the desktop, and check findings on your phone with the Android app from Google Play or the iOS app from the App Store. There is a browser extension on the Chrome Web Store (Chrome, Brave, Arc, Vivaldi, Opera and Edge) and on Firefox Add-ons, an IDE extension for VS Code, JetBrains and Open VSX, and a full web interface with nothing to install. If you cannot install anything at all, the Cloud CLI runs the CLI on Safeguard's infrastructure, and the cloud sandbox gives you an isolated tenant against a seeded demo repo, free for seven days with no card.

For more on the assistant side of the CLI, read the Safeguard CLI as an AI assistant on your machine.

Common mistakes on Linux

Looking for a Homebrew formula or container image. The runner docs say there is neither. Use the install script, which verifies the checksum.

Running the AppImage before the CLI. The Linux desktop build needs the CLI on your PATH. Install the CLI, confirm which -a safeguard, then launch the AppImage.

Skipping the first interactive run. "syft binary not found" on a fresh install means the scanners never downloaded. Run safeguard once. In CI, provide syft and grype on the PATH or via TOOLS_DIR.

Scanning an empty dependency tree. Install dependencies first (npm install, pip install -r requirements.txt, go mod download) and keep lockfiles. For "No dependencies found", check pwd, then safeguard scan --dir "$(pwd)". For monorepos that run out of memory, scan each package directory separately.

Turning on transitive resolution by default. --resolve-transitive is off by default because it makes network calls for every dependency. Use it when you need it, not on every run.

Fighting the corporate proxy. Export HTTP_PROXY and HTTPS_PROXY, allow outbound HTTPS on 443, and test with curl -I https://api.safeguard.sh/auth. For a corporate CA, set SSL_CERT_FILE or add the certificate to the system store and run sudo update-ca-certificates on Ubuntu or Debian. Never disable certificate checks.

Writing output where you cannot write. On servers, point results at a folder you own with --output ~/safeguard-results. Logs and notices go to stderr, so redirect stdout alone when you want clean JSON.

Yolo on a shared box. Yolo approves everything. Use Ask on shared servers.

safeguard doctor checks environment, sign-in, tools and policy without changing anything; logs live in ~/.sg/logs/safeguard.log. If you still need help, safeguard support bug "what you ran, what you expected, what happened" opens a ticket.

FAQ

Does the Safeguard CLI work on arm64 Linux?

Yes. The support matrix lists native Linux x86_64 and arm64 builds, and the install script picks the right one. The desktop AppImage is x86_64 only.

Which distributions are supported?

The CLI is a static binary, so the docs say the operating system and architecture matter, not the distribution.

Can I keep using my Claude, ChatGPT or Codex subscription?

Yes. Bring the Claude, ChatGPT or Codex plan you already pay for and use it inside the Safeguard CLI. Safeguard adds no extra charge for that usage; your plan's own usage limits and terms still apply. You can also connect Claude or ChatGPT to the Safeguard MCP server. See the CLI docs or /model for connecting a model.

How do I sign in on a headless server?

Run safeguard login --no-browser, open the printed URL on any device, enter the code and approve.

Does my source code leave the server?

When the local runner runs platform scan jobs, only SBOMs and findings are uploaded; source code stays on the machine. Runner traffic is outbound HTTPS only.

Will the assistant run commands without asking?

In Ask and Auto modes, no: writing files, editing code and running commands ask first under the /permissions mode. Yolo approves everything. In CI, safeguard exec defaults to strict, which denies anything not pre-approved by policy.

Why does the AppImage not start?

Usually FUSE is missing or the CLI is not on your PATH. Install FUSE 2 for your distribution, confirm safeguard --version works, and make the file executable with chmod +x.

Can I use it on an air-gapped machine?

The docs describe safeguard update --scanner grype --import with a database archive downloaded elsewhere, and SAFEGUARD_SKIP_CHECKSUM=1 as an explicit opt-out for cases such as air-gapped mirrors.

Try it yourself

This walkthrough covers installing and starting the CLI: set up the runner on your own machine, pick the platform, start it, approve it with its device code, then use the same CLI to scan from the terminal.

Click through it at your own pace, or open it full screen.

Ready for a real machine? Get the CLI and the AppImage from safeguard.sh/download, and keep the CLI docs close for your first session.

Quick check

Sources

• Safeguard CLI documentation
• Safeguard CLI installation
• Safeguard CLI interactive terminal
• Safeguard CLI slash commands
• Safeguard CLI usage
• Safeguard CLI system configuration
• Safeguard CLI troubleshooting
• Safeguard CLI support matrix
• Safeguard local runner
• Safeguard CI/CD integration
• Safeguard downloads
• AppImage documentation: FUSE troubleshooting

Last reviewed: 21 October 2026.