Skip to content

Install Walter

Walter On-Prem ships with a dedicated walter-onprem CLI. The public docs site publishes the bootstrap script, the CLI binaries, the bundle archive, and the release manifest operators need for install and upgrade flows. The bootstrap shell script is now intentionally thin: it only downloads the correct walter-onprem binary for the current machine and then execs walter-onprem install ....

Requirements

  • Docker with Compose support (docker compose or docker-compose)
  • A Walter registry username and token, communicated separately
  • A hostname or IP address clients will use to reach Walter

Verify Compose before you start:

docker compose version
# or:
docker-compose version

If docker compose version fails on Debian, Ubuntu, or Raspberry Pi OS, install docker-compose-plugin. If your environment already standardizes on the standalone docker-compose binary, Walter can use that too.

License keys and LLM settings are optional at boot. You can enter them in the browser after Walter starts.

One-command install

For the fastest first boot:

curl -fsSL https://onprem.walterops.com/install/install-walter.sh | bash

The installer:

  1. Downloads the correct walter-onprem binary for the current machine
  2. Resolves the latest stable Walter release from /releases/manifest.v1.json
  3. Downloads the Walter On-Prem bundle into ~/walter-onprem
  4. Verifies checksums before touching the existing install
  5. If ~/walter-onprem already exists, moves it to a timestamped backup before unpacking the new bundle
  6. Restores the prior ~/walter-onprem/.env.deploy into the new bundle directory when present
  7. Prompts for the deployment mode and explains what internal-tls and public-tls mean
  8. Prompts for the host clients will use to reach Walter
  9. For fresh internal-tls installs, asks whether to keep the default published host ports 80/443
  10. Reuses existing Docker auth or prompts for the GHCR username and token Walter provided separately
  11. Writes or updates ~/walter-onprem/.env.deploy
  12. Pulls the Walter image
  13. Starts the Docker Compose stack

A normal reinstall is not a clean wipe. walter-onprem install moves the existing ~/walter-onprem bundle aside to a timestamped backup, restores the previous .env.deploy when present, and leaves Docker named volumes in place. If you need a truly fresh install, remove the Compose volumes too. See Troubleshooting.

When the stack is up, open https://<the host you entered>. After install, ~/walter-onprem/bin/walter-onprem doctor reruns the local preflight and config checks without changing anything.

If you prefer a fully non-interactive install, pass --mode, --host, and either preconfigure Docker auth or pass --registry-username and --registry-token.

The bundle-managed defaults are:

  • internal-tls: publishes Walter on host ports 80 and 443
  • public-tls: requires standard public 80/443 for Let's Encrypt

If you need non-default published ports, use internal-tls and pass --https-port and, if needed, --http-port.

The CLI refuses to refresh a non-empty install directory unless it already looks like a Walter On-Prem install. Use --force only when you are intentionally adopting a custom path and understand that Walter will move the existing directory aside before writing the new bundle.

What the installer asks

With no flags, walter-onprem install asks for the minimum it cannot safely guess:

  • deployment mode: internal-tls for private networks with Walter's generated internal CA, or public-tls for a public DNS hostname with Let's Encrypt
  • the host clients will use to reach Walter
  • for fresh internal-tls installs, whether to keep the default published host ports 80/443
  • the GHCR username and token Walter provided separately, if Docker is not already authenticated

Pressing Enter at the deployment-mode prompt chooses internal-tls.

Useful flags

# Public hostname with automatic Let's Encrypt
curl -fsSL https://onprem.walterops.com/install/install-walter.sh | \
  bash -s -- --mode public-tls --host walter.example.com

# Private TLS with Walter's generated internal CA
curl -fsSL https://onprem.walterops.com/install/install-walter.sh | \
  bash -s -- --mode internal-tls --host 192.168.1.50

Use a hostname or IP address that client machines already resolve. If you use a made-up internal name, you must also provide matching internal DNS or /etc/hosts entries on every client. For small private deployments, using the server's private IP is often the simplest option.

# Private TLS on a non-default published HTTPS port
curl -fsSL https://onprem.walterops.com/install/install-walter.sh | \
  bash -s -- --mode internal-tls --host 192.168.1.50 --https-port 8443

# Pin an exact Walter release
curl -fsSL https://onprem.walterops.com/install/install-walter.sh | \
  bash -s -- --to <supported-release>

# Use an exact image tag instead of the release manifest
curl -fsSL https://onprem.walterops.com/install/install-walter.sh | \
  bash -s -- --image ghcr.io/matchylabs/walter:<supported-release>

# Preseed license and LLM settings
curl -fsSL https://onprem.walterops.com/install/install-walter.sh | \
  bash -s -- \
    --host 192.168.1.50 \
    --license-key "<provided-license-key>" \
    --llm-base-url https://api.openai.com/v1 \
    --llm-api-key "<provided-api-key>"

Manual CLI install

If you prefer not to pipe the bootstrap script into bash, download the binary explicitly:

curl -fsSL https://onprem.walterops.com/downloads/walter-onprem-linux-arm64 -o walter-onprem
curl -fsSL https://onprem.walterops.com/downloads/walter-onprem-linux-arm64.sha256 -o walter-onprem.sha256
sha256sum -c walter-onprem.sha256
# or: shasum -a 256 -c walter-onprem.sha256
chmod +x walter-onprem

./walter-onprem versions
./walter-onprem install

Replace the binary name with the correct platform if you are not on Linux arm64.

Trust the internal CA

internal-tls uses Walter's generated internal certificate authority. That keeps traffic encrypted, but browsers and turf hosts need to trust the generated CA before the experience feels smooth.

Walter's turf bootstrap flow carries that CA forward for the installed agent, so agents can keep verifying wss traffic after the first bootstrap. Browsers still need manual CA trust if you want a warning-free experience.

For a quick first boot, expect your browser to warn about the certificate until that CA is trusted. If you want a clean browser experience without manual trust steps, use public-tls with a real DNS hostname and public 80/443 reachability.

If you run internal-tls on a non-default published HTTPS port, include that port in the browser URL and pass --https-port during install so Walter generates the same origin for turf bootstrap commands.

What happens next

After first boot:

  1. Enter your Walter license key if it was not preseeded
  2. Create your admin account
  3. Enter your LLM provider details if they were not preseeded
  4. Add your first turf from the Walter sidebar