Install with an AI agent

If you already use an AI coding agent (Claude Code, Codex, Gemini CLI, …), it can do the installation for you. Copy the prompt below into the agent, run the agent on your server or give it SSH access the way you normally would, and tell it:

• which server to use and where to install Sublarr,
• where your media library lives, and whether Sonarr/Radarr run on the same host (and under which path they see the media),
• whether you open Sublarr only on your network or through a public domain.

The prompt does not contain installation steps of its own. It sends the agent to the current pages of this documentation first, so it stays correct when Sublarr changes.

What the agent does — and what it leaves to you

• It checks the host, installs Docker if it is missing, writes a docker-compose.yml and a .env file, starts the container and verifies that /api/v1/health reports healthy.
• It keeps any existing installation and its data. It is told never to delete volumes or the config directory.
• It does not open the first-run page or the setup wizard. You set the password there yourself, so it never passes through the agent or its chat log.
• It does not print secret values. A generated API key stays in the .env file (mode 600); the agent only tells you where that file is.

Read what the agent runs

An agent with SSH access can change anything on that host. Use one you trust, keep its permission prompts on, and read the commands it proposes — especially on a server that already runs other services.

The prompt

Install a self-hosted Sublarr instance on my server using Docker Compose.

Read the current official documentation before making changes:
- https://sublarr.de/docs/getting-started/installation/
- https://sublarr.de/docs/getting-started/environment-variables/
- https://sublarr.de/docs/troubleshooting/reverse-proxy/

1. Establish the target server, the installation directory, the path of my
   media library, and the intended access URL from the context I provide.
   Ask for any missing details, in particular whether Sonarr/Radarr run on
   this host and under which path they see the media. Check the OS, CPU
   architecture (amd64 and arm64 are supported), memory, free disk space,
   Docker, Docker Compose and whether port 5765 is free. Install missing
   prerequisites using the official Docker instructions for that OS.

2. Check for an existing Sublarr installation (a container or compose
   project named sublarr, an existing config directory) before creating or
   changing anything. Preserve existing configuration and data. For an
   upgrade, back up the config directory first. Never delete volumes or the
   config directory, and never run `docker compose down -v`,
   `docker volume rm` or `docker system prune` to fix an installation.

3. Write a docker-compose.yml from the Compose example in the installation
   guide, using the image `ghcr.io/abrechen2/sublarr:latest`.
   - Put the config directory on local SSD storage, not on an NFS/SMB share
     or an SD card (the guide explains why).
   - Mount the media library at `/media`. If Sonarr/Radarr see it under a
     different path, note the pair for Path Mapping in the setup wizard
     instead of changing the mount.
   - Set PUID/PGID to the user and group that own the media files.

4. Only set the bootstrap variables from the environment-variables page.
   Provider keys, Sonarr/Radarr and translation are configured later in the
   web UI; do not put them in the environment.
   - Leave `SUBLARR_CORS_ORIGINS` unset: since 1.17.4 the live connection of
     the web UI accepts the address it is opened on. Only set it to add other
     origins. (On 1.17.3 or older, set it to the exact origin I will open
     Sublarr on, for example `http://192.168.1.20:5765`.)
   - If the instance will be reachable from the internet, also generate a
     long random `SUBLARR_API_KEY`.
   Keep secrets in a `.env` file with mode 600 next to the compose file, and
   never print a secret value in the chat.

5. For a public domain, configure HTTPS following the reverse-proxy guide,
   including WebSocket forwarding for `/socket.io/`. Do not expose any other
   port.

6. Validate with `docker compose config --quiet`, then run
   `docker compose pull` and `docker compose up -d`.

7. Check `docker compose ps` and the container logs, then
   `curl http://<host>:5765/api/v1/health` (expect `"status":"healthy"`) and
   the web UI at the intended URL. Diagnose and fix startup errors before
   declaring success. State explicitly if a check could not be completed.

8. Do not complete the first-run page or the setup wizard yourself; that is
   where I choose the password. Report: the installation directory, the
   access URL, service status, any Path Mapping pair I need, the location of
   the `.env` file (not its contents), and the commands to stop, start,
   update (`docker compose pull && docker compose up -d`) and back up this
   instance. Remind me to set a password on the first page before the
   instance is reachable from outside my network.

After the agent is done

Open the URL it reports, set a password on the Welcome to Sublarr page, and continue with Your first 10 minutes.