Quick Self-Host Guide

HakoSpace is a self-hosted voice, video, and messaging platform that gives you full control of your server, data, and privacy. (The name “Hako” comes from the Japanese 箱 (はこ) — a box of your own.)

This guide walks you through every required step, from nothing to your first member joining, and includes a recommended security checklist. It’s written for hosters who want to get a HakoSpace Server up and running as quickly as possible.

1. What You’ll Get

When you finish this guide, you’ll have:

A HakoSpace Server that’s reachable from the internet over HTTPS
An owner account of your own
At least one additional admin (recommended in §6.4)
Banned-word filtering and a registration policy in place
A known backup location and backup procedure

The overall process:

Get the server (a Docker image or a single executable; choose one)
Prepare a domain and TLS
Start the server
Create the owner account and configure the basics
Apply the security checklist
Invite your first member

Each step has its own chapter below. This guide covers only what’s required and what’s recommended for security; for all “advanced settings,” it points you to the matching chapters of the Admin Manual.

2. Before You Start

2.1 System Requirements

Item	Value
Operating system	Linux or Windows (the single executable is amd64; Docker additionally supports ARM64)
RAM	At least 512 MB
Disk	Depends on usage (messages and uploaded files are stored in the `data/` directory; with Docker, in the volume you create)
Domain	Optional; needed only for setting up TLS

HakoSpace Server is available as two executables: Linux amd64 and Windows amd64. There’s also a Docker image that supports both amd64 and ARM64, so it runs on a Raspberry Pi, ARM-based cloud servers, and Macs with Apple silicon; the version that matches your machine is picked automatically when you download it. Any machine that meets the table above will do, whether it’s a cloud VPS or a home computer.

2.2 What You Need to Have Ready

Before you begin, make sure you have everything below:

A server that meets §2.1
If you plan to use Docker (§4.1): Docker installed on that machine
Firewall rules: open 8080/TCP (HTTP) and 8443/TCP (HTTPS) to the outside
An email account: you’ll need it if you later enable the email verification registration policy (§6.1)
A domain name: strongly recommended; §3.2 explains how to get one

If your firewall doesn’t allow ports 8080 and 8443 beforehand, outside users can’t reach your server, and validation for the ACME automatic certificate in §3.3 also fails.

3. Domain and TLS

3.1 Why You Need a Domain

HakoSpace Server checks its TLS settings the first time it starts. If you haven’t specified a domain or provided a certificate manually, the server automatically generates a self-signed certificate so that it can run. A self-signed certificate encrypts connections normally. Browsers show a warning page that requires users to click Advanced and trust the certificate manually before they can get in.

If you’re only trying it out by yourself on your own machine, a self-signed certificate is enough. Once you plan to invite friends or community members, or to open it to the public, you need:

A domain that resolves to your server’s public IP
A certificate issued by a trusted CA (for example, Let’s Encrypt)

HakoSpace Server has a built-in ACME client. It automatically requests a certificate from Let’s Encrypt the first time it starts, and renews it automatically before it expires. You don’t need to run any certificate-issuing commands by hand.

3.2 Ways to Get a Domain

There are two main options for getting a domain:

Fixed Domain

Buy a domain from any domain registrar (GoDaddy, Namecheap, Cloudflare Registrar, Gandi; any of them works). Then, in the registrar’s DNS settings, add an A record that points the domain to your server’s public IP.

When to use it: your server has a fixed public IP (cloud VPSs usually do).

Dynamic DNS (DDNS)

The public IP of a home network usually changes whenever your ISP reconnects you. An A record that points straight at a fixed address breaks often. Here’s how a DDNS service handles this: a small program runs on your server or router, and whenever the IP changes, it automatically updates the DNS A record, so the domain always points to your current IP.

DDNS comes in two kinds:

Router built-in DDNS: Many home routers (ASUS, TP-Link, Netgear, and others) have a DDNS service built in. For example, ASUS routers offer free domains in the form xxx.asuscomm.com. Turn it on in the router’s admin page; you don’t need to install any client program on the server.
Third-party DDNS services: For example, no-ip offers names in the xxx.ddns.net format, and DuckDNS offers the xxx.duckdns.org format. Sign up for a free account, then run the matching update client on your server or router.

CGNAT warning: If your ISP uses CGNAT (many customers sharing the same public IP), outside devices still can’t connect to your server, even with DDNS set up. In that case, ask your ISP for a fixed IP, or use a cloud VPS instead.

3.3 Set Up TLS (HTTPS)

HakoSpace Server supports four ways to set up TLS. At startup, it automatically determines which one to use, in this order of priority:

Mode	Condition	Result
ACME automatic certificate (recommended)	Set `ACME_DOMAIN=your.domain.com` in `data/.env`	At startup, the server automatically requests a certificate from Let’s Encrypt and renews it automatically; the certificate is cached in `data/certs/`
Manual certificate	Both `TLS_CERT=/path` and `TLS_KEY=/path` are set	The server uses the certificate files you provide
Plain HTTP	Set `TLS_AUTO=false`	The server doesn’t enable TLS; for local networks or test environments only
Self-signed certificate	None of the above is set (default)	The server automatically generates a self-signed certificate; browsers show a warning

ACME mode is all the vast majority of hosters need. Steps (ACME, the preferred choice for production):

Make sure your domain (including a DDNS name) already resolves to the server’s public IP. You can run ping your.domain.com from another machine and check that the IP in the reply is the one you expect.
Make sure the server is reachable from the internet. The most direct way: set up NAT port forwarding on your router, forwarding external 443 → the server’s 8443 (required; it serves HTTPS and TLS-ALPN-01 certificate validation). It’s also recommended to forward external 80 → the server’s 8080 (so that ACME HTTP-01 validation can work too, which improves the chances of getting the certificate on the first try). If your cloud VPS runs the server directly on a public IP, you only need to allow 8080 and 8443 in the firewall; no port forwarding is needed.
Edit data/.env and add the line ACME_DOMAIN=your.domain.com.
Start the server (see §4 for the steps).
On first start, the server shows messages in its log about getting the certificate from Let’s Encrypt. After that, the certificate renews automatically before it expires.

If you haven’t started the server for the first time yet, you can jump ahead to §4 and run it once to create data/.env, then come back and edit the file.

4. Get and Start HakoSpace Server

There are two ways to get the server running. Choose one and follow it through:

Use Docker (§4.1) — take a ready-made configuration file and run one command. It has the fewest steps and the simplest updates later on. The machine needs Docker installed first.
Use the single executable (§4.2 onward) — download one file and run it directly. You don’t need to install Docker on the machine, but you set up automatic start at boot yourself, once (§4.5).

Both paths give you a server with exactly the same features, and the chapters from §5 onward apply to both.

4.1 Set Up with Docker

Before you start: Docker must already be installed on the machine. For how to install it on Linux, Windows, or macOS, see Docker’s official installation guide; this guide doesn’t repeat it.

Step 1: Get the Configuration File

Get docker-compose.yml from HakoSpace-releases and put it in the directory where you want the server to run permanently. The file already has all the required settings filled in, so it works without changing a single line.

Step 2: Start It

In the directory that contains docker-compose.yml, run:

docker compose up -d

On first start, HakoSpace automatically generates a random JWT_SECRET and saves it in its data area. You don’t need to configure anything by hand.

Step 3: Check That It Started

Open a browser and go to http://localhost:8080 (when connecting from another machine, use this machine’s address instead). If you see the HakoSpace login page, it worked. Next, go to §5 to create the owner account.

If You Use a Graphical Container Manager

Some systems let you create containers through a graphical interface, without opening a terminal (for example, the container manager built into a NAS, or a container management interface you installed yourself). Whichever one you use, these are the four things to fill in:

Field	What to enter
Image	`ghcr.io/hakospace/hako:latest`
Port	Host `8080` → container `8080`
Volume	Create a volume named `hako-data` and mount it at `/app/data` in the container
Environment	Set `TLS_AUTO` to `false`

Don’t skip the last one. HakoSpace’s built-in TLS is on by default, and while it’s on, the main service runs on 8443. If you map only 8080, you end up with a server whose “status looks normal but the web page won’t open,” and nothing on screen gives you any clue why. To use HTTPS, see §3.3.

Four Things to Know When Running on Docker

1. All your data is in that volume. The database, the TLS certificates, and the automatically generated JWT_SECRET are all stored in hako-data. Losing this volume means losing the whole server’s identity — every member has to log in again, and the certificates have to be redone. Backing up means backing up this volume; see §6.5 for how.

2. Updates work differently. Updating a container means “swapping in a new image,” so the app’s built-in auto-update is deliberately turned off in the container. When you click Check for Update in the update area of the admin panel, it shows Managed by Docker instead, along with a command. To update, all you need to do is run this in the same directory:

docker compose pull && docker compose up -d

Your data stays in the volume and isn’t lost when the container is recreated.

Running pre-releases: in docker-compose.yml, change ghcr.io/hakospace/hako:latest to ghcr.io/hakospace/hako:pre, and update with the same command. :latest is the latest stable release; :pre follows the latest pre-release and also moves up when a newer stable release comes out, so it’s never older than :latest. Before switching from :pre back to :latest, check that :latest isn’t older than the version you’re running — a newer version may already have changed the database, and an older version isn’t guaranteed to read it.

3. Ports to open. 8080 and 8443 are both TCP. Also, if you later enable the built-in TURN relay in the admin panel (it’s off by default), open 3478 for both UDP and TCP as well.

4. Don’t change the ports to 80 or 443. Inside the container, the server doesn’t run with administrator privileges, so it can’t use ports below 1024. To let the outside world connect on 80 / 443, set up the mapping on the host side (for example, map the host’s 443 to the container’s 8443).

Voice

For voice to get through all kinds of home networks, the key is the TURN relay setup — see Admin Manual §11 (Advanced Networking and Maintenance) for how. Voice setup in a Docker environment is still being verified; once the results are settled, this section will add the corresponding steps.

If you took the Docker route, you can skip §4.2 through §4.5 entirely and go straight to §5.

4.2 Download the Server Executable

You can download the server executable from either of the two places below. A given version is the same file in both places, so pick one:

The download page on the official website: hakospace.com/download
GitHub Releases

Pick the file for your operating system:

Linux: server-hakospace-linux-amd64-B<version>
Windows: server-hakospace-windows-amd64-B<version>.exe

On the website’s download page, the Server section has two cards, Linux and Windows. Each card shows the file name; click it to download. By default, the page offers the latest stable release, which is usually the one to download. To download a different version, see “Download Other Versions” at the end of this section.

On GitHub Releases, open the release marked Latest (the latest stable release), then click the matching file name in the file list to download it. Releases with Pre-Release in the title are pre-releases.

After downloading, put the file in the directory where you want the server to run permanently. It’s recommended to rename the file to hako (Linux) or hako.exe (Windows) to make it easier to work with later; the rest of this guide uses these names.

Renaming doesn’t affect the built-in auto-update. When it upgrades, HakoSpace detects the actual path and name of its own executable and overwrites that same file, so any name works.

On Linux, first give the file execute permission:

chmod +x hako

Windows doesn’t need this step, but be sure to run hako.exe from PowerShell or Command Prompt — don’t double-click it. A window opened by double-clicking closes as soon as the server exits, so you can’t see the startup log or tell whether it started successfully.

Download Other Versions

On the website’s download page, below the Download HakoSpace heading, there’s a Version drop-down menu. When you open the download page, the menu is set to the latest stable release. To download a different version, open the menu and choose it:

The Stable group lists the stable releases the download page currently offers; the one at the top is labeled Latest. If you choose an older version, a reminder appears below the menu: “This isn’t the latest version and may be missing later fixes and security updates. Unless you need this version, download the latest stable release.”
When there’s a pre-release newer than the latest stable release, a Pre-release group appears at the bottom of the menu. Choosing from it first opens a Download the pre-release? dialog, which explains: “Pre-releases are for people who want to try new features early. They may include unfinished features or known issues. If you’re not sure, use the stable release.” The menu switches only when you click I understand, use the pre-release. If you click Stay on stable, the menu goes back to the version it was on.

After you switch to a pre-release, the notice “You are viewing the downloads for pre-release {tag}.” appears above the downloads. Click Back to the latest stable next to it to switch back.

Whichever version you select in the menu, the download links, the file names, and the Verify checksums link (that version’s SHA256SUMS.txt) on the page change to match. If the selected version has no file for a platform, that spot shows Not available for this version.

If you set up the server with a pre-release, remember to turn on Receive Pre-release Updates in the Server Update section of Settings → Dashboard once the server is set up, so that Check for Update keeps offering new pre-releases. See §6.5.

4.3 Start It for the First Time

Go to the directory that contains the hako executable and run:

Linux:

./hako

Windows (from PowerShell or cmd):

hako.exe

On first start, HakoSpace does a few things:

Creates a data/ subdirectory in the current directory
Automatically generates the data/.env configuration file, which contains a random 48-character JWT_SECRET
Starts listening on 8080 (HTTP) and 8443 (HTTPS)

You can get it running without editing any settings by hand.

If you plan to get a proper certificate with ACME mode (§3.3): first get the server running and make sure everything works, press Ctrl+C to stop it, edit data/.env to add ACME_DOMAIN=your.domain.com, and then start the server again.

4.4 Check That It Started

Once it’s started, the server listens on port 8080 (HTTP) and 8443 (HTTPS) by default. Open a browser and go to:

Testing on the same machine: http://localhost:8080
With ACME mode: https://your.domain.com:8443 (if you’ve used NAT to forward external 443 to internal 8443, you can leave out the :8443 part)

If you see the HakoSpace login page, the server started successfully. If ACME is set up, the browser’s address bar shows a padlock icon, with no warnings.

4.5 Set It Up as a System Service (Recommended)

Make HakoSpace start automatically when the operating system boots. This step is recommended for both cloud VPSs and home machines that run long-term; otherwise, the server won’t come back up by itself after a reboot.

Linux: systemd

Create /etc/systemd/system/hakospace.service and paste in the following (adjust the paths and user to match your setup):

[Unit]
Description=HakoSpace Server
After=network.target

[Service]
Type=simple
User=hako
WorkingDirectory=/opt/hakospace
ExecStart=/opt/hakospace/hako
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Keep the Restart=always from the example. With it, systemd restarts the server automatically no matter how it exits (except when you stop it with systemctl stop). When you apply an update from the admin panel (§6.5), the server first swaps in the new executable and then exits normally on its own, and systemd starts the new version. If you change it to Restart=on-failure, systemd restarts the server only when it exits abnormally, so after you apply an update, the server stays stopped and doesn’t come back.

It’s recommended to create a dedicated hako system user and put both the executable and the data/ directory in /opt/hakospace/ to isolate permissions. The data/ directory is created automatically under WorkingDirectory on the first run.

Enable and start the service:

sudo systemctl daemon-reload
sudo systemctl enable hakospace
sudo systemctl start hakospace
sudo systemctl status hakospace

From then on, view the logs with journalctl -u hakospace -f, and stop or start the service with sudo systemctl stop|start|restart hakospace.

Windows: Task Scheduler

Create a simple .bat file (for example, C:\hakospace\start.bat) with this content:

@echo off
cd /d C:\hakospace
hako.exe

Open Task Scheduler and create a new task:

Trigger: run the task When the computer starts
Action: run C:\hakospace\start.bat
Start in: enter C:\hakospace

Once that’s set, the server starts automatically when Windows boots.

5. First-Time Setup

5.1 Create the Owner Account

By default, the first user to register automatically becomes the owner. The process:

On the login page, click the Register link next to Need an account? to go to the registration page.
Enter a username and password.
When registration is complete, you’re logged in automatically.
Your role is automatically promoted to owner.

The first time the owner logs in, three dialogs appear in turn:

Please review our updated terms dialog: The EULA and the Privacy Policy each have a checkbox. First click Read the full EULA or Read the full Privacy Policy next to it to open the full text, and scroll to the very bottom; only then can you select the matching checkbox. When both are selected, click Accept and continue. If you click Leave server, you’re logged out.
EULA consent dialog: I Accept becomes clickable after you open one of the terms links above it; click it to continue. If you click Decline, you’re logged out immediately.
HakoSpace Improvement Program dialog: Asks whether you’re willing to share anonymous usage statistics. You can choose Participate or No Thanks.

The last two dialogs appear only once, the first time the owner logs in. The first dialog appears for every member the first time they log in, and again after the terms are revised.

If you’re more advanced and want to designate the owner with an environment variable (for example, to let several people register first and decide later who becomes the owner), set OWNER_USERNAME=<existing username> in data/.env. When the server starts, it forcibly promotes that account to owner and demotes any other existing owners to admin. Note that the account must already exist on the server; otherwise, the server fails to start.

5.2 Set the Server Name

The server name is the display name other users see when they connect to your server (for example, “Welcome to {serverName}!” on the login page).

Steps:

After logging in with the owner account, open the Settings → Overview tab.
Find the Server Name field (up to 32 characters).
Enter the name you want, and save.

After you save, anyone who opens the login page or reloads the page from then on sees the new server name.

6. Security Checklist (Required)

The previous chapters got the server running; this chapter makes it secure. It’s recommended that you finish all of it before opening the server to members. Each section has two parts: “why it’s recommended” and “exactly where to find it.”

6.1 Registration Policy (Including Email Verification)

By default, your server is in open registration mode: anyone who has the URL can create an account. That’s too permissive for most communities, so the first thing to do is change the registration policy.

Where to find it: the Settings → Registration tab.

HakoSpace offers four registration modes:

Mode	Behavior
Open	Anyone can register (default)
Invite Only	Users need an invite code to register
Closed	Registration is turned off; the login page shows “Registration is currently closed.”
Email Verification	Users must provide an email address when they register and complete verification before the account is activated

Recommended Choices

Closed communities (friends, a company, a private group): choose Invite Only, then create an invite code in the invite codes section and send the link to the people who want to join.
Public or semi-public communities: choose Email Verification. Why: it blocks mass bot registrations and abuse through disposable accounts; email verification is the low-barrier line of defense that public communities accept most readily.

Important: Setup Order

The Email Verification option appears in the list of registration mode buttons only after you’ve already set up the Email Proxy. Without an Email Proxy configuration, the server has no way to send verification emails, so the interface hides this option.

Set Up the Email Proxy

Where to find it: the Settings → Email Proxy tab.

HakoSpace supports three email providers:

Gmail (recommended for first-time hosters): send mail with your own Gmail account and an App Password. The fields to fill in:
- Provider: choose Gmail
- Username / API Key: your Gmail address
- Password / API Key: the App Password you generated (not your main Gmail password)
- From Address: preferably the same as your Gmail address
- From Name: your server’s display name (for example, HakoSpace - YourCommunity)
- Base URL: your server’s public URL, for example https://chat.yourdomain.com:8443
Resend: a commercial email-sending API service. Sign up at resend.com to get an API key, and enter the API key in the Password / API Key field.
Custom SMTP: enter the host, port, and authentication details of your existing SMTP server manually.

When you’re done, click the test button that goes with “Send a test email to verify your configuration.” to confirm that the Email Proxy settings work. After the test passes, go back to Settings → Registration and switch the mode to Email Verification.

For advanced sending options (such as changing the SMTP Port), see Admin Manual §9. For Password Change Verification (members also confirm password changes by email), see Admin Manual §3.

6.2 Get to Know the Audit Log

The audit log is HakoSpace’s built-in history of administrative actions. It’s on by default and has no switch, so this section doesn’t teach you how to “enable the audit log.” Instead, it tells you where it is, what it records, and how to use it.

Administrative actions such as changing a member’s role, banning or kicking a member, granting or revoking permissions, changing the server name or registration mode, and creating or deleting channels are all written to the audit log automatically. Whether the action was taken by the owner, an admin, or a member who has been granted management permissions, the entry records who did it.

Where to find it: the Settings → Audit Log tab.

You see a list, newest first, of the 200 most recent administrative actions. Each entry includes:

Who performed the action
What they did (for example, changed a role, changed a setting, or kicked a member)
To whom, or to which resource
When it happened
The source IP (if it was recorded for that action)

Above the list is a filter that lets you narrow the entries to the action types you care about.

Next to the filter there’s also a Show automatic cleanup checkbox, which is cleared by default. When you select it, the list also shows entries for older messages or files that the server removed automatically under its retention settings, with System shown as the one who performed the action. For details, see Admin Manual §9.

When You’ll Use It

In situations like these, the audit log gives you the answer directly:

A member’s role was changed, but you don’t remember authorizing it
Server settings look different from what you remember
The same IP keeps showing up with unusual actions
You want to know who carried out a particular ban or kick

Day to day, opening it once a week or once a month to catch anything unusual early is enough.

6.3 Set Up Banned Words

Banned words is a message-level word filter. When it’s enabled, messages that users send are scanned in real time, and any message that matches a word on the list is handled according to the mode you set.

Default behavior: on first start, HakoSpace creates a default banned-word list (including common abusive words in English and Chinese), but the feature itself is off by default. To use it, you need to turn it on explicitly in the settings.

Where to find it: the Settings → Banned Words tab.

Steps to Enable

Turn on the Enable Banned Words switch.
Choose a handling mode:
- Replace: banned words in the message are replaced with the characters you specify (*** by default; you can change this in the Replacement Text field).
- Block: the whole message is blocked and isn’t sent.
Review the default list and decide whether to add or remove words to suit your community’s culture.
You can choose the matching method for each word separately:
- Exact: triggers only on an exact, whole-word match
- Contains: triggers whenever the message contains the string (even as part of another word)
Click Save. Your changes to the switch, the handling mode, and the list are saved together only when you click it.

Recommended Practices

Before enabling it, review the default list. Add common local insults or harassing words that fit your community’s context, and remove entries you decide you don’t need.
After enabling it, you can see the history of messages that were actually filtered on the Settings → Banned Words → Filter Logs page, which helps you adjust the list and the handling mode.
If your community leans toward strict moderation, it’s recommended to start with Block mode and relax it to Replace later as needed.

6.4 Set Up at Least One Admin

The owner account has the highest privileges on the server, but it’s also a single point of failure: if the owner account’s password is forgotten, its email stops working, or the owner is temporarily unable to act, nobody can manage the server. Setting up at least one admin avoids this. Admins can handle day-to-day member management, channel adjustments, and audit reviews, while actions on other admins (changing roles, banning, kicking) are reserved for the owner.

Where to find it: the Settings → Members tab.

Create Your First Admin

Ask a member you trust to register an account under the registration mode you chose in §6.1.
As the owner, go to Settings → Members and find that member’s row.
Click the Change Role button on that member’s row.
Choose admin.

Promotion Rules

Changing a role requires the Administrator permission, which the admin role has built in. On a newly set-up server, only the owner has it, so the owner promotes the first admin.
After that, admins can also promote other members to admin (admins can change only members’ roles, not the owner’s or other admins’).

Once your first admin is in place, at least two accounts can perform administrative actions. In practice, 2–3 admins are recommended for a small community; larger communities can add more as needed.

If you only want someone to share part of the management work (for example, only handling members who break the rules), you don’t need to make them an admin. Granting them the matching permission in the Settings → Permissions tab is enough; see Admin Manual §4.3 for details.

6.5 Baseline Backup Strategy

All of HakoSpace’s data — messages, users, channels, settings, and uploaded files — is stored in the data/ directory (with Docker, this directory is inside the hako-data volume you created). If this directory is damaged and you have no backup, none of your conversations or member data can be recovered. That’s why backups are a must.

Built-in Backup

Where to find it: Settings → Dashboard, then scroll down to the Backup section.

When you click the Create Backup button, the server:

Creates a clean snapshot of the database
Packs the entire data/ directory into a zip file
Saves it as data/backup/hako-backup-<timestamp>.zip

The Backup section also lists your existing backups and lets you download or delete them.

Three Baseline Recommendations

Back up manually at least once a week: add it to your routine; picking a fixed day of the week is recommended.
Download backup files to somewhere other than the server: download the zip file to cloud storage or your own device. A backup kept only on the same machine as the server is lost along with it if the disk fails or the server is compromised, which is the same as having no backup.
Always back up before upgrading the server: the upgrade process itself is relatively safe, but this is a basic rule of backups.

Upgrade the Server

If you use Docker, go straight to the update part of §4.1 — built-in upgrades are deliberately turned off in the container, and you update by pulling the image again. What follows is for the single-executable path.

HakoSpace has a built-in upgrade process. Where to find it: Settings → Dashboard, then scroll down to the Server Update section.

After you click the Check for Update button:

If you’re already on the latest version, it shows Up to date.
If there’s a new version, it shows New version available! and the version number. Then:
1. Click Download Update. The server downloads the new version and verifies it automatically. When verification passes, it shows Download complete, verified.
2. Click Apply Update. You’re asked to confirm once more: “This will disconnect all users and restart the server. Are you sure?”
3. Click Yes, Apply Update to start applying it. The screen shows Updating server….

On Linux, after you apply it, the server switches to the new version and restarts. You do the whole thing in the web page, with no need to SSH in and handle it by hand. Once the new version starts, every member receives a System Update notification: “Updated from {from} to {to}”.

If you’ve set HakoSpace up as a systemd service (§4.5), systemd handles the restart: after swapping in the new executable, the server exits on its own, and systemd starts the new version. That’s why the example in §4.5 uses Restart=always.

If you want to upgrade entirely by hand (for example, to pin a specific version, or to switch to a pre-release temporarily), the standard process is: stop the server → replace the executable with the new version → start the server again. The entire data/ directory is kept intact, and the new server reads the existing data directly when it starts. You can choose the version to switch to from the versions listed in the Version menu on the website’s download page (§4.2).

The Server Update section mentioned above has a Receive Pre-release Updates switch, which decides whether Check for Update also includes pre-releases. It’s off by default. If your server runs a pre-release (whether you set it up with a pre-release or switched to one by hand), remember to turn this switch on, so that Check for Update keeps offering new pre-releases. While the switch is off, Check for Update offers the latest stable release. If you’re running a pre-release, the stable release’s version number may be lower than your current one; download and apply it with the Download Update → Apply Update steps above, and you’re back on the stable release.

For the full description of the update area (including switching between pre-releases and stable releases, what to do when automatic verification fails, and where updates are downloaded from), see Admin Manual §11.5.

7. Invite Your First Member

At this point, your server is running and secure. Now you can invite your first member.

How you invite people depends on the registration policy you chose in §6.1:

Open mode: give them the server URL (for example, https://your.domain.com:8443), and they register on their own.
Invite Only: go to the Settings → Registration → Invite Codes section and create an invite code. When you create it, you can set the maximum number of uses (0 = unlimited) and the expiration time (0 = never expires). Give them the server URL together with the invite code.
Email Verification: all you need to do is give them the server URL. When they register, they receive a verification email, and their account is activated only after they click the link in it.
Closed mode: first switch to one of the modes above that allows registration, then switch back to Closed after you’ve invited them.

Once they finish registering, they join as a member. If you want to make them an admin too, repeat the process in §6.4.

That completes every required step, from nothing to your first member joining.

8. Further Reading

The advanced settings from here on are all in the Admin Manual. Look them up as you need them:

Full member management (banning, kicking, user groups): Admin Manual §3 (Members and Registration) and Admin Manual §4 (User Groups, Badges, and Permissions)
Granting individual management permissions to members or user groups: Admin Manual §4.3 (Permissions)
Channel structure (text channels, voice channels, forum channels) and channel group settings: Admin Manual §2 (Channel Management)
Managing content resources such as IO Apps, stickers, and the sound board: Admin Manual §5 (IO Apps Management) and Admin Manual §6 (Stickers and Sound Board)
AI bot (experimental) settings and usage limits: Admin Manual §10 (AI Bot)
Server updates (including switching between pre-releases and stable releases) and backups: Admin Manual §11.5 (Server Update) and Admin Manual §11.3 (Backup)
The built-in TURN relay and advanced network settings (used when voice needs to get through all kinds of home networks): Admin Manual §11 (Advanced Networking and Maintenance)

To learn how to use HakoSpace as a user, see the User Guide.