Install Qwest

Do this on the server, once Docker is installed (VPS, Linux, Windows or macOS).

1. Make a folder for Qwest

Linux / macOS

mkdir ~/qwest && cd ~/qwest

Windows

mkdir ~\qwest; cd ~\qwest

Run every command below from this folder.

2. Download Qwest

1. Sign in to your account with your license key.

2. Download the latest release. It’s one file, like qwest-1.0.0.tar.

3. Put it in the qwest folder on the server.

   • The server is your own PC: move the file into the folder.

   • The server is a VPS: copy it over from your computer (run this on your computer, not the server):

     scp qwest-1.0.0.tar root@YOUR_SERVER_IP:~/qwest/

     Or, on the server, download it directly with the link from your account page (links work for one hour):

     curl -fLo qwest-1.0.0.tar "PASTE_THE_DOWNLOAD_LINK"

4. Load it into Docker:

   docker load -i qwest-1.0.0.tar

   It ends with Loaded image: qwest:1.0.0. Note the version.

3. Get the two setup files

Linux / macOS

curl -fsSLO https://docs.qwest.dev/install/compose.yml
curl -fsSL -o .env https://docs.qwest.dev/install/env.example

Windows

curl.exe -fsSLO https://docs.qwest.dev/install/compose.yml
curl.exe -fsSL -o .env https://docs.qwest.dev/install/env.example

• compose.yml tells Docker to run Qwest and its database.
• .env holds your settings.

4. Make your secrets

Qwest needs four long random passwords. This prints them for you (use your version number):

docker run --rm qwest:1.0.0 bun -e "const c=require('crypto');for(const k of ['BETTER_AUTH_SECRET','COLLAB_SECRET','SECRETS_KEY','POSTGRES_PASSWORD'])console.log(k+'='+c.randomBytes(32).toString('hex'))"

Copy the four lines it prints.

5. Fill in .env

Open it:

Linux / macOS

nano .env

Save with CtrlO, Enter, then quit with CtrlX. (On a Mac with a screen, open -e .env works too.)

Windows

notepad .env

Change these lines:

Line	Set it to
QWEST_VERSION	The version you loaded, like 1.0.0.
BETTER_AUTH_SECRET, COLLAB_SECRET, SECRETS_KEY, POSTGRES_PASSWORD	The four lines you copied (replace the empty ones).
BETTER_AUTH_URL	The address your team will open. See below.
QWEST_PORT	See below. Remove the # in front of it to use it.

Which address? Pick how your team will reach Qwest (you can change it later):

How	BETTER_AUTH_URL	QWEST_PORT
Only on the studio’s network (old PC)	http://192.168.1.42:8080 (the PC’s address)	leave it out
Privately from anywhere, with Tailscale	https://qwest.your-tailnet.ts.net (you’ll get it on that page)	127.0.0.1:8080
Publicly, with your own domain	https://qwest.yourstudio.com	127.0.0.1:8080

127.0.0.1:8080 keeps Qwest’s port closed to the outside: only Tailscale or your web server on the same machine can reach it.

Keep .env safe

Back it up somewhere private, like a password manager. Losing BETTER_AUTH_SECRET signs everyone out, and losing SECRETS_KEY loses the stored AI keys.

6. Start Qwest

docker compose up -d

Watch it start (press CtrlC to stop watching. Qwest keeps running):

docker compose logs -f qwest

It’s ready when it prints database is up to date and stops printing errors.

7. Make the first account

If you chose a Tailscale or domain address, finish that page first: Tailscale or domain.

1. Open exactly the address you put in BETTER_AUTH_URL. Another address for the same server (like its IP) won’t let you sign in.
2. Click Sign up. This first account is the instance admin.
3. Activate your license.
4. Make a workspace and invite your team.

Useful commands

Run them from the qwest folder.

To…	Run
See if it’s running	docker compose ps
See its logs	docker compose logs -f qwest
Restart it (after changing .env)	docker compose up -d
Stop it	docker compose down (your data stays)

Qwest restarts by itself if it crashes or the server reboots.