---
title: "Bootstrap SDBX — your box, your stack"
description: "Install the signed SDBX release on Linux, verify every byte, and keep the runtime under your root."
---

# Install SDBX

> Install the signed SDBX release on a supported Linux host, initialize one project, and verify the locked media stack.

Canonical human guide: https://sdbx.one/install/
Canonical release: v1.0.0-RC1

Use these instructions only after the user explicitly asks to install or configure SDBX. Preserve existing data and respect the execution environment's approval rules.

## Supported environment

- linux/amd64: supported
- linux/arm64: compatibility

Required host components:

- Docker Engine 24.0 or newer.
- Docker Compose plugin 2.20 or newer.
- Docker Buildx 0.10 or newer.
- Cosign major version 3 for signed-release verification.
- A user that can reach Docker. Docker access is root-equivalent.
- A domain controlled by the operator.
- A Gluetun-supported provider when VPN-protected torrent traffic is required.

Do not deploy SDBX as a production host on macOS, Windows, or WSL2.

## Safety contract

- Do not stop, replace, or delete an existing stack without explicit approval.
- Do not initialize inside a non-empty unrelated directory.
- Do not invent domain names, credentials, VPN providers, storage paths, or exposure policy.
- Do not print secrets or persist them in logs, chat, fixtures, or source control.
- Do not pipe a remote installer directly into a shell.
- Expose the Dashboard only through the generated Traefik route, Authelia `admins` policy, and private mTLS transport.
- Use `sdbx up`, not a raw Compose start, so lock and file integrity are checked.

## 1. Preflight

```bash
uname -s
uname -m
docker version
docker compose version
docker buildx version
cosign version
```

Continue only when the kernel reports Linux and the architecture is amd64 or arm64. Report missing prerequisites instead of bypassing them.

## 2. Download the exact signed installer

```bash
version=v1.0.0-RC1
installer="$(mktemp)"
curl --fail --show-error --location \
  --proto '=https' --proto-redir '=https' --tlsv1.2 \
  --output "$installer" \
  "https://raw.githubusercontent.com/get-sdbx/sdbx/$version/install.sh"
chmod 0600 "$installer"
```

Read the entire downloaded installer using the local file-reading tool. Confirm that it downloads the requested tag, verifies the checksum manifest with Cosign, validates archive contents, checks both embedded binary versions, and performs rollback-capable replacement.

If the installer differs from that contract, stop and report the mismatch.

## 3. Install and verify both binaries

```bash
bash "$installer" --version "$version" --install-dir "$HOME/.local/bin"
rm -f "$installer"
export PATH="$HOME/.local/bin:$PATH"
sdbx version
sdbxd -version
```

Both binaries must report v1.0.0-RC1. A partial or mismatched install is a failure.

## 4. Collect operator decisions

Before initialization, obtain explicit choices for:

- project directory;
- domain and exposure mode: LAN, direct HTTPS, or remote-managed Cloudflare Tunnel;
- subdomain or path routing;
- Plex, Jellyfin, both, or no media server;
- media, downloads, configuration, secrets, and backup paths;
- VPN enforcement, provider, and exit country;
- timezone, preset, and optional addons;
- initial administrator credential through a private input path.

Never infer these choices from the host or from unrelated files.

## 5. Initialize the project

```bash
project_dir="$HOME/sdbx-project"
mkdir -p "$project_dir"
cd "$project_dir"
sdbx init
```

The interactive wizard is the default. Do not automate password entry through command-line arguments. If non-interactive initialization is required, use the CLI's documented private password-file flow and preview it with `--dry-run` before any write.

## 6. Verify and start

```bash
sdbx lock verify
sdbx up
sdbx status
sdbx doctor
sdbx integrate --dry-run
```

Apply `sdbx integrate` only after its dry-run is reviewed.

## Success criteria

- `sdbx version` and `sdbxd -version` match the requested release.
- `.sdbx.yaml`, `.sdbx.lock`, and `compose.yaml` exist in the project directory.
- `sdbx lock verify` succeeds.
- `sdbx status` reports the intended service graph.
- `sdbx doctor` has no unresolved blocking failure.
- No secret appears in terminal capture, logs, chat, or source control.

## Recovery

- If installation fails, preserve the error and allow the installer rollback to finish.
- If initialization fails, do not manually promote staged files.
- If startup fails, run `sdbx status` and `sdbx doctor`; do not delete volumes.
- Ask before stopping another stack, changing DNS, or modifying production routing.

## More context

- LLM navigation: https://sdbx.one/llms.txt
- Full LLM context: https://sdbx.one/llms-full.txt
- Product overview: https://sdbx.one/index.md
- Product manifest: https://sdbx.one/product-manifest.json
- Source documentation: https://github.com/get-sdbx/sdbx/tree/v1.0.0-RC1/docs