FAQ

This FAQ gives quick answers for every kind of reader: end users, hosters, and admins alike. Each answer gives only its conclusion, in one to three sentences; when you need the full steps, the end of the answer points you to the matching section of Getting Started, the User Guide, the Quick Self-Host Guide, or the Admin Manual. HakoSpace is designed so that each server has its own separate accounts — every server keeps its own member data — and this basic property runs through many of the answers here.

1. General Questions

Q1.1 What Is HakoSpace? How Is It Different from Other Chat Platforms?

HakoSpace is a self-hosted voice, video, and messaging platform, made up of HakoSpace Server and a client (HakoSpace Web or HakoSpace Desktop). The biggest difference from other chat platforms is that you (or your server owner) host the server on your own machine, and the server, its data, and privacy are all controlled by whoever hosts it.

→ See Getting Started §1; self-hosting: the Quick Self-Host Guide; administration: the Admin Manual

Q1.2 What Can HakoSpace Do?

You can send messages in text channels; use real-time voice, video, and screen sharing in voice channels; have 1:1 direct messages and calls with a single member; write posts and replies in forum channels; and use embedded mini apps such as Whiteboard or Snake in IO App channels.

→ See User Guide §2 (text), §3 (voice), §4 (direct messages), §5 (forums), and §6 (IO Apps)

Q1.3 What Do I Need to Install to Use HakoSpace? What’s the Difference Between HakoSpace Web and HakoSpace Desktop?

Open the URL your server owner gives you in a browser, and you can use HakoSpace (HakoSpace Web) without installing any software; if you want it running all the time or want the desktop-only features, you can also download HakoSpace Desktop (Windows / Linux). Both have the same core features; for the desktop-only features, see Q4.1.

→ See Getting Started §2 for a comparison; desktop-only features: User Guide §10

Q1.4 What Interface Languages Does HakoSpace Have?

HakoSpace offers two interface languages, English and Traditional Chinese: switch between them in Settings → App Settings → Language, and the change takes effect immediately. To open the settings panel, click the gear icon on the right of the tab bar (tooltip: User Settings).

→ See User Guide §7.8

Q1.5 How Are Direct Messages (DMs) Different from Channels?

A direct message is a 1:1 conversation space with a single member: it isn’t managed by any channel, it isn’t subject to channel permissions, and it has 1:1 voice and video calls built in. For a conversation with three or more people, use a text channel instead.

→ See User Guide §4

2. Accounts and Logging In

Q2.1 After I Register on One HakoSpace Server, Can I Use the Same Account to Log In to Other Servers? Can I Connect to Several Servers at Once?

Each HakoSpace Server has its own separate accounts, so you register once on each server you want to join. You can connect to several servers at the same time: in HakoSpace Web, open multiple browser tabs, and in HakoSpace Desktop, switch between them with the multi-server sidebar.

→ See Getting Started §1 (the note at the start of the chapter) and §2; multiple servers in HakoSpace Desktop: User Guide §10.1

Q2.2 How Do I Join a HakoSpace Server?

You need the URL your server owner gives you (starting with https://...). On the Web route, enter the URL in your browser; on the Desktop route, click the + in the multi-server sidebar of HakoSpace Desktop (when you hover over it, it shows Add Server) and fill in the server name and address.

→ See Getting Started §3 (§3.1: Web; §3.2: Desktop)

Q2.3 How Do I Create an Account? Why Can’t I Register on Some Servers, or Why Does Their Registration Page Look Different?

On the login page, click Register next to Need an account? to go to the registration page, and fill in fields such as a username and a password (at least 6 characters, including both letters and numbers). Each server has its own registration policy, so you may also run into invite-only registration (an invite code is required), email verification, or closed registration (the page shows “Registration is currently closed.”).

→ See Getting Started §4; server-side settings: Admin Manual §3.1

Q2.4 I Didn’t Get the Verification Email. What Should I Do?

The verification email is sent from the sender address your server owner set up, so check your spam folder first. If it still hasn’t arrived, log in once with that account’s username and password: the login page then shows a Resend Verification Email button (it does not appear if the username or password is wrong); enter the email address you registered with and click it to send the email again.

→ See Getting Started §4

Q2.5 I Forgot My Password. What Should I Do?

Below the username and password fields on the login page is a Forgot password? link; what happens next depends on your server’s settings.

→ See Getting Started §4

Q3.1 What Formatting Do Messages Support, and What Can I Do with Them? How Do I Zoom In on an Image in a Message?

Messages support Markdown-style formatting such as bold, italics, strikethrough, inline code, and spoilers; the Formatting help button next to the message box shows the full syntax. Hover over a message to add an emoji reaction, pin it, or reply to it, and you can also edit and delete your own messages. Clicking an image opens the image viewer, where you can zoom and drag; on touch devices, pinch with two fingers to zoom and swipe left or right to move between images.

→ See User Guide §2.2 (formatting), §2.3 (message actions), and §2.4 (image viewer)

Q3.2 How Do I Join a Voice Channel? Can I Still Talk If I Denied Camera Permission?

Click a voice channel’s name to join it right away. The first time you join, only microphone permission is requested; camera permission is requested separately, only when you click Start camera. If you deny camera permission, you can still have voice-only calls.

→ See Getting Started §6; full details: User Guide §3 (camera permission: §3.3)

While you’re in a voice channel, click Visual Source on the personal control bar and choose Start camera or Share Screen; in browsers on phones and tablets, Share Screen is disabled, while Start camera works as usual. When you use the game HUD in HakoSpace Desktop for Windows, you can also open the HUD panel in your game and click Share this game.

→ See User Guide §3.3 (camera), §3.4 (screen sharing), and §10.11 (game HUD)

Yes. Multiple shares appear side by side on the stage; external streams pushed with tools such as OBS appear as Click to Load tiles, and watching starts only when you click one. To watch in a separate window, click Pop Out on that share’s control bar, or click Pop out stage at the top of the channel.

→ See User Guide §3.4 (screen sharing and pop-out windows) and §10.5 (using pop-out windows in HakoSpace Desktop)

Q3.5 Can I Adjust the Microphone, Speakers, and Audio Quality for Calls?

Yes. You adjust input and output devices, the voice threshold, and screen share quality in Settings → App Settings → Voice & Audio, while the audio quality of a voice channel itself is decided in the channel settings by members who hold the Manage channels permission. To adjust one particular member’s voice on its own, right-click them while you’re both in the voice channel (long-press on touch devices) and drag User Volume in the member menu; this changes only the volume you hear.

→ See User Guide §3.5 and §7.6; volume for an individual member: User Guide §3.1; channel audio quality on the admin side: Admin Manual §2.2

Q3.6 Older Messages or Files in a Channel Have Disappeared. What’s Going On?

If a channel has a Message limit or Keep messages for (days) set, older messages are removed automatically, and when you scroll back to the beginning of the channel, you see a notice saying that messages were removed automatically. If When the file space is full is set to Remove the oldest files, only the files are removed and the messages themselves stay; where a file used to be, you see “Removed by this channel’s file space rules · {date}”.

→ See User Guide §1.3 and §2.4; channel settings: Admin Manual §2.1

4. Desktop App Questions

Q4.1 What Features Does HakoSpace Desktop Have That HakoSpace Web Doesn’t?

HakoSpace Desktop offers desktop-only features such as the multi-server sidebar, running in the system tray, global shortcuts, Push to Talk, HakoCap screen capture, remembering window position and size, launching at login, high-load viewer boost (Windows), the game HUD (Windows), and per-app audio capture (Linux). HakoSpace decides automatically whether to use HakoCap, so you don’t need to set it up; to launch at login, turn on Start on login in Desktop App Settings → Behavior.

→ See User Guide §10 (HakoCap: §10.5; launch at login and window memory: §10.7); starting a self-hosted server automatically at boot is a separate matter: see Q5.1

Q4.2 HakoSpace Keeps Running After I Close the Window. Is That Normal? What Should I Attach When I Report a Problem?

Yes. By default, HakoSpace Desktop uses Minimize to system tray when you close the window and keeps running; you can change this to Quit application in Desktop App Settings → Behavior → Close Button Behavior. When you report a problem, right-click the system tray icon, choose Open Diagnostics Folder, and attach the hako-diag.log file inside it.

→ See User Guide §10.2

Q4.3 How Do I Update HakoSpace Desktop?

In the installed Windows version, Automatic Updates is on by default: at launch, the app first checks for and installs updates; while it’s running, it only pre-downloads updates in the background and doesn’t restart on its own, and once an update is downloaded, you apply it by clicking Restart to apply update or by waiting for the next launch. To update manually, click Check for Update in Desktop App Settings → Update, and if there’s a new version, click Update now (in the portable and Linux versions, it’s Download from GitHub).

→ See User Guide §10.8

Q4.4 How Do I Set Up Push to Talk and Global Shortcuts? Once They’re Bound, Do Games Still Receive the Same Keys?

For Push to Talk, choose Push to Talk in Desktop App Settings → Behavior → Voice Input Mode, then bind Push to Talk Key in Desktop App Settings → Shortcuts; the other shortcuts are bound on the same page too, and none of them is bound by default. When a key combination bound on the Shortcuts tab includes a modifier key such as Ctrl, Alt, Shift, or Super, it works whether HakoSpace is in the foreground or the background, and games and other apps still receive the same keys as usual. For a single key without a modifier, or in a Wayland desktop environment on Linux, shortcuts work only while HakoSpace is in the foreground.

→ See User Guide §10.3, §10.4, and §11.3; HUD shortcut: User Guide §10.11

Q4.5 I Enabled the Game HUD. Why Can’t I See It in My Game? Why Doesn’t It Appear on Programs Such as Office and Web Browsers Either?

The HUD starts only after you join a voice channel, and it attaches to games running maximized or in borderless fullscreen; if you can’t see it, first check Status in Desktop App Settings → HUD, and make sure the game isn’t on the Disabled games list. By default, the HUD normally appears only when someone talks, joins, or leaves, or when there’s a new message; if pressing the HUD shortcut (default Shift + `) opens the HUD panel, the HUD is attached. By default, the HUD also doesn’t appear over common tools such as Office, web browsers, code editors, messaging apps, and video players.

→ See User Guide §10.11

If you use HakoSpace Desktop on Windows, you can try turning on High-load viewer boost (off by default) in Desktop App Settings → Behavior. Once it’s on, the boost is applied when you watch other members’ screen shares in a voice channel, and ⚡ Viewer boost active appears on the main window while the boost is in effect; a UAC prompt may appear when it’s applied.

→ See User Guide §10.10

5. Hoster and Admin Questions

Q5.1 How Do I Host My Own HakoSpace Server? How Do I Make It Start Automatically at Boot?

Follow the Quick Self-Host Guide to set it up with the official Docker image or by downloading the server executable; once it’s started, the first user to register automatically becomes the owner. If you set it up with the executable, you can use systemd on Linux or Task Scheduler on Windows to make the server start automatically at boot; on Linux, if you follow the example configuration, systemd brings the server back up automatically when it exits on its own (for example, to apply an update) or exits abnormally.

→ See Quick Self-Host Guide §4 (Docker: §4.1; system service: §4.5) and §5; launch at login for HakoSpace Desktop itself is a separate switch: see Q4.1

Q5.2 Do I Need a Domain? Can I Host on a Home Network Whose IP Changes? Do I Have to Request a TLS / HTTPS Certificate by Hand?

If you’re only trying it out by yourself on your own machine, the server automatically generates a self-signed certificate (browsers show a warning, and you have to trust it manually); to invite others or open the server to the public, you need a domain that points to the server’s public IP and a certificate from a trusted CA. On a home network whose IP changes, you can use DDNS (built into your router, or a service such as no-ip or DuckDNS); if your ISP uses CGNAT, ask for a fixed IP or use a cloud VPS instead. You don’t need to request the certificate by hand: set ACME_DOMAIN in data/.env, and the built-in ACME client automatically requests one from Let’s Encrypt and renews it before it expires.

→ See Quick Self-Host Guide §3 (§3.1: why you need a domain; §3.2: getting a domain and DDNS; §3.3: setting up TLS)

Q5.3 Which Firewall Ports Do I Need to Open? What Should I Do If Users Behind Strict NAT or a VPN Can’t Connect to Voice?

Open 8080/TCP and 8443/TCP to the outside (if they aren’t open, outside users can’t connect, and the ACME automatic certificate also fails); if the server’s outbound connections are restricted too, Check for Update and Download Update connect to dl.hakospace.com and GitHub, so allow those as well. When users behind strict NAT (VPNs, corporate networks) can’t connect to voice, you can enable the built-in TURN server in Network → TURN Server, open the TURN port (3478 by default, both UDP and TCP), and test it once from an outside network.

→ See Quick Self-Host Guide §2.2 and §3.3; TURN: Admin Manual §11.1 and §12.1; the domains to allow for updates: Admin Manual §12.2

Q5.4 How Do I Back Up My Data? How Do I Upgrade the Server to a New Version? How Do I Update a Server Running in a Docker Container?

All your data is stored in the data/ directory: click Create Backup in the Backup section of Settings → Dashboard to pack it into a zip file, and it’s recommended to back up weekly and keep the backups somewhere other than the server; always back up before upgrading. To upgrade, click Check for Update, Download Update, and Apply Update in order in the Server Update section of the same page, and confirm; on Linux, the server switches to the new version and restarts, and if you run it with systemd, the service configuration must use Restart=always. A server running in a Docker container is updated with docker compose pull && docker compose up -d instead; its data is kept in the volume and isn’t lost.

→ See Quick Self-Host Guide §6.5; backup: Admin Manual §11.3; the full update process (including switching between pre-releases and stable releases): Admin Manual §11.5 and §12.2

Q5.5 Which Security Settings Should I Set Up Before I Open the Server to Members?

Before you open the server to others, it’s recommended that you set a registration policy (invite-only or email verification), enable banned-word filtering, check the audit log (on by default), set up at least one admin, and establish a backup baseline.

→ See Quick Self-Host Guide §6; for more on each feature: Admin Manual §3 (registration and roles), §9 (banned words and the audit log), and §11.3 (backup)

Q5.6 What’s the Difference Between an Admin and an Owner?

The owner is the person who set up and owns the server, with the highest privileges; an admin is a second-level manager who can open every server settings tab and can also promote members to admin, but can’t change the role of the owner or other admins, or ban or kick them. If you only want someone to share part of the management work, you can grant individual permissions to members or user groups in Settings → Permissions, without promoting them to admin.

→ See Quick Self-Host Guide §6.4; changing roles: Admin Manual §3.3; granting permissions: Admin Manual §4.3

6. AI Bot Questions Experimental

This feature is experimental. Its interface and behavior may change in future versions. Evaluate it carefully before enabling it in production.

Q6.1 Does HakoSpace Have an AI Bot? How Do I (a Regular Member) Talk to It? Can I Use It by Default?

Some servers enable an AI bot that members can ask questions through direct messages: click the sparkle icon button to the right of the Direct Messages heading (hovering over it shows Start AI Chat) to open a direct message with the bot. The Member Access switch is off by default, and while it’s off, only the owner, admins, and members who have been granted the Administrator permission can use the bot; once it’s turned on, all members can use it.

→ See User Guide §4.1 and §9; admin settings: Admin Manual §10.1

Q6.2 I’m the Owner or an Admin. How Do I Enable and Set Up the AI Bot?

In Settings → AI Settings → Overview, turn AI Enabled on or off, choose a provider (Anthropic, OpenAI, Google Gemini, or OpenRouter) and a model, enter the API key, and set the bot’s name, whether regular members may use it, and the various limits. Members who have been granted the Manage AI permission can also change these settings.

→ See Admin Manual §10.1; granting permissions: Admin Manual §4.3

Q6.3 Can I Limit the AI Bot’s Usage?

Yes. On the Limits card, you can set the number of context messages, max tokens, a daily token limit, and a rate limit; the daily token limit is a single cap shared by the whole server, and the day changes at midnight UTC. You can see actual usage on the Usage Log tab.

→ See Admin Manual §10.1 and §10.3

Q6.4 What Tools Can the AI Bot Use? Who Can See Its Usage Log?

On the Tool Management tab, you can turn each tool the bot can use on or off, one by one; when the bot does something for a member, it uses only the tools that member has permission to use. The Usage Log tab lists the member, provider, model, token count, and status for each use, and the owner, admins, and members who have been granted the Manage AI or Administrator permission can see it; the page’s description states that the messages members send to the AI are not recorded, while tool calls are shown along with their parameters and results.

→ See Admin Manual §10.2 and §10.3

7. Privacy, Data, and Security

Q7.1 Where Is My Data Stored? Who Can See It?

HakoSpace is self-hosted: your messages, account, channels, and uploaded files are all stored in the server owner’s data/ directory, under the control of whoever hosts the server. Direct messages are a 1:1 conversation space; they aren’t managed by any channel and aren’t subject to channel permissions.

→ See Quick Self-Host Guide §6.5; how direct messages work: User Guide §4.2

Q7.2 Is There a Record of What Admins Have Done on the Server?

Yes. The audit log is on by default, and administrative actions such as changing a member’s role, banning or kicking a member, granting or revoking permissions, and changing the server name or registration mode are recorded 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. Anyone who holds the View audit log permission (the owner and admins always included) can view it in Settings → Audit Log and filter it by action type.

→ See Quick Self-Host Guide §6.2; details: Admin Manual §9.4

Q7.3 Are Messages Filtered?

The server owner can enable banned-word filtering: depending on the settings, words that match the list are replaced, or the whole message is blocked. Each server decides for itself whether to enable it and how to handle matches.

→ See Quick Self-Host Guide §6.3; managing it: Admin Manual §9.1

Q7.4 I See a Warning in the Browser Console, or F12 Doesn’t Open the Developer Tools in HakoSpace Desktop. What’s Going On?

When you open the browser console in HakoSpace Web, you see a warning in red text that says, in short: don’t paste or type in commands from unknown sources; it’s almost certainly a scam, and doing so gives the other person a chance to take over your account. If you’re a developer and really need the console, you can type devmode=enable in it to lift the protection, for the current tab only. In HakoSpace Desktop, F12 not opening the developer tools is likewise a deliberate security protection, not a malfunction.

→ This answer is self-contained

Q7.5 What Happens to My Data If My Account Is Banned or Kicked?

A banned member is disconnected immediately and can’t log in again; a kicked member is removed from the server, and their data is deleted. These actions are carried out by the owner, an admin, or a member who has been granted the Moderate members permission, and they’re recorded in the audit log.

→ See Admin Manual §3.4

Q7.6 Does HakoSpace Collect My Usage Data? Where Can I Read the Privacy Policy and License Terms?

The server owner can choose to join the HakoSpace Improvement Program to share anonymous usage statistics (the interface states “No personal data is collected.”). HakoSpace Desktop sends information such as your graphics card model and driver version only during screen sharing, to the server you’re connected to at that moment (not to HakoSpace itself), to diagnose video stuttering; for the foreground window information that the game HUD reads, the interface states: “This information is processed only on your device; it is not transmitted to HakoSpace or to the server you are connected to.” You can open the full Privacy Policy and EULA from the User Settings → About tab.

→ Improvement Program: Quick Self-Host Guide §5.1; the server-side switch: Admin Manual §1.1; what the HUD reads and why: User Guide §10.11; the About tab: User Guide §7.10

FAQ