> For the complete documentation index, see [llms.txt](https://docs.gotempest.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gotempest.app/self-hosting-and-web-mode/self-host-tempest-desktop.md).

# Deploy Tempest Desktop with Docker Compose

Run Tempest Desktop's browser UI and SSH backend on your own server with Docker Compose.

## Install with an AI assistant

Copy this prompt into an AI assistant that can access your server. It links to this guide so the assistant can follow the complete deployment instructions.

```
Help me deploy optional Tempest Desktop Web Mode on my server. Read and follow this guide first:
https://docs.gotempest.app/guidelines/self-host-tempest-desktop.md

Check the host's Linux amd64 architecture, SSE4.2 support, kernel and Docker Compose availability. Ask for any missing deployment details: target host, domain or SSH-tunnel access, and Tempest Cloud or a self-hosted account server. Create the Compose file from the inline YAML in this guide, configure persistent storage and the chosen account endpoint, then start and verify the deployment. Configure HTTPS and WebSocket forwarding if I provide a domain. This component is optional; do not deploy Web Services unless I request it. Preserve existing data, keep secrets out of chat and report the access URL and verification results.
```

**Tempest Desktop in Web Mode** is an optional deployment that provides the same Tempest experience as the desktop app, but runs in your browser without a local installation. You can use the native desktop or mobile apps with your self-hosted Web Services without deploying this container.

The `tempest-desktop` container serves the browser UI and runs the backend. SSH connections run from the container, so the Docker host must be able to reach your target servers.

There are two separate services you can self-host:

| Component                    | Image                                                                           | Purpose                                                                     |
| ---------------------------- | ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
| Tempest Desktop (this guide) | `tempestterm/tempest-desktop`                                                   | Browser UI, WebSocket backend, SSH connections and server-side vault access |
| Tempest Web Services         | `tempestterm/tempest-web-services-oss` or `tempestterm/tempest-web-services-ee` | Accounts, OAuth and encrypted vault synchronization                         |

Deploy Desktop on its own to connect to Tempest Cloud, or point it at your own [Web Services deployment](https://docs.gotempest.app/self-hosting-and-web-mode/self-host-tempest-server-docker-compose.md). Desktop does not require its own Postgres, Redis or CouchDB containers.

## Requirements

* Docker Engine with the Docker Compose plugin.
* **Linux amd64 (x86-64).** The published Desktop image is currently built for `linux/amd64`; there is no native ARM64 image in this pipeline.
* **A CPU with SSE4.2 support.**
* Linux kernel 5.1 or newer; 5.6 or newer is recommended by Bun.
* Network access from the container to your SSH targets, account server and its CouchDB endpoint.

On the Linux Docker host (inside the VM when Docker runs in a VM), check:

```sh
uname -m
uname -r
lscpu | grep -i sse4_2
```

The architecture should be `x86_64`, and the CPU flags must include `sse4_2`. A hypervisor must expose this feature to the guest. An `Illegal instruction` error at startup can indicate missing CPU features.

These requirements follow the image's pinned Bun 1.3.9 runtime: the official [slim Dockerfile](https://github.com/oven-sh/bun/blob/bun-v1.3.9/dockerhub/debian-slim/Dockerfile) selects `x64-baseline`, whose minimum is SSE4.2 in the [versioned Bun requirements](https://github.com/oven-sh/bun/blob/bun-v1.3.9/docs/installation.mdx#cpu-requirements).

## 1. Save the Compose file

Create a deployment directory:

```sh
mkdir -p ~/tempest-desktop
cd ~/tempest-desktop
```

Save the following configuration as `docker-compose.desktop.yml` in this directory. It runs a single Desktop container, persists its data in a named volume, and binds port 8787 to localhost for access through a reverse proxy or SSH tunnel. Run the remaining commands from this directory.

{% code title="docker-compose.desktop.yml" %}

```yaml
services:
  desktop:
    image: ${TEMPEST_DESKTOP_IMAGE:-tempestterm/tempest-desktop:latest}
    platform: linux/amd64
    init: true
    restart: unless-stopped
    ports:
      - "127.0.0.1:8787:8787"
    environment:
      TEMPEST_WS_HOST: 0.0.0.0
      TEMPEST_WS_PORT: "8787"
      TEMPEST_DATA_DIR: /data
      # Optional: default account/sync server. Omit to use Tempest Cloud.
      # TEMPEST_API: https://tempest.example.com
      # Optional: restrict which account servers users may connect to.
      # TEMPEST_WEB_ALLOWED_SERVERS: https://tempest.example.com
    volumes:
      - desktop-data:/data
    healthcheck:
      test: ["CMD", "bun", "-e", "const r = await fetch('http://127.0.0.1:8787/'); process.exit(r.ok ? 0 : 1)"]
      interval: 30s
      timeout: 10s
      start_period: 30s
      retries: 3

volumes:
  desktop-data:
```

{% endcode %}

The image is published on Docker Hub as `tempestterm/tempest-desktop`. For a fixed deployment, replace `latest` with a published tag or pin an image digest.

## 2. Start Desktop

```sh
docker compose -f docker-compose.desktop.yml pull
docker compose -f docker-compose.desktop.yml up -d
docker compose -f docker-compose.desktop.yml ps
docker compose -f docker-compose.desktop.yml logs -f desktop
```

Check the HTTP endpoint on the Docker host:

```sh
curl -I http://127.0.0.1:8787/
```

Open `http://localhost:8787` if Docker runs locally. For a remote host, forward the port from your workstation:

```sh
ssh -N -L 8787:127.0.0.1:8787 user@docker-host
```

Then open `http://localhost:8787` in your workstation's browser and sign in.

## 3. Connect your own account server (optional)

To use your own Web Services deployment, uncomment `TEMPEST_API` and set it to that server's externally reachable HTTPS origin. You can also select **Self-hosted server** on the welcome screen. This is the account server address, not the Desktop container's address.

Set `TEMPEST_WEB_ALLOWED_SERVERS` to a comma-separated list of account server origins if you want to restrict which servers this Desktop instance can use. `TEMPEST_API` alone only sets the default; it does not enforce an allowlist.

Apply configuration changes:

```sh
docker compose -f docker-compose.desktop.yml up -d
```

The account server must have the Desktop OAuth application registered; see step 6 of the [Web Services deployment guide](https://docs.gotempest.app/self-hosting-and-web-mode/self-host-tempest-server-docker-compose.md#6-register-the-oauth-clients).

## 4. Serve it over HTTPS

For access through a domain, put an HTTPS reverse proxy in front of port 8787. Both the page and WebSocket connection use this port. For example, Caddy running on the Docker host can use:

```caddyfile
desktop.example.com {
    reverse_proxy 127.0.0.1:8787
}
```

Point the domain at the host and make ports 80 and 443 reachable for Caddy's certificate provisioning. Caddy forwards WebSocket upgrades automatically. If your proxy runs in another container, join it to the Desktop network and proxy to `desktop:8787` instead of its own localhost.

For nginx, enable HTTP/1.1 WebSocket upgrades and forward `Host`, `X-Forwarded-Proto` and `X-Forwarded-For`. When serving HTTPS, the WebSocket connection must use `wss://`. By default, the UI uses the page's host and port; set `TEMPEST_WS_URL` only if your WebSocket endpoint is different.

If you configure `TEMPEST_WEB_TRUSTED_PROXIES`, include only your proxy's actual address or CIDR range. This lets browser-session rate limiting use the forwarded client address.

## Data and upgrades

`TEMPEST_DATA_DIR=/data` keeps browser sessions and the backend vault under the `desktop-data` volume. The web vault runs on this server beside its SSH sessions: treat the host and backups as trusted infrastructure. This differs from native Desktop, where the vault is on your own device. Browser cookies identify browser sessions; keep the volume and your browser session when restarting the service.

Back up the volume with the container stopped for a consistent snapshot. Do not run `docker compose down -v` unless you intend to delete this data.

Upgrade using the same image source and tag configuration:

```sh
docker compose -f docker-compose.desktop.yml pull
docker compose -f docker-compose.desktop.yml up -d
```

Container restarts disconnect active SSH sessions. After upgrading, verify that the page loads, account sign-in works, and a test SSH connection succeeds.
