Install CrateSphere on a Windows PC

This guide sets up the portal on one Windows computer. You do not need to know anything about servers, Linux or networking. Every step is a thing you click or one line you copy.

Read the next section before you start. It decides whether this is the right guide for you at all.

Is this the right guide?

The Windows installation runs the portal for the computer it is installed on. When it is running, you open it in a browser on that same PC at http://127.0.0.1:3001.

Out of the box, other people cannot reach it — not your phone, not a laptop in the same room. The portal listens only to the PC it runs on, so nothing crosses your network unencrypted.

You can publish it to the internet, for free, using a Cloudflare Tunnel. That gives your portal a proper https:// address that artists can use from anywhere, without opening any ports on your router. Part 2 covers it fully.

Note what a tunnel does and does not change. It does not make the portal visible on your local network — there is no 192.168.x.x address to hand out. It gives you one public web address, and everyone including you uses that.

So:

Two honest caveats before you pick Part 2 over a cloud server. Your home connection becomes the portal's server, so every artist downloading a 90 MB master is using your upload speed; and the portal is online only while that PC is switched on and awake. A cloud server costs a few pounds a month and removes both. The numbers are in Part 2 so you can judge for yourself.

Part 1: The portal on your PC

What you need

A Windows 10 or Windows 11 PC that you can leave running while you use the portal.

About 20 GB of free disk space to begin with, plus room for your music. The portal keeps your catalogue on this PC's disk unless you tell it otherwise, so if your catalogue is 80 GB you need 80 GB free for it.

Node.js version 20.6 or newer. This is the engine the portal runs on. If you do not have it:

1. Go to <https://nodejs.org>.
2. Download the version marked LTS (it means "long-term support" — the stable one).
3. Run the installer and accept every default. Do not change any options.
4. Restart your PC when it finishes.

You do not need to understand Node.js. You are installing it the same way you would install a printer driver.

The CrateSphere folder on your PC. If you are reading this file, you already have it.

Step 1: Start the portal

Open the CrateSphere folder in File Explorer. Find the file named:

start-portal.cmd

Double-click it. A black window opens with white text scrolling past. That window is the portal. Leave it open — closing it stops the portal.

The first time you run it, this takes five to fifteen minutes. It is downloading the pieces it needs and building the portal. You will see a lot of text. That is normal, including lines that look like warnings.

Later runs take under a minute.

You will know it is ready when the black window shows:

Starting fresh CrateSphere at http://127.0.0.1:3001

If the window closes instantly

It found a problem and told you what it was, too quickly to read. To see the message, open the folder, hold Shift, right-click in the empty space, choose Open PowerShell window here, and type:

.\start-portal.cmd

Now the message stays on screen. The most common causes are Node.js not being installed, or the PC needing the restart after installing it.

If it says port 3001 is already in use

The portal is already running in another window, or something else on your PC has taken that port. The message names the program holding it. Close that program, or close the other portal window, then double-click start-portal.cmd again.

Step 2: Create your administrator account

Open a web browser on the same PC and go to:

http://127.0.0.1:3001

You will see Initial administrator. This screen appears only once, before any account exists.

Fill in:

• Name — your name.
• Email — your email address. This is what you will sign in with.
• Password — at least 12 characters. Use a password manager.
• Bootstrap token — already filled in for you. Do not change it. It is a one-time key the portal generated so that only someone sitting at this PC can create the first account.
• Tick the box to accept the Terms of Use.

Click Create administrator.

You are now the administrator. The screen you just used is permanently closed — visiting that address again shows a normal sign-in page.

Moving an existing portal here? There is a link on this screen reading "Moving an existing portal? Restore from a backup instead". Use that rather than creating a new administrator. See Move to a cloud server, which works in either direction.

Step 3: Find your music

Your catalogue lives here:

C:\Users\<your name>\AppData\Local\CrateSphere\storage

AppData is hidden by default. The quickest way to open it is to press Windows+R, paste %LOCALAPPDATA%\CrateSphere and press Enter.

Inside storage, the portal uses three kinds of folder:

Submissions and Rejected are made automatically the first time they are needed. You never create them by hand, and the names are reserved — you cannot use them for a release.

To bring in an existing catalogue, copy your release folders into storage, then in the portal go to Settings → Storage and refresh. Keep folder names exactly as they are; the portal identifies music by its folder path.

Step 4: Back up

Do this now, before you have anything to lose, so you know it works.

In the portal, go to Settings → Maintenance and click Create portal-state backup.

This writes a .zip file to:

%LOCALAPPDATA%\CrateSphere\backups

What the backup contains: every account, project, track, comment, submission and setting, plus your encrypted service passwords and the key that unlocks them.

What it does not contain: your actual music files. A backup of an 80 GB catalogue would be 80 GB. Your music is already sitting in the storage folder — copy that folder to an external drive on your own schedule.

Treat the .zip as a secret. Anyone holding it holds your stored service passwords. Keep it somewhere private, not in a shared folder.

To restore one later, go to Settings → Maintenance, pick a backup from the list, type your password and the confirmation phrase. The portal stops, restores, and starts again by itself. It only lists backups already in that backups folder — if you are restoring from another PC, copy the .zip in there first.

Everyday use

Starting: double-click start-portal.cmd. Wait for the address to appear, then open http://127.0.0.1:3001.

Stopping: close the black window.

After a CrateSphere update: double-click start-portal.cmd as usual. It rebuilds automatically, which makes that run slower. Your data is untouched — it lives outside the CrateSphere folder, in AppData, precisely so an update cannot overwrite it.

Where everything lives:

You can delete and re-download the program folder without losing data.

When something goes wrong

Part 2: Let other people in

This publishes the portal on your PC to a real web address like https://portal.glitchpulser.com, using a free Cloudflare Tunnel. No router settings, no firewall rules, no fixed IP address needed.

Allow about an hour.

Before you decide

Your upload speed is the portal's speed. Home connections are far faster down than up, and an artist downloading a 90 MB master is limited by your upload:

That is one person at a time — three at once each get a third. For occasional use 20 Mbit/s upload is a workable floor; for several people aim for 50 Mbit/s or more. Check yours at <https://www.speedtest.net> and read the upload number, not the download one.

The portal is online only while the PC is. Sleep, a restart, Windows Update or a power cut takes it offline. Set the PC to never sleep.

Sustained uploads may count against a data cap and will slow everything else in the house.

None of these apply to a cloud server, which costs about €5.40/month. If you start here and change your mind, Move to a cloud server carries everything across.

What changes

Once the portal has a public address, it is no longer a private local installation, and it switches to stricter rules to match:

• Your catalogue and your encrypted passwords must live in commissioned locations you choose deliberately, rather than in default folders.
• The setup key stops being pre-filled in the browser, because the portal will not print a secret into a public web page.
• You stop using `start-portal.cmd`. That launcher has a fixed loopback address built in and refuses to start with any other, by design. A different launcher takes over.

You need a domain name (like glitchpulser.com) with its DNS managed by Cloudflare. Moving a domain's nameservers to Cloudflare is free and their dashboard walks you through it.

Step 1: Stop the portal

Close the black window if it is open. Nothing below will work while the old launcher is running.

Step 2: Choose where your catalogue lives

Open PowerShell in the CrateSphere folder (hold Shift, right-click empty space, Open PowerShell window here).

If your music is in a normal folder, or a synced folder like Proton Drive or Dropbox, point at it:

.\scripts\commission-portal-storage.ps1 -Action Storage -Arrangement SyncedFolder -Root "C:\Users\nickm\Proton Drive\My files\Glitchpulser" -ConfirmServicesStopped SERVICES_STOPPED

In plain English: record that this exact folder is the catalogue, and check it is a safe place to keep one. Replace the path with yours.

If you would rather keep your music in cloud object storage, use -Arrangement ObjectStorage and supply -Endpoint, -Bucket and -CredentialsPath. The cloud server guide explains how to create those values in Cloudflare R2.

Step 3: Protect your saved passwords

.\scripts\commission-portal-credential-vault.ps1 -ConfirmServicesStopped SERVICES_STOPPED

In plain English: create the locked safe that holds your email and service passwords, and generate the key that opens it, keeping the key somewhere separate from the safe.

Back that key up separately, and never store it beside a portal backup. Losing it means re-entering every stored service password.

Step 4: Claim your web address

.\scripts\set-public-origin.ps1 -Mode Stage -NewOrigin https://portal.glitchpulser.com
.\scripts\set-public-origin.ps1 -Mode Activate

In plain English: prepare the new public address, then make it live. Two steps so a typo can be cancelled before it takes effect.

It must start with https:// and have nothing after the domain. Check what is recorded:

.\scripts\set-public-origin.ps1 -Mode Status

Step 5: Install Cloudflare Tunnel

Download cloudflared for Windows from <https://github.com/cloudflare/cloudflared/releases> — the file named cloudflared-windows-amd64.exe.

Rename it to cloudflared.exe and put it in a simple folder such as C:\cloudflared.

Then, in PowerShell:

C:\cloudflared\cloudflared.exe tunnel login

In plain English: sign in to Cloudflare. Your browser opens; sign in and choose your domain.

C:\cloudflared\cloudflared.exe tunnel create cratesphere

In plain English: create the tunnel. It prints an ID like 6ff42ae2-765d-4adf-8d05-196c6c9b67eb. Copy that ID.

Step 6: Tell the tunnel where to send traffic

Create a file at C:\Users\<your name>\.cloudflared\config.yml. In PowerShell:

notepad "$env:USERPROFILE\.cloudflared\config.yml"

Notepad offers to create it. Say yes, then type this, replacing both YOUR-TUNNEL-ID values and the hostname:

tunnel: YOUR-TUNNEL-ID
credentials-file: C:\Users\nickm\.cloudflared\YOUR-TUNNEL-ID.json

ingress:
  - hostname: portal.glitchpulser.com
    service: http://127.0.0.1:3000
  - service: http_status:404

Keep the indentation exactly as shown. The last line is required by Cloudflare even though it looks odd.

Port 3000, not 3001. The tunnelled launcher uses 3000. The 3001 from Part 1 belongs to start-portal.cmd, which you are no longer using.

Save and close Notepad, then point your address at the tunnel:

C:\cloudflared\cloudflared.exe tunnel route dns YOUR-TUNNEL-ID portal.glitchpulser.com

In plain English: tell Cloudflare this web address should reach this tunnel. This creates the DNS record for you — do not add one by hand.

Make it start automatically with Windows. Open PowerShell as Administrator (right-click, Run as administrator):

C:\cloudflared\cloudflared.exe service install

In plain English: run the tunnel as a background Windows service so it comes back after a restart without you logging in.

Step 7: Start the portal

Back in a normal PowerShell window, in the CrateSphere folder:

.\scripts\portal-beta-supervisor.ps1 -UseCommissionedAdapters

In plain English: start the portal using the catalogue, safe and web address you just commissioned, and keep watching it — if it stops responding, restart it automatically.

Leave this window open; it is the portal. The first start rebuilds and takes several minutes.

Then open https://portal.glitchpulser.com in a browser.

Step 8: Create your administrator account

If this is a fresh installation you will see Initial administrator, with the Bootstrap token box empty. That is correct: on a public address the portal will not print its own setup key into a web page.

Open this file in Notepad and copy the contents:

%LOCALAPPDATA%\CrateSphere\runtime\bootstrap-admin-token.txt

Paste it into the box, fill in your name, email and a password of at least 12 characters, accept the Terms, and click Create administrator.

If you already created an administrator in Part 1, that account still works — sign in with it as normal.

Everyday use with a tunnel

Starting: open PowerShell in the CrateSphere folder and run .\scripts\portal-beta-supervisor.ps1 -UseCommissionedAdapters. The tunnel is already running as a service.

Stopping: close that window. The address will show a Cloudflare error until you start it again.

Checking the tunnel: in an Administrator PowerShell, Get-Service cloudflared.

When the tunnel misbehaves

That is everything for a portal you use yourself. If artists need to sign in, carry on to Part 2; otherwise you are finished.