豕豕豕 - Blog (EN)

Play Tears of the Kingdom Natively on Mac: A MacNativeGames Build Guide

Thu, 22 Oct 2026 00:00:00 GMT

If you want to play Tears of the Kingdom on a Mac, MacNativeGames offers a way to build a native app from your own game files. It adapts the game’s ARM64 code to run on Apple silicon, renders its graphics through Metal, and packages the result as an app you can open in Finder. Most of the setup happens during the first build.

This guide is for Mac users who may be unfamiliar with build tools. It covers installing dependencies, building the base game or an updated version, and setting up controls, graphics, and save backups. It covers the Mac version only.

Version used in this guide

Prepared on October 22, 2026, this guide follows the documentation and build script at commit 30a1b93. The commands select that source revision so the instructions can be checked against it. Requirements and controls may change in later revisions; consult their README when using newer code. The documentation and command arguments were checked for this article; a full game build and performance benchmarks were not repeated.

1. Check the requirements

Hardware and storage

Item	Requirement
Mac	An Apple silicon model, such as M1, M2, M3, M4, or M5; this workflow does not cover Intel Macs
System	macOS 26 or later, using the project’s Metal 4 backend
Memory	The project recommends at least 16 GB; an 8 GB machine may use substantial swap during the build
Storage	About 25 GB beyond the original game files for a base build, or about 40 GB for a fresh base-plus-update build
Network	Required to install dependencies and fetch pinned build sources

These storage estimates assume the work folder and finished app are on the same APFS volume, where cloning can share large data files. If cloning is unavailable or you put the app on another volume, allow roughly another 17 GB for the app copy. Make room before starting if your disk is nearly full.

Game files

Have these ready:

Your own version 1.0.0 base game, as an uncompressed XCI or NSP, with title ID 0100F2C0115B6000.
Your own prod.keys.
For an updated build, a separate cumulative update package for 1.1.2, 1.2.1, or 1.4.3, in NSP or NSZ format.
System shared fonts if you use an NSP base, as explained below.

Your files and the finished app

The project requires a game you own, with keys and system files from your own Switch. The repository supplies none of these, and this guide does not provide download sources. The app you build contains game content: keep it for personal use and do not share it.

The revision used here does not support compressed NSZ/XCZ base games, DLC, combined packages, or personalized tickets. NSZ support applies to updates. To build 1.4.3, supply the 1.0.0 base and the separate cumulative 1.4.3 update; intermediate updates are unnecessary.

2. Install the build tools

Open Terminal and install the Xcode command line tools:

xcode-select --install

If macOS says they are already installed, continue. Otherwise, wait for the installer to finish.

Install Homebrew using its official instructions, including the shell setup printed at the end. Its default Apple silicon prefix is /opt/homebrew; see the Homebrew installation documentation.

Check that Terminal can find it, then install the dependencies:

brew --version
brew install opus libvpx python@3.14
python3.14 --version

The final command should report Python 3.14.x. Use python3.14 throughout this guide to avoid selecting another Python installation.

This revision’s Mac build does not require .NET, CMake, or the iOS toolchain. The script prepares its remaining environment, and the finished app does not need Python to run.

Optional: install the Metal toolchain

If you have the full Xcode application, install the Metal toolchain following Apple’s additional-component documentation:

xcodebuild -downloadComponent MetalToolchain

The project uses this to compile startup shaders into the app. If you only have the command line tools, you can skip this step. The build can still proceed using the Mac’s Metal cache for the app’s location, which matters if you move the app later.

3. Download the source and organize your files

The following puts the source under ~/Projects. If you already downloaded it elsewhere, enter that directory instead.

mkdir -p "$HOME/Projects"
cd "$HOME/Projects"
git clone https://github.com/ly05010419/MacNativeGames.git
cd MacNativeGames
git checkout 30a1b93d0776150fbaffd7c20f9a5ca0841c21c9

The final command selects the revision used in this article. Git may display a detached HEAD notice; that is normal when selecting a specific commit and does not prevent building.

The examples below assume this layout. Replace the sample filenames and paths with your own.

~/Games/TOTK/
  base.xci            Base game; base.nsp for the NSP route
  update-1.4.3.nsp     Optional separate update
  firmware/           Needed for the NSP route; contains unpacked .nca files

~/keys/
  prod.keys

Create a personal Applications folder for the finished app:

mkdir -p "$HOME/Applications"

~/Applications is inside your home directory and differs from the system-wide /Applications. It normally needs no administrator privileges. Building directly to the intended location also reduces the need to rebuild location-dependent shader caches later.

Paths containing spaces

Quote the complete path, for example "$HOME/Games/TOTK/My Game.xci". You can also drag a file from Finder into Terminal to insert its path. A tilde inside double quotes does not expand, so these examples use "$HOME/...".

4. Choose your build command

Run the following from the MacNativeGames source directory. Choose the command that matches your files; you do not need to run every example.

XCI base: build version 1.0.0

python3.14 build_app.py "$HOME/Games/TOTK/base.xci" \
  -k "$HOME/keys/prod.keys" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

This builds 1.0.0. An XCI usually supplies shared fonts through its system update partition. If that partition is missing, add --firmware or --shared-fonts as described next.

NSP base: supply the shared fonts

An NSP base does not include system shared fonts, so provide an unpacked firmware directory:

python3.14 build_app.py "$HOME/Games/TOTK/base.nsp" \
  -k "$HOME/keys/prod.keys" \
  --firmware "$HOME/Games/TOTK/firmware" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

The firmware path must point to a directory containing .nca files, or an installed firmware’s registered directory. Do not pass a firmware ZIP archive directly.

If you previously extracted the fonts, replace --firmware and its path with:

--shared-fonts "$HOME/Games/TOTK/TOTK_build/totk/extracted/firmware/shared-fonts"

That is an argument fragment to insert into the build command. The directory must contain the six files from 0-standard.bfttf through 5-nintendo-extension.bfttf. The builder validates them and can reuse valid fonts already in the work folder. Ordinary macOS fonts are not substitutes.

Base plus update: build version 1.4.3

For an XCI base and a separate update:

python3.14 build_app.py "$HOME/Games/TOTK/base.xci" \
  -k "$HOME/keys/prod.keys" \
  --update "$HOME/Games/TOTK/update-1.4.3.nsp" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

For an NSP base, keep the font argument:

python3.14 build_app.py "$HOME/Games/TOTK/base.nsp" \
  -k "$HOME/keys/prod.keys" \
  --firmware "$HOME/Games/TOTK/firmware" \
  --update "$HOME/Games/TOTK/update-1.4.3.nsp" \
  -o "$HOME/Applications/Tears of the Kingdom.app"

If your update is an NSZ, change the --update path to that .nsz file; the builder handles decompression and verification. For 1.1.2 or 1.2.1, supply that version’s cumulative update instead. Omitting --update builds 1.0.0; updates are not selected automatically.

Argument	Purpose
File path after `build_app.py`	The 1.0.0 base game
`-k`	Your keys file
`--update`	Optional separate cumulative update
`--firmware` / `--shared-fonts`	Alternative font sources; use one
`-o`	Full output path, ending in `.app`
`--work`	Optional custom intermediate-file directory

Without -o, the app is written next to the base game. With the file layout above, the default work folder is ~/Games/TOTK/TOTK_build; it holds extracted data and build logs. After fixing a recoverable error, rerun the same command to reuse completed steps before considering removal of the whole work folder.

How long does it take?

The script extracts and verifies game data, rewrites code modules, prepares shaders, and packages and signs the app. Let it continue while progress is being reported. Memory, storage, network speed, and shader compilation all affect the first build.

The project reports that GPU shader compilation alone can take around 25 minutes on an 8 GB M1 MacBook Air. This helps explain a long wait; it is not an estimate for your complete build.

At the end, the script runs the launcher in --check mode. That completes executable checks and related startup checks. You still need to open the game to verify graphics, sound, and controls.

5. Let the first launch finish preparing

In Finder, press Command + Shift + G, enter ~/Applications, and open Tears of the Kingdom.app. Alternatively:

open "$HOME/Applications/Tears of the Kingdom.app"

The first launch verifies game data and prepares shaders. The project observed roughly 20 seconds for data verification locally; your wait depends on the machine and cache state. Allow visible progress to finish.

Shader warm-up can continue behind the title screen, with another wait when first entering the world. The builder already generates startup shaders from your game data and the shared shader list, so a cache downloaded from another player is normally unnecessary.

Unvisited scenes may still need new shader variants and briefly stutter. First-use compilation and persistently low frame rates call for different checks. If a second visit is noticeably smoother, the cache is helping. If it stays slow, investigate graphics settings, memory pressure, and the particular scene.

Can you move the app?

Yes, though choosing its destination before building is useful:

With the Metal toolchain: the app carries its precompiled startup shader libraries and can use those after moving.
Without the Metal toolchain: the Mac’s compiled shader cache is associated with the app’s location. Moving the app may trigger recompilation, as can a system cache cleanup.

This is why the examples use -o to build directly to the final directory. Copying across volumes can also require another copy of the game data and another macOS app check.

6. Controller and keyboard controls

Controllers: watch the confirm button’s position

Compatible controllers recognized by macOS, such as DualSense and Xbox controllers, are mapped to a Switch Pro Controller. The default face-button mapping follows position:

Physical position	Switch button	Xbox	PlayStation
Right	A: confirm / interact	B	Circle
Bottom	B: cancel / sprint	A	Cross
Top	X: jump	Y	Triangle
Left	Y: attack	X	Square

An on-screen A prompt therefore corresponds to the right-hand B button on an Xbox controller by default. Motion and rumble depend on the controller and what macOS exposes.

Custom controller mappings go in:

~/Library/Application Support/MacNativeGames/TOTK/controls.txt

For example, assign a DualSense touchpad click to the map button:

touchpad = minus

Unspecified buttons keep their defaults. Restart the game after editing. If the launcher reports an invalid line, check that line; deleting the configuration file restores the defaults.

Keyboard layout for this revision

These are the defaults at the commit used in this guide. Keys refer to physical US keyboard positions. For other revisions, check their README and in-game shortcut display.

Mac key	Action
W, A, S, D	Move: left stick
Arrow keys	Camera: right stick
J	A: confirm / interact
K or Space	B: cancel / sprint
I	X: jump
U	Y: attack
Q / E	L / R
Option / Shift	ZL / ZR
F, T, H, G	D-pad left, up, right, down
Z / C	Left / right stick click
Return	Menu (+)
Tab or Esc	Map (−)

7. Adjust graphics one setting at a time

First enter the game with its default settings and check basic controls. Then try the number keys one at a time so you can identify the effect of each change.

Key	Function
1	Cycle full overlay, FPS only, and hidden
2	Cycle interpolation: off, 30+30, half refresh rate, unlimited
3	Cycle MetalFX 2K, native 2K, and off
4	Cycle `16:9`, fit to window/display, and `21:9`; versions 1.2.1 / 1.4.3
5	Toggle MetalFX temporal anti-aliasing; version 1.4.3

Two details help interpret the results:

Interpolated frame counts include generated frames and do not directly represent the game’s logic frame rate.
Native 2K changes the composition canvas and UI. The 3D scene has separate render scaling, so this does not force every internal render target to 1440p.

The game follows your Mac’s language. To temporarily select Simplified Chinese, fully quit the game and launch it with:

open --env TOTK_LANG=zh-Hans "$HOME/Applications/Tears of the Kingdom.app"

That environment variable applies to this launch. Running open again while the app is already running does not reload its startup environment.

8. Find and back up your saves

The app, build work folder, and personal saves are stored separately:

Content	Location
App in this guide	`~/Applications/Tears of the Kingdom.app`
Default work folder in this guide	`~/Games/TOTK/TOTK_build`
Save profile	`~/Library/Application Support/MacNativeGames/TOTK/profile`
Shader cache	`~/Library/Application Support/MacNativeGames/TOTK/shader-cache`
Current run’s log	`~/Library/Logs/MacNativeGames/totk.log`
Previous run’s log	`~/Library/Logs/MacNativeGames/totk.previous.log`

Use Command + Shift + G in Finder to open these locations.

Before changing game versions, quit the game and copy the entire profile folder somewhere safe. Before an updated version starts, the project also creates a backup beside the profile, such as profile-before-1.4.3; startup stops if that backup fails. Keep your pre-upgrade backup for a rollback: a newer save may not work with an older game version.

To update the project’s code, obtain the desired newer source and rebuild using the original base game, the same update package, and the same output path. Quit the running game first, and preserve necessary arguments such as --firmware, --shared-fonts, and --work. Building to the same path replaces the app; saves remain in the separate user directory above.

9. Troubleshooting

Terminal cannot find `brew` or `python3.14`

Complete the shell setup printed by the Homebrew installer, reopen Terminal, and repeat the version checks in section 2. An existing python3 command may point to another version. Use the Apple silicon Homebrew installation to avoid mixing dependencies from an Intel environment.

Shared fonts are missing

Check the base format. NSP requires --firmware or --shared-fonts; an XCI missing its system update partition needs them too. The firmware must be unpacked, and an extracted font directory must contain the six .bfttf files.

A version or hash check fails

Check that the base is 1.0.0, the update is a supported separate cumulative package, the files are intact, and your keys match your content. Validation detects unsupported or damaged inputs. Do not edit the expected hashes to bypass the failure.

No game window appears after opening the app

First launch, moving the app, or copying it across volumes can trigger system checks or data verification. Look for progress and inspect the log. If an explicit error appears, address it. A successful build-time --check does not establish that gameplay works.

Stutter persists or memory pressure is high

Close other memory-heavy applications and inspect memory pressure and swap in Activity Monitor. Use key 3 to disable additional 2K modes for comparison, wait for background warm-up, and revisit the same scene. Avoid judging final performance during first-use compilation. Clearing every cache is not a routine optimization: the shaders would need to be prepared again.

Effects play, but dialogue or music is missing

Check the selected macOS audio output and volume, then look for CoreAudio or decoder errors in the log. The project includes a streamed-audio path fix; see its audio troubleshooting guide. If using an early app, rebuild from source containing the fix with your original game files. Compilation stalls can also interrupt playback and need separate diagnosis.

You want to install mods

Complete a build and launch without mods first. Then follow the project’s mod documentation. Code patches are merged at build time with --mod; RomFS data has separate installation and manifest requirements. Do not drop another environment’s mod folder into the app bundle.

References

Deploy Xboard Directly on Linux for a Self-Hosted Proxy Panel

Mon, 22 Jun 2026 00:00:00 GMT

This guide comes from a recent end-to-end deployment session where I set up an Xboard panel, Caddy for HTTPS, Hysteria2 nodes, a dedicated subscription domain, SMTP mail, and the final production hardening steps from scratch.

This setup fits a fairly common pattern: one public Linux server runs the Xboard panel, and one or more Linux VPS instances serve as nodes. You can host Xboard locally if you really want to, but you still need at least one overseas server for the node side.

Preparation Checklist

Before you start, make sure you already have the following:

One panel server: Ubuntu 22.04 / 24.04 or Debian 12, ideally with at least 1 GB RAM, with 80/tcp and 443/tcp available.
One or more node servers: Ubuntu 22.04 / 24.04 or Debian 12, running Hysteria2, with 8443/udp open, or later 20000-29999/udp if you plan to use port hopping.
A split domain layout: one panel domain, one subscription domain, and one or more node domains.
Access to Cloudflare DNS management, since the examples in this post assume Cloudflare.
An SMTP provider for sending mail. This guide uses Brevo’s free SMTP.
A mailbox that can receive verification messages. Here it is paired with Cloudflare Email Routing.
Basic system tools: curl, wget, git, ufw, and later Docker, Caddy, and certbot.

The example domains in this guide are:

Panel domain: v.shishishi3.com
Subscription domain: 474769754.xyz
Hong Kong node: hk.474769754.xyz
US node: us.474769754.xyz

Replace them with your own domains in practice.

Architecture

This post uses a direct Linux deployment model:

User -> HTTPS domain -> Linux server with Caddy -> Xboard container
User -> HY2 node domain over UDP -> Linux node server running xboard-node

I strongly recommend separating the responsibilities of your domains:

v.shishishi3.com
Purpose: the main Xboard panel, admin login, and management operations

474769754.xyz
Purpose: subscription distribution entry

hk.474769754.xyz
Purpose: Hong Kong node domain

us.474769754.xyz
Purpose: US node domain

Note

Do not use the same domain for the admin panel, subscriptions, and nodes. Splitting them makes troubleshooting and risk control much cleaner, and it also reduces the blast radius if one part gets blocked or abused.

If you want a separate subscription entry, a cheap numeric domain is usually enough. In practice it often costs less than ¥10.

Tutorial

1. Prepare the Servers

Recommended specs for the panel server:

OS: Ubuntu 22.04 / 24.04 or Debian 12
Memory: 1 GB minimum, 2 GB preferred
Ports: 80/tcp, 443/tcp

Recommended specs for node servers:

OS: Ubuntu 22.04 / 24.04 or Debian 12
Protocol: Hysteria2
Ports: 8443/udp, or 20000-29999/udp for port hopping

Start with a system update:

sudo apt-get update
sudo apt-get install -y curl wget ca-certificates git ufw

Troubleshooting

If this gets stuck because of an old Ookla speedtest repository, jump to Broken apt source.

2. Configure DNS

Example Cloudflare DNS records:

A  v    panel server IP  DNS only
A  @    panel server IP  DNS only
A  hk   Hong Kong node IP  DNS only
A  us   US node IP  DNS only

Important details:

For the root domain 474769754.xyz, the hostname should be @, not the literal domain string.
Node domains must stay gray-clouded, meaning DNS only.
HY2 uses UDP, and Cloudflare’s regular proxy does not forward that traffic.
Fresh DNS changes may take a few minutes to propagate.

Verify with:

nslookup 474769754.xyz 1.1.1.1
nslookup hk.474769754.xyz 1.1.1.1
nslookup us.474769754.xyz 1.1.1.1

Troubleshooting

If your local machine is using a proxy or TUN and you see 198.18.x.x fake IP results, jump to Fake-IP interference.

3. Install Docker and Compose

If Docker is not installed yet:

curl -fsSL https://get.docker.com | sudo sh
sudo systemctl enable --now docker
docker --version
docker compose version

4. Deploy Xboard

The official compose branch of Xboard ships with a Docker Compose template that exposes container port 7001 to host port 7001.

cd /opt
sudo git clone -b compose --depth 1 https://github.com/cedar2025/Xboard Xboard
cd /opt/Xboard

Make sure compose.yaml contains something like:

services:
  xboard:
    image: ghcr.io/cedar2025/xboard:latest
    restart: unless-stopped
    ports:
      - "7001:7001"
    volumes:
      - ./.env:/www/.env
      - ./.docker/.data/:/www/.docker/.data
      - ./storage/logs:/www/storage/logs
      - ./storage/theme:/www/storage/theme
      - ./plugins:/www/plugins
      - redis-data:/data

For a simple setup, initialize it with SQLite and the built-in Redis:

sudo docker compose run --rm \
  -e ENABLE_SQLITE=true \
  -e ENABLE_REDIS=true \
  -e ADMIN_ACCOUNT=admin@example.com \
  xboard php artisan xboard:install

The installer will print:

Admin email
Admin password
Admin path

Save those values, then bring the service up:

sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs -f

Test local access:

curl -I http://127.0.0.1:7001

The expected result is:

HTTP/1.1 200 OK

5. Install Caddy

Install Caddy:

sudo apt-get install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' \
  | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' \
  | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt-get update
sudo apt-get install -y caddy

Write this into /etc/caddy/Caddyfile:

v.shishishi3.com {
	reverse_proxy 127.0.0.1:7001
}

474769754.xyz {
	handle /s/* {
		reverse_proxy 127.0.0.1:7001
	}

	handle /api/v1/client/subscribe* {
		reverse_proxy 127.0.0.1:7001
	}

	respond "Not Found" 404
}

What this means:

v.shishishi3.com
Reverse-proxy the full Xboard panel.

474769754.xyz
Expose only subscription paths and keep the admin panel hidden.

The /s/* rule is important. A real Xboard subscription link often looks like:

https://474769754.xyz/s/xxxxxxxxxxxxxxxx

Troubleshooting

If you only allow /api/v1/client/subscribe*, the client import request can still get blocked by Caddy. If that happens, jump to Subscription 404.

Validate and reload Caddy:

sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl reload caddy
sudo journalctl -u caddy -f

Test both domains:

curl -I https://v.shishishi3.com
curl -I https://474769754.xyz

Expected results:

https://v.shishishi3.com -> 200
https://474769754.xyz -> 404

A 404 on the root of the subscription domain is normal, because we intentionally do not expose the panel there.

Troubleshooting

If you get unexpected eof while reading here, jump to Caddy TLS EOF.

6. Basic Xboard Configuration

After logging into the panel, start by changing:

Site name: your own name
Site URL: your panel domain or subdomain, such as https://v.shishishi3.com
Subscription URL: your subscription domain or subdomain, such as https://474769754.xyz

Recommended security settings:

Admin path: change it to a random path
Open registration: enable only when ready, or keep it closed for private use
Email verification: enabled
Login captcha: enabled
Registration captcha: enabled
Subscription anti-leech: enabled

If the panel only offers one URL field, use:

https://v.shishishi3.com

If it provides a separate subscription URL field, use:

https://474769754.xyz

7. SMTP Mail Configuration

If the panel is for personal use only, you may not need this section. But if you want email verification or password reset, set up SMTP properly.

Cloudflare Email Routing can receive and forward mail, but it is not an SMTP sending server.

This guide uses Brevo’s free SMTP:

SMTP host: smtp-relay.brevo.com
SMTP port: 587
Encryption: TLS
SMTP username: the SMTP Login provided by Brevo
SMTP password: your Brevo SMTP key
From address: noreply@474769754.xyz

A few details matter:

Port 587 means TLS or STARTTLS, not SSL/TLS.
Addresses like ac96b9001@smtp-brevo.com are SMTP login usernames, not the visible sender address.
The sender address can be noreply@474769754.xyz, but it must be verified in Brevo.
Cloudflare Email Routing can receive Brevo’s verification message for noreply@474769754.xyz.

Cloudflare DNS allows only one SPF record. If Cloudflare already gives you:

v=spf1 include:_spf.mx.cloudflare.net ~all

and Brevo asks for:

v=spf1 include:spf.brevo.com ~all

merge them into:

v=spf1 include:_spf.mx.cloudflare.net include:spf.brevo.com ~all

If verification mail is not arriving, inspect the Xboard logs:

cd /opt/Xboard
sudo docker compose logs --tail=160 xboard
sudo grep -R "SMTP\|Brevo\|SendEmailJob\|Unauthorized" storage/logs/

Troubleshooting

If you see 525 5.7.1 Unauthorized IP address in the logs, jump to SMTP unauthorized IP.

8. Plan Design

Adjust your plans to fit your actual node machines and bandwidth. The examples below are simply the way I structured mine.

If the US node has plenty of traffic while the Hong Kong node is relatively limited, a reasonable split is:

US San Jose: main node, 1x
Hong Kong: backup node, 5x / 8x / 10x

Example low-cost plan:

Plan name: Vela Basic
Monthly: ¥3.9
Yearly: ¥36
Traffic: 50 GB / month
Speed cap: 300 Mbps
Devices: 3
US: 1x
HK: 5x or higher

If the pricing is closer to:

Monthly: ¥3
Yearly: ¥30

then a more conservative package may be:

Traffic: 40 GB / month
Speed cap: 200 Mbps
Devices: 2
HK: 8x

Example plan description template:

## Plan Details

- Traffic: {{transfer}} GB
- Speed limit: {{speed}} Mbps
- Concurrent devices: {{devices}}
- Primary node: San Jose, US West Coast
- Backup node: high-multiplier Hong Kong node

## Service Notes

1. Traffic resets {{reset_method}}
2. Supports common iOS, Android, Windows, and macOS clients
3. The San Jose node is the primary route, with a 10 Gbps uplink and a real-world peak around 1.8 Gbps to 6 Gbps
4. The Hong Kong node is a backup route and uses a higher multiplier because monthly traffic is limited
5. Best suited for browsing, social media, AI tools, and light streaming
6. BT/PT, mining, scanning, spam, and long-term bandwidth abuse are not allowed
7. 24/7 technical support

9. Create HY2 Nodes

In the Xboard backend, choose:

Hysteria

Example Hong Kong node:

Node name: HK-HY2-01
Base multiplier: 5
Traffic limit: 0
Tags: HK, HY2
Permission group: Default
Node address: hk.474769754.xyz
Connect port: 8443
Service port: 8443
Protocol version: V2
Obfuscation: enabled
Obfuscation implementation: Salamander
Obfuscation password: random
SNI: hk.474769754.xyz
Allow insecure: disabled
ECH: disabled
Upload bandwidth: set to the real line capacity
Download bandwidth: set to the real line capacity
Bind server: independent deployment or bind to the matching server

Example US node:

Node name: US-HY2-01
Base multiplier: 1
Node address: us.474769754.xyz
Connect port: 8443
Service port: 8443
SNI: us.474769754.xyz

Things to keep straight:

ECH is not your TLS certificate.
HY2 does not sit behind Caddy.
Caddy cannot reverse_proxy ordinary HY2 UDP traffic.
Node domains must stay gray-clouded.

This next screenshot corresponds to the transport-layer settings, including connect port, service port, obfuscation, SNI, and ECH:

If you want to configure port hopping and server binding, this is the relevant part of the interface:

10. Install Xboard-Node

You can go straight to the Xboard backend, open Node Management -> Add Server, copy the generated xboard-node installation command, and run it on the node server.

Once installation is done, the backend should show the server online with resource and load information.

11. Configure HY2 Certificates

HY2 requires TLS certificates.

Troubleshooting

If you are already seeing protocol "hysteria" requires TLS certificate files, jump to Server online but node not running.

If the node server has nothing listening on port 80, you can issue a certificate directly:

sudo apt-get install -y certbot

sudo certbot certonly --standalone \
  -d hk.474769754.xyz \
  --agree-tos \
  -m admin@474769754.xyz \
  --non-interactive

If Caddy or nginx is already bound to port 80 on that machine, stop it first, issue the certificate, then start it again:

sudo systemctl stop caddy
sudo certbot certonly --standalone -d hk.474769754.xyz --agree-tos -m admin@474769754.xyz --non-interactive
sudo systemctl start caddy

The resulting certificate files are:

/etc/letsencrypt/live/hk.474769754.xyz/fullchain.pem
/etc/letsencrypt/live/hk.474769754.xyz/privkey.pem

Copy them into the Xboard-Node directory:

sudo mkdir -p /etc/xboard-node/certs

sudo install -m 0644 /etc/letsencrypt/live/hk.474769754.xyz/fullchain.pem \
  /etc/xboard-node/certs/hk.fullchain.pem

sudo install -m 0600 /etc/letsencrypt/live/hk.474769754.xyz/privkey.pem \
  /etc/xboard-node/certs/hk.privkey.pem

Edit the config:

sudo nano /etc/xboard-node/config.yml

Add this at the top level:

cert:
  cert_mode: file
  domain: hk.474769754.xyz
  cert_file: /etc/xboard-node/certs/hk.fullchain.pem
  key_file: /etc/xboard-node/certs/hk.privkey.pem

cert: must stay at the top level. Do not indent it under panel: or machine:.

Restart the service:

sudo systemctl restart xboard-node
sudo journalctl -u xboard-node --since "2 minutes ago" --no-pager

Check the UDP listener:

sudo ss -lunp | grep 8443

You should see 8443/udp.

The US node is the same idea. Just replace the domain and file paths with:

us.474769754.xyz
/etc/xboard-node/certs/us.fullchain.pem
/etc/xboard-node/certs/us.privkey.pem

12. Firewall and Security Groups

Open these ports on the panel server:

80/tcp
443/tcp
22/tcp

Open these on the node server:

8443/udp
22/tcp

If you are using port hopping:

20000-29999/udp

Example ufw rules:

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 8443/udp
sudo ufw enable
sudo ufw status

If your cloud provider has security groups, open the same UDP ports there too. Opening only the system firewall is not enough.

13. HY2 Port Hopping

Hysteria2 supports port hopping. A practical range is:

20000-29999/udp

The Xboard node settings would look like:

Connect port: 20000-29999
Service port: 8443
Hop interval: 30

On the node server, redirect the port range to the real listening port:

sudo iptables -t nat -A PREROUTING -p udp --dport 20000:29999 -j REDIRECT --to-ports 8443

Persist the rule:

sudo apt-get install -y iptables-persistent
sudo netfilter-persistent save

Check both iptables and the UDP listener:

sudo iptables -t nat -S PREROUTING | grep 8443
sudo ss -lunp | grep 8443

During rollout, it is safer to keep both open:

8443/udp
20000-29999/udp

Once everything is stable, you can keep only the hopping range.

Troubleshooting

If you are worried that ss does not show the full port range, jump to UDP port range not visible.

14. User Subscriptions and Clients

The usual flow is:

Create a plan -> create a user -> attach the plan -> copy the subscription link -> import into the client

If the imported client shows only DIRECT and no nodes, the common reasons are:

The user does not have a valid plan.
The plan’s permission group does not include the node’s permission group.
The node is marked hidden.
The node service is not running.
The client does not support Hysteria2.
The subscription template does not include HY2.

Inspect the subscription payload directly:

curl -L "https://474769754.xyz/s/your-token"

If the output does not contain:

hysteria
hy2
hk.474769754.xyz
US-HY2-01

then Xboard is not distributing the node yet, and the first things to check are plans and permission groups.

If the payload does contain nodes but the client still does not show them, switch to a client or template that supports HY2, such as sing-box, Clash Meta, or Mihomo.

15. Pre-Launch Checklist

Before enabling public registration, I recommend confirming all of the following:

SMTP test mail works
Email verification enabled
Registration captcha enabled
Login captcha enabled
Admin path changed to a random one
Subscription domain only exposes /s/*
Plan permission groups are correct
Node multipliers are correct
HK node uses a higher multiplier
Cloud security groups expose only necessary ports

Suggested trial policy:

Free signup plan: disabled
or 1 GB / 1 day
Do not allocate too much Hong Kong traffic to cheap plans

16. Final Hardening

The final port exposure I recommend is:

Panel server:

80/tcp
443/tcp
22/tcp

Node server:

22/tcp
20000-29999/udp

If you are not using port hopping:

22/tcp
8443/udp

Caddy should expose only:

Full reverse proxy for the panel domain
Only /s/* and required API paths on the subscription domain

Backend settings:

Open registration: only when needed
Email verification: enabled
Captcha: enabled
Admin path: random
Trial quota: extremely low or disabled

Node strategy:

US as the primary route, 1x
HK as the backup route, 5x / 8x / 10x

At that point you are no longer in a test setup. You have something you can reasonably expose and operate.

Pitfalls

Broken apt source

If you run into:

E: The repository 'https://packagecloud.io/ookla/speedtest-cli/ubuntu noble Release' does not have a Release file.

that means the Ookla speedtest apt source does not support the current system release. Disable it first:

grep -R "packagecloud.io/ookla" /etc/apt/sources.list /etc/apt/sources.list.d/

Suppose the output is:

/etc/apt/sources.list.d/ookla_speedtest-cli.list

Disable it like this:

sudo mv /etc/apt/sources.list.d/ookla_speedtest-cli.list \
  /etc/apt/sources.list.d/ookla_speedtest-cli.list.disabled

sudo apt-get update

This was a real issue in my own deployment. Any installer that calls apt-get update can get stuck behind that broken source.

Fake-IP interference

If your machine is running a proxy or TUN, 198.18.x.x fake IP results are normal. Use a public DNS resolver directly, or temporarily disable the proxy while checking records.

Caddy TLS EOF

Typical symptom:

curl: (35) TLS connect error: unexpected eof while reading

Check with:

nslookup domain 1.1.1.1
sudo caddy validate --config /etc/caddy/Caddyfile
sudo journalctl -u caddy -f

The common causes are:

DNS is not pointing at the server.
The Caddyfile never made it onto the server.
Caddy was not reloaded.
Ports 80 and 443 are not actually open.

Subscription 404

If the response headers look like:

HTTP/2 404
server: Caddy
content-length: 9

then Caddy is blocking the request. Make sure the Caddyfile includes:

handle /s/* {
	reverse_proxy 127.0.0.1:7001
}

SMTP unauthorized IP

Check the logs:

sudo grep -R "SendEmailJob\|SMTP\|Unauthorized" /opt/Xboard/storage/logs/

If you find:

525 5.7.1 Unauthorized IP address

then Brevo is rejecting the outbound IP address. Check the IP used by the Xboard container:

cd /opt/Xboard
sudo docker compose exec -T xboard curl -s https://ifconfig.me

Add that IP to Brevo’s Authorized IP addresses.

Server online but node not running

Inspect the node logs:

sudo journalctl -u xboard-node -n 120 --no-pager

If you see:

requires TLS certificate files

then HY2 is missing certificate configuration. Go back to Section 11 and add the cert: block correctly.

Node running but idle

This is normal. It simply means the node process is up, but no client is actively using it at the moment.

UDP port range not visible

Check:

sudo ss -lunp | grep 8443

If you are using port hopping, it is normal that ss shows only 8443, because the process is actually listening on that single backend port. Use iptables to inspect the forwarding rule:

sudo iptables -t nat -S PREROUTING | grep 20000

Also remember to open 20000-29999/udp in your cloud security group.

Cannot delete a plan

If the backend says that the plan cannot be deleted because orders still reference it, do not force-delete it.

A safer pattern is:

Disable the plan
Hide the plan
Close purchases
Rename it to Test-Deprecated

Keeping historical order references intact is normal in production systems.

References

From Disk to Files: Understanding GPT, APFS, Containers, and Volumes on macOS

Sun, 21 Jun 2026 00:00:00 GMT

The first time you inspect storage on macOS, several terms tend to blur together: disk, partition, container, volume, file system, and mount point. They all sound like parts of a drive, but they live at different layers.

The main source of confusion is that older storage layouts often looked like “one partition equals one volume.” Modern macOS uses APFS by default, and APFS adds a container layer between partitions and volumes. A single APFS container can hold multiple volumes, and those volumes share the same pool of free space.

For a typical macOS system disk, the path looks like this:

Physical disk
  -> GPT partition table
  -> Partition
  -> APFS container
  -> APFS volumes
  -> Files and directories

For a simple exFAT external drive, the structure is usually flatter:

Physical disk
  -> GPT / MBR partition table
  -> Partition
  -> exFAT file system volume
  -> Files and directories

Once these two paths are clear, names like Macintosh HD, Macintosh HD - Data, Preboot, Recovery, VM, /dev/disk0, /dev/disk0s2, and disk3 stop looking like a random pile of devices.

Physical Disks

A physical disk is the actual storage device: the internal SSD, an external hard drive, a USB drive, an SD card, or an NVMe drive.

On macOS, it may appear as:

/dev/disk0
/dev/disk4

These names are not stable identities. Plugging in devices, rebooting, or mounting disk images can change the numbering. When you want to inspect the current layout, use:

diskutil list

At the lowest level, a disk is a sequence of addressable blocks. The partition table describes which ranges of those blocks belong to which partitions.

GPT: The Partition Map

GPT is the partition table format commonly used by modern macOS disks. It does not manage files, and it does not know where your documents, photos, or apps are. It only records how the disk is divided.

GPT usually records:

Where a partition starts.
Where a partition ends.
What type the partition is.
The partition GUID.
The partition name.

So GPT is a disk-level map. It tells the system “this area is an EFI partition” and “that area is an APFS partition,” but it does not manage the files inside those areas.

MBR still appears on older devices and in some compatibility scenarios. For current Mac system disks and most modern external disks, GPT is the more common layout.

Partitions

A partition is a continuous range of space on a disk.

On macOS, names often look like this:

disk0      the whole disk
disk0s1    partition 1
disk0s2    partition 2

A partition can contain many different things:

APFS
HFS+
exFAT
FAT32
NTFS
Linux ext4
EFI System Partition

The older mental model is often:

one partition = one file system = one volume

A normal exFAT USB drive often works like this:

GPT partition
  -> exFAT file system
  -> volume named DATA
  -> files

In that situation, partition and volume appear almost identical. APFS is different.

File Systems

A file system defines how files are stored, how directories are organized, how permissions are recorded, and how free space is managed.

Common file systems include:

File system	Common platform	Notes
APFS	macOS, iOS, iPadOS	Apple’s modern file system, with space sharing, snapshots, clones, encryption, and more
HFS+	Older macOS versions	Apple’s pre-APFS file system
NTFS	Windows	Common for Windows system drives
exFAT	Cross-platform	Useful for USB drives and external disks shared between macOS and Windows
FAT32	Older devices	Very compatible, but limited to 4 GB per file
ext4	Linux	Common Linux file system
Btrfs	Linux	Supports modern features such as snapshots and checksumming
XFS	Linux	Common for large files and server workloads

The file system affects file naming rules, maximum file size, permissions, snapshots, case sensitivity, journaling, copy-on-write behavior, and more.

On current macOS, APFS is the most important file system to understand. It is not just a format; it also brings containers, shared space, volume groups, and snapshots into daily storage management.

APFS Containers

The key APFS concept is the container.

A GPT partition can be used as APFS physical storage. Inside that storage, macOS creates an APFS container. The container can then hold multiple APFS volumes.

A typical layout looks like this:

Physical disk disk0
  -> GPT partition disk0s2
    -> APFS Container disk3
      -> Macintosh HD
      -> Macintosh HD - Data
      -> Preboot
      -> Recovery
      -> VM

Here, disk3 is not another physical disk. It is a synthesized APFS container device created by macOS.

The major benefit of an APFS container is space sharing. If a 1 TB APFS container holds two volumes, and volume A uses 200 GB while volume B uses 100 GB, the remaining space is not permanently assigned to either volume. It remains free space inside the container and can be allocated to any volume as needed.

That is very different from traditional partitioning. If you split a disk into two fixed 500 GB partitions, unused space in partition A is not automatically available to partition B. APFS containers are more flexible: multiple volumes share the same free space pool.

APFS volumes can still have boundaries when needed. You can set a reserve size to guarantee space, or a quota size to limit how much a volume can allocate.

Volumes

A volume is the logical storage unit that the operating system can mount, name, display, and use for files.

In Finder, names like these are usually volumes:

Macintosh HD
Macintosh HD - Data
Backup
MyDisk

On the command line, external volumes are usually mounted under:

/Volumes/Backup

Windows drive letters such as C: and D: can also be understood as volumes. On Linux, paths like /mnt/data or /media/xxx are mount points where volumes become accessible.

So a volume is the usable operating-system-level unit. A partition is a continuous range on a disk. An APFS container is the shared space pool that holds multiple APFS volumes.

Mounting

Mounting means attaching a volume to the operating system’s directory tree. If an external volume is named Backup, macOS usually mounts it at:

/Volumes/Backup

When a volume is not mounted, it may still exist and its file system may still be intact, but Finder will not show it and you cannot access its files through a normal path.

Useful commands include:

diskutil mount /dev/disk4s2
diskutil unmount /dev/disk4s2
diskutil unmountDisk /dev/disk4

unmount detaches a specific volume or partition. unmountDisk detaches all unmountable volumes on a disk.

Why Macintosh HD and Macintosh HD - Data Are Separate

Starting with macOS Catalina, Apple separated system files from user data. Roughly:

Macintosh HD          system volume
Macintosh HD - Data   data volume

The system volume stores macOS system content. On modern macOS, it is read-only. Starting with macOS Big Sur, it became a Signed System Volume, meaning macOS verifies the integrity of system content. If verification fails, the boot process may stop or require macOS to be reinstalled.

The data volume stores user files, app data, and writable configuration. macOS uses APFS Volume Groups and firmlinks to present the system volume and data volume as one coherent system.

So Finder gives you the feeling of one unified disk, but underneath it, two volumes have different responsibilities:

The system volume keeps operating system content stable and verifiable.
The data volume stores user and app-generated writable data.

That is why Macintosh HD - Data should not be treated as a duplicate disk. It is part of the modern macOS file management model.

APFS Volume Groups

An APFS Volume Group is a set of related APFS volumes.

The most common pair is:

Macintosh HD
Macintosh HD - Data

Together, they form the system volume group. This design lets macOS do two things at the same time:

Keep system content isolated, read-only, and verifiable.
Keep user data writable and available at familiar paths.

The user sees one system. Internally, macOS knows which content belongs to the system volume and which content comes from the data volume.

Preboot, Recovery, and VM

An APFS system container often contains several system-managed volumes:

Preboot: Stores information needed to boot APFS system volumes.
Recovery: Stores the recovery environment for reinstalling macOS, Disk Utility, Terminal, and system recovery.
VM: Stores virtual memory, swap files, and sleep-related data.
Update: Appears on some macOS versions and participates in system updates.

These volumes are managed by macOS and should not be deleted manually. Preboot and Recovery may look unimportant during normal use, but they matter when the system needs to boot or recover.

Formatting, Erasing, Deleting Volumes, and Deleting Partitions

Disk Utility uses several similar-looking operations, but they happen at different layers.

Formatting usually means creating a new file system on a partition or volume. For example:

diskutil eraseVolume ExFAT DATA /dev/disk4s2

This creates an exFAT file system on /dev/disk4s2 and names the volume DATA.

Erasing a whole disk can be much more destructive. If you select an entire physical disk, macOS may rebuild the partition table, create new partitions, create a file system, and create a volume:

diskutil eraseDisk ExFAT DATA GPT /dev/disk4

That affects the entire disk and removes the old partition layout.

Deleting an APFS volume is also different from deleting an APFS partition.

After deleting an APFS volume, the freed space returns to the APFS container:

APFS Container
  -> Volume B
  -> Free space inside container

After deleting an APFS partition, the space returns to the GPT layer as unallocated disk space:

GPT
  -> EFI
  -> Free Space
  -> Other Partition

This explains a common surprise: deleting an APFS volume may not create visible unallocated space in the partition map. You removed a volume inside the container, not the GPT partition itself.

Snapshots

APFS supports snapshots. A snapshot records the state of a file system at a point in time. It does not immediately copy every file.

APFS uses copy-on-write. When a snapshot is first created, it uses very little additional space. Later, when files change, old blocks are kept so the snapshot can still see the previous state.

This is part of what makes Time Machine, system update rollback, and recovery workflows efficient.

Snapshots can still consume space. If you delete files but free space does not seem to return immediately, local snapshots are one of the things worth checking, along with Trash, caches, and cloud sync behavior.

EFI Partition

GPT disks often include an EFI System Partition, also called ESP. It usually uses FAT32 and stores UEFI boot-related files.

macOS may create an EFI partition even on some external disks, even if that disk is not actively used for booting. Do not casually delete the EFI partition on a system disk. It is quiet most of the time, but it belongs to the boot chain.

RAID and Volumes

RAID combines multiple disks into a logical storage device. For example:

RAID 0: Striping for performance, no redundancy.
RAID 1: Mirroring for redundancy.
RAID 5: Redundancy with parity.
RAID 10: Mirroring plus striping.

After RAID is created, the operating system usually sees a new logical disk. That logical disk can still contain a partition table, partitions, file systems, and volumes.

RAID does not replace the file system. It operates below it by combining physical disks into a logical device.

Reading diskutil Output

On macOS, these clues help decode storage output:

Output	Usually means
`/dev/disk4`	A whole disk, which may be physical or synthesized
`/dev/disk4s2`	Partition 2 on disk4
`GUID_partition_scheme`	The disk uses GPT
`EFI`	EFI System Partition
`Apple_APFS`	A partition used as APFS physical storage
`APFS Container`	APFS container
`APFS Volume`	A volume inside an APFS container
`Free Space`	Unallocated space at the GPT layer

This command is especially useful for APFS:

diskutil apfs list

It shows APFS containers, volumes, volume groups, snapshots, and related details more clearly than the generic disk list.

The Core Idea

The most important macOS takeaway is:

APFS is not simply "one partition, one volume."
It creates a container inside a partition, then manages multiple shared-space volumes inside that container.

Once that is clear, Macintosh HD, Macintosh HD - Data, Preboot, Recovery, and VM no longer look like mysterious extra drives. They are pieces of the storage model macOS uses to keep the system reliable, recoverable, and easier to manage.

References

Deploying a QQ Bot on Linux with NapCat, NoneBot2, GsCore, and Caddy

Fri, 19 Jun 2026 00:00:00 GMT

I wanted a QQ bot setup on Linux that was not just “working for now,” but stable enough to live with. The stack I ended up with was NapCat + NoneBot2 + GsCore, with Caddy in front for HTTPS and reverse proxying. The overall design is straightforward. The actual deployment, though, was shaped by a series of very real and very ordinary problems: terminal encoding, missing CLI tools, local-only bindings, TLS validation, and even something as basic as forgotten DNS records.

This post turns that whole session into a practical guide you can follow from scratch. More importantly, it includes the failures along the way, because those are usually the parts that save the most time later.

The Final Architecture

This is the message path we ended up with:

QQ / group message
  -> NapCat
  -> NoneBot2
  -> nonebot-plugin-genshinuid
  -> GsCore
  -> actual business plugin (such as GenshinUID)

For admin access from the web, we added another layer:

Browser
  -> Caddy (HTTPS / reverse proxy)
  -> NapCat WebUI / GsCore WebConsole

Two design decisions mattered a lot here:

Treat the bot message path and the admin panel path as separate concerns.
Avoid exposing 6099 and 8765 directly to the public internet when a reverse proxy can keep them behind localhost.

What Each Piece Does

NapCat: the protocol side and QQ login layer.
NoneBot2: the bot framework itself, responsible for receiving OneBot events and dispatching logic.
GsCore: the Sayu core layer that provides the plugin ecosystem and a unified connection model.
nonebot-plugin-genshinuid: the official NoneBot2-side plugin used to connect to GsCore.
Caddy: the HTTPS and reverse proxy layer for safely exposing the admin panels.

Environment Assumptions

This guide assumes:

You are on Ubuntu, Debian, or a similar Linux system.
You have root or sudo access.
The server has internet access.
You have a QQ account ready for bot login.
You have a domain name and plan to manage DNS with Cloudflare.

The directory layout in this guide looks like this:

~/qqbot        # NoneBot2 project
~/gsuid_core   # GsCore installation

Step 1: Install NapCat

NapCat provides a Linux installer, and the straightforward way to start is:

curl -o napcat.sh https://nclatest.znin.net/NapNeko/NapCat-Installer/main/script/install.sh
bash napcat.sh --tui

After installation, you can usually re-enter its TUI with:

sudo napcat

Problem 1: NapCat Shell showed garbled text

The first thing we saw was not a clean UI, but broken characters like ~@~A and ~M~U. This turned out not to be a NapCat bug at all. It was a classic locale and terminal issue.

Start by checking:

locale
echo $LANG
echo $TERM

If the environment is not using UTF-8, fix it temporarily before launching NapCat:

export LANG=zh_CN.UTF-8
export LC_ALL=zh_CN.UTF-8
export TERM=xterm-256color
sudo napcat

If the server does not have the locale generated yet, install it:

sudo apt update
sudo apt install -y locales
sudo locale-gen zh_CN.UTF-8
sudo update-locale LANG=zh_CN.UTF-8

If you prefer a neutral UTF-8 setup instead of a Chinese locale, C.UTF-8 works well too:

export LANG=C.UTF-8
export LC_ALL=C.UTF-8
export TERM=xterm-256color
sudo napcat

Log in to NapCat WebUI

NapCat’s WebUI typically listens on port 6099. Once it starts, check the logs for the access URL and token, scan the QQ login QR code, and set a proper WebUI password.

Step 2: Create the NoneBot2 Project

Create a Python virtual environment first:

mkdir -p ~/qqbot
cd ~/qqbot
python -m venv .venv --prompt nonebot2
source .venv/bin/activate

Install the base dependencies:

pip install "nonebot2[fastapi]"
pip install nonebot-adapter-onebot

Create .env:

HOST=127.0.0.1
PORT=8080
ONEBOT_ACCESS_TOKEN=replace-this-with-a-long-random-token
COMMAND_START=["/"]
COMMAND_SEP=["."]

Create bot.py:

import nonebot
from nonebot.adapters.onebot.v11 import Adapter as OneBotV11Adapter

nonebot.init()

driver = nonebot.get_driver()
driver.register_adapter(OneBotV11Adapter)

if __name__ == "__main__":
    nonebot.run()

Test that it starts:

source .venv/bin/activate
python bot.py

Step 3: Connect NapCat to NoneBot2

In NapCat, create a new WebSocket client network connection and point it to:

ws://127.0.0.1:8080/onebot/v11/ws

Use the same token value as ONEBOT_ACCESS_TOKEN in your .env file.

If you get a 403, the first thing to verify is the token value. A mismatch there is by far the most common cause.

Step 4: Install GsCore

According to the official GsCore docs, install it as a separate project next to your bot:

cd ~
git clone https://github.com/Genshin-bots/gsuid_core.git --depth=1 --single-branch
cd gsuid_core

The official docs recommend uv:

uv python install 3.13
uv sync --python 3.13
uv run python -m ensurepip

Start GsCore:

uv run core

On first startup, it will generate:

~/gsuid_core/data/config.json
~/gsuid_core/data/core_config.json

Step 5: Connect GsCore to NoneBot2

The official NoneBot2-side connector for GsCore is nonebot-plugin-genshinuid.

Problem 2: `nb` was not found

We initially followed the official pattern and ran:

nb plugin install nonebot-plugin-genshinuid

That failed with:

-bash: nb: command not found

Nothing was wrong with the project. The issue was simply that nb-cli was not installed. The nb command is not part of Python itself; it belongs to the NoneBot CLI.

There are two reasonable fixes.

Fix A: install `nb-cli`

cd ~/qqbot
source .venv/bin/activate
pip install nb-cli
nb plugin install nonebot-plugin-genshinuid

Fix B: install the plugin directly with `pip`

If you already manage your bot with a hand-written bot.py, direct installation is often simpler:

cd ~/qqbot
source .venv/bin/activate
pip install nonebot-plugin-genshinuid

That second route is the one I would recommend in this setup. It is shorter and avoids pulling in an extra layer unless you actually want the CLI workflow.

Add GsCore settings to the NoneBot `.env`

Append these values to your existing .env:

gsuid_core_ws_token=123
gsuid_core_host=localhost
gsuid_core_port=8765
gsuid_core_botid=NoneBot2

Configure `config.json` on the GsCore side

Edit:

~/gsuid_core/data/config.json

At minimum, make sure these fields are set:

{
  "HOST": "localhost",
  "PORT": "8765",
  "masters": ["your-qq-number"],
  "WS_TOKEN": "123",
  "TRUSTED_IPS": ["127.0.0.1"]
}

Two details matter here:

WS_TOKEN must match gsuid_core_ws_token in the NoneBot .env
masters should include your own QQ number, or a lot of core admin commands will not work for you later

Step 6: Install the Actual Business Plugin

GsCore by itself is the platform layer. The actual bot features come from business plugins.

Once your account is listed in masters, you can install one from chat:

core安装插件GenshinUID

If you prefer manual installation:

cd ~/gsuid_core/plugins
git clone -b v4 https://github.com/KimigaiiWuyi/GenshinUID.git --depth=1 --single-branch

Restart GsCore once the plugin is installed.

Step 7: Access the GsCore Admin Panel

GsCore’s admin backend is the Web Console, usually available at:

http://127.0.0.1:8765/app

That is enough if you are accessing it locally.

Problem 3: public access returned 502

When we tried to access the admin panel from the public internet, we ran into HTTP ERROR 502. The clue came from GsCore itself:

WebConsole挂载于本地, 如想外网访问请修改data/config.json中host为0.0.0.0!

That message means the web console is bound to localhost only, which is why outside access fails. The most direct fix is to change:

"HOST": "localhost"

to:

"HOST": "0.0.0.0"

That said, exposing 8765 directly is not the design I would recommend. A better pattern is to keep GsCore bound to localhost and let a reverse proxy expose it safely.

Step 8: Put Caddy in Front of NapCat and GsCore

Operationally, it is cleaner not to expose 6099 and 8765 to the public internet at all. The safer layout is:

Keep NapCat WebUI and GsCore WebConsole bound to localhost
Expose only 80 and 443
Let Caddy handle HTTPS and reverse proxying

Install Caddy

On Ubuntu or Debian, one clean installation route is:

sudo apt update
sudo apt install -y debian-keyring debian-archive-keyring apt-transport-https curl
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/gpg.key' | sudo gpg --dearmor -o /usr/share/keyrings/caddy-stable-archive-keyring.gpg
curl -1sLf 'https://dl.cloudsmith.io/public/caddy/stable/debian.deb.txt' | sudo tee /etc/apt/sources.list.d/caddy-stable.list
sudo apt update
sudo apt install -y caddy

Recommended upstream layout

Keep the backend services local:

NapCat WebUI -> 127.0.0.1:6099
GsCore WebConsole -> 127.0.0.1:8765

Then configure /etc/caddy/Caddyfile like this:

{
	email yourmail@example.com
}

napcat.example.com {
	reverse_proxy 127.0.0.1:6099
}

gscore.example.com {
	reverse_proxy 127.0.0.1:8765
}

Format, validate, and reload:

sudo caddy fmt --overwrite /etc/caddy/Caddyfile
sudo caddy validate --config /etc/caddy/Caddyfile
sudo systemctl restart caddy
sudo systemctl status caddy

Step 9: Problem 4 — Caddy could not obtain certificates

Caddy itself started just fine, but the logs kept showing challenge failed. The root cause was not in Caddy at all. I had forgotten to add the DNS records in Cloudflare.

That type of failure usually comes down to one of these:

The domain does not actually resolve to this server
Ports 80 and 443 are not publicly reachable
Another service is already occupying 80 or 443
DNS changes have not propagated yet

Useful troubleshooting commands

Check recent Caddy logs:

sudo journalctl -u caddy -n 80 --no-pager

Check DNS resolution:

dig +short napcat.your-domain.com A
dig +short gscore.your-domain.com A

Check what is listening:

ss -lntp | grep ':80\|:443'

Check the firewall:

sudo ufw status

If the DNS record simply does not exist in Cloudflare, ACME validation obviously cannot succeed. It is a basic mistake, but also an extremely common one.

If the admin panels are mostly for your own use, I would tighten things up this way:

Do not expose 6099 or 8765 directly to the internet
Expose only 80 and 443
Keep NapCat and GsCore bound to localhost
Put Caddy in front of them
Keep strong passwords and tokens on the panels themselves
Add IP allowlisting or another auth layer if you can

One point is worth stating explicitly: your email address is not an authentication mechanism. It is only a contact address for certificate issuance. The things that actually protect your admin panels are HTTPS, reverse proxy boundaries, panel passwords, tokens, and whether you avoided exposing the raw upstream ports.

Recommended Startup Order

Once everything is deployed, I recommend starting and debugging in this order:

NapCat
NoneBot2
GsCore
business plugin
Caddy

And when something breaks, trace the same chain in order:

Is QQ login working?
-> Is the OneBot WebSocket connected?
-> Is NoneBot running?
-> Is GsCore connected?
-> Is the plugin loaded?
-> Is the admin panel reachable?
-> Are HTTPS, DNS, and Caddy behaving correctly?

The Four Things Most Worth Remembering

1. Garbled TUI output usually means the terminal environment is wrong

Check LANG, LC_ALL, and TERM before assuming the software is broken.

2. A missing `nb` command usually just means `nb-cli` is not installed

And if you are already managing your bot with a custom bot.py, direct pip install may be the simpler path anyway.

3. If a backend is bound to localhost, public access is supposed to fail

Once you see localhost bindings or “mounted locally” warnings, stop guessing at public-network issues and fix the binding model first.

4. TLS failures are often not “proxy problems” at all

Even in a stack with reverse proxies, certificates, and HTTPS, the most common failure point is still the boring layer underneath: DNS.

References

Closing Thoughts

By the end of this deployment, the biggest takeaway was not “the bot is finally installed.” It was that the hard part of this kind of work is rarely the install commands themselves. What determines whether the setup stays pleasant later is whether the boundaries are clear: whether the protocol layer is separated from the framework, whether admin surfaces are exposed carelessly, whether the domains really point where you think they do, and whether the logs tell you where the failure actually is.

Once those boundaries are in place, NapCat + NoneBot2 + GsCore + Caddy is a very workable combination. It is not the lightest stack, and it is not the flashiest one either, but it is clear, stable, and perfectly suited to long-term maintenance.

Rebuilding My Personal Server Framework

Tue, 16 Jun 2026 00:00:00 GMT

While reorganizing my personal servers, the main thing I wanted to solve was not “how do I run a few more services?” It was how to put a growing pile of services back behind clear boundaries.

HomeLab services tend to pile up naturally: a blog, a start page, monitoring, admin panels, personal projects, bots, Minecraft servers, and all kinds of temporary experiments. At first, each one is just something I want to “get running.” After a while, entry points, domains, databases, ports, and backup strategies start tangling together. When something breaks, it becomes hard to tell which layer failed. When I want to migrate, it becomes hard to move only one part away.

Looking back, the April version was more like a migration draft: it mapped out the roles of HK Main, the Mac mini, proxy nodes, and each stack. This version is closer to the current scene: which domains are actually in use, which services have become long-lived, and which entry points exist for friends or for my own maintenance.

So the goal of this framework is straightforward: use one public entry path, split services by responsibility, keep sensitive components inside the private network, put static content on managed hosting whenever possible, and leave the Mac mini for services that need long-running processes, persistence, or private-network access.

Overall Idea

The current architecture follows a “Cloudflare as the DNS/access layer + HK Main as the public entry point + Mac mini for local core services” model.

flowchart LR
    User["Public users / friends"] --> CF["Cloudflare DNS / CDN"]
    CF --> Pages["Cloudflare Pages<br/>Astro Blog and static content"]
    CF --> HK["HK Main<br/>frps only"]
    HK --> FRPC["Mac mini<br/>frpc"]
    FRPC --> NPM["Nginx Proxy Manager"]

    NPM --> Monitor["monitor-stack<br/>Komari"]
    NPM --> Home["homepage-stack<br/>Homepage"]
    NPM --> Private["private-services-stack<br/>Nextcloud / Vault"]
    NPM --> VPN["vpn-stack<br/>VPN download and config entry"]

    Friends["Trusted friends"] --> GameAccess["Tailscale first<br/>frp / domain fallback"]
    GameAccess --> Games["game-stack<br/>Game Server"]

    VPN --> Nodes["Proxy / VPN nodes<br/>connected as needed"]

The key idea is to separate “entry” from “business services.”

HK Main is only the public entry server. It runs frps, but it does not host databases, personal files, long-running business services, or proxy exit traffic. The real services run locally on the Mac mini inside OrbStack. frpc connects them to HK Main, and Nginx Proxy Manager (NPM) handles domain-based routing and reverse proxying.

The static blog still belongs on a hosted platform such as Cloudflare Pages. But homepage.shishishi3.com is no longer just a static home page; it is the HomeLab navigation and status entry point, so it now lives on the Mac mini as a long-running service. This keeps the static publishing surface and the private service surface from dragging each other down.

Server Roles

The Mac mini is the core host of this system. It has no public IP. Its job is to run long-lived services, databases, personal projects, bots, and game servers. Containers are split into Docker Compose stacks, each with its own config directory, data directory, and network boundary.

HK Main is the only host exposed as the public entry layer. It only runs frps, receives HTTP/HTTPS traffic after Cloudflare, and forwards it through frp to the Mac mini. The less this node does, the better, because it sits on the public side and should have as small an attack surface as possible.

Proxy or VPN nodes only handle network exit and access duties. They are not involved in Nextcloud, Homepage, Komari, game services, or other main services, and they are not mixed with HK Main. Nodes can come and go without shaking the entry layer or the local service layer.

This split makes the boundaries easier to reason about: if the entry breaks, check HK Main; if a service breaks, check the Mac mini; if file sync breaks, check Nextcloud; if monitoring looks strange, check Komari; if game access breaks, check gs and the related ports. I no longer need to dig through a pile of unrelated containers on the same machine.

Domain Plan

Domains are also split by responsibility. I no longer want the domain table to describe everything I might run someday; it should describe the entry points that are actually in use right now.

shishishi3.com hosts normal web services for myself and trusted visitors:

Subdomain	Service	Location
`komari.shishishi3.com`	Komari monitoring panel	`monitor-stack`
`homepage.shishishi3.com`	Homepage navigation and service entry	`homepage-stack`
`vpndl.shishishi3.com`	VPN download, config, or instruction entry	`vpn-stack`
`gs.shishishi3.com`	Game service entry	`game-stack`
`nc.shishishi3.com`	Nextcloud file and sync service	`private-services-stack`
`v.shishishi3.com`	Vault / private tools entry	`private-services-stack`

This version is more focused than the April plan: names like status, panel, bot, and demo are out of the current article instead of pretending to represent the live setup. They can come back later if needed, but a domain plan should reflect running services rather than reserving space for every possibility.

Infrastructure domains stay quiet and are only used for HK Main, frp, nodes, or internal management entries. Normal service entry points live under shishishi3.com; infrastructure entry points should not blend into business domains. This makes DNS, certificates, Cloudflare rules, and NPM proxy rules much easier to troubleshoot.

Public Entry

This setup does not use Cloudflare Tunnel as the main entry. Cloudflare handles DNS, CDN, WAF, and access control, while the real origin entry for local services is centralized on HK Main.

The web traffic path looks roughly like this:

User browser
  -> Cloudflare
  -> HK Main:80/443
  -> frps
  -> Mac mini frpc
  -> NPM
  -> Komari / Homepage / Nextcloud / Vault / VPN entry containers

TCP forwarding is configured like this:

HK Main:80  -> frps:8080 -> Mac mini frpc -> NPM:80
HK Main:443 -> frps:8443 -> Mac mini frpc -> NPM:443

frps only forwards traffic. It does not process business requests on HK Main. TLS transport is enabled between frpc and frps; NPM handles domain routing, reverse proxying, and certificate management. Backend services do not expose ports directly to the public internet. They only join Docker networks that NPM can reach.

Non-HTTP/HTTPS services are not forced through NPM. For example, gs.shishishi3.com is more like a friendly entry label for game services. The actual connection can depend on the game protocol, port, and audience: trusted friends use Tailscale first, and frp or restricted ports are only fallbacks when installing a client is not practical.

Stack Layout on the Mac mini

Services on the Mac mini are split into a few layers by responsibility. The names do not need to be pretty; the important thing is that the directory tells me what it owns.

edge-stack is the entry layer. It contains frpc and NPM. It brings public traffic into the local machine and forwards each domain to the right service. The NPM admin UI is only reachable from the LAN or Tailscale by default; it is not exposed directly to the public internet.

monitor-stack hosts Komari. Monitoring may look like just another panel, but it answers the question “do I need to get up and check something?” That deserves independent persistence and upgrades that are not tied to unrelated services.

homepage-stack hosts Homepage. It is an entry point for humans, not for machines: links, groups, service status, and common management addresses can live here. It can be exposed for my own use, but it should not accidentally expose every backend behind it.

private-services-stack hosts Nextcloud and private services such as v.shishishi3.com. The common thread is not the tech stack; it is data sensitivity. Files, sync data, vault data, and other private material need explicit volumes, backup plans, and access limits.

vpn-stack hosts the download, config, or instruction entry behind vpndl.shishishi3.com. It may not be complex, but it affects access, so it should stay separate from ordinary showcase projects. I do not want a casual page edit to affect someone else’s connection path.

game-stack hosts the game services behind gs.shishishi3.com. Game traffic is not mixed with the web reverse proxy. Access uses Tailscale first, with frp or restricted ports as fallbacks. Saves, mods, and config files are persisted separately and backed up regularly.

Temporary projects can still have a projects-stack, but they are no longer the center of this article. The core of the current architecture is keeping Komari, Homepage, the VPN entry, game services, Nextcloud, and private services stable.

After this split, every stack can be started, stopped, backed up, and migrated independently. When adding a new service, I first decide which layer it belongs to, then add it to that stack instead of throwing every container into the same flat space.

Security Strategy

The rule for HK Main is: entry only, no business services. It only opens 80, 443, the frps control port, and the necessary high forwarding ports. frps uses a strong token and disables the default admin port. SSH allows key login only and disables password login.

The rule for the Mac mini is: layered services, centralized data. OrbStack networks are split by stack. Database ports are not mapped to the public side. The NPM admin UI is not exposed directly. .env files, database passwords, tokens, and key files are never committed to Git. For services such as Nextcloud and Vault, “the page opens” is not enough; the data volumes, backups, and restore path also have to be verified.

The rule for Cloudflare is: route by domain, put access control in front. Normal web services can use CDN and WAF. Panel-like services should be protected with Cloudflare Access or IP restrictions. Certificates should use DNS validation or Cloudflare Origin Certificates where possible, avoiding HTTP validation problems caused by the frp forwarding chain.

Backups should cover Cloudflare Pages project configuration, the Astro Blog source repository, Homepage config, Komari data, Nextcloud data and database, Vault-style service volumes, the VPN config entry, game saves, and NPM configuration. A service is not really deployed until it can be restored.

Maintenance Order

This setup is no longer just a migration plan, so maintenance should not start by “launching all containers.” It should start by clarifying entry points and data boundaries.

The first step is to inventory existing containers, image versions, port mappings, volumes, databases, and config files, then complete one verifiable backup. The second step is to keep stack directories on the Mac mini, with each stack maintaining its own compose.yml, .env, and data/.

If the entry layer changes, check HK Main’s frps, firewall, and required ports first, then verify that the Mac mini’s frpc can connect reliably. Once the entry path works, check edge-stack and NPM, confirm that npm-http and npm-https forwarding are registered, and make sure each domain hits the right Proxy Host.

If a business service changes, verify it domain by domain: komari for continuous monitoring data, homepage for navigation and status cards, vpndl for usable downloads and config, gs for game protocol and port access, nc for file sync and database health, and v for login, unlock, and persistence.

Finally, review DNS, NPM reverse proxy rules, backup jobs, and old port mappings. Once the new entry is stable, shut down old containers or old domains instead of saving all the risk for the end.

What Comes Next

This framework has moved from April’s “preparing the rebuild” stage into ongoing maintenance around the current services. A few concrete templates still need to be filled in:

monitor-stack compose.yml and Komari backup notes.
homepage-stack config structure.
private-services-stack Nextcloud / Vault backup and restore procedures.
vpn-stack entry notes and access-control checklist.
game-stack compose.yml.
NPM reverse proxy rule list.
Scheduled backup scripts and restore rehearsal notes.

Once those templates are complete, this will become more than a one-time rebuild note. It will be a reusable way to run my personal servers: new services join by layer, old services migrate by layer, and problems can be traced through entry, service, data, and network boundaries one layer at a time.

Raising a Pet in Codex? Wait, Really?

Fri, 08 May 2026 00:00:00 GMT

This article walks through the full process of enabling pets in Codex, installing a custom pet, and creating your own pet from a reference image. The example here is FleetSnowfluff.

Note

This is for people who already use Codex Desktop or Codex CLI and want to enable a built-in pet, install a custom animated pet, or make one of their own and share it.

1. Understand the Basics First

1.1 What Is a Codex Pet?

A Codex pet is a tiny animated companion whose behavior changes with your working state. An installable pet is usually a local folder containing at least:

<pet-id>/
  pet.json
  spritesheet.webp

pet.json describes the name, ID, description, and spritesheet file path. spritesheet.webp is the animation atlas.

The final install package in this repo is:

~/.codex/pets/fleetsnowfluff/
  pet.json
  spritesheet.webp

1.2 The `hatch-pet` Skill and the Pet Package Are Not the Same Thing

hatch-pet is the Codex Skill used to create pets.
~/.codex/pets/<pet-id>/ is the finished pet package that Codex reads.

In other words, if someone gives you a finished pet package, you do not need to install hatch-pet.

You only need hatch-pet when you want to generate a pet yourself from an image or prompt.

2. How to Enable Pets in Codex

2.1 Enable a Built-in Pet

In Codex Desktop:

Open Codex.
Go to Settings.
Open Appearance.
Find the Pets section.
Choose the pet you want to enable.
If the UI shows Tuck Away Pet, you can use it to temporarily hide the pet.

You can also use this inside a Codex session:

/pet

If you cannot see the pet selector, update Codex first, then restart the app.

2.2 Enable a Custom Pet

Put the pet package into the local Codex pets directory.

macOS / Linux:

mkdir -p "$HOME/.codex/pets/fleetsnowfluff"
cp pet.json spritesheet.webp "$HOME/.codex/pets/fleetsnowfluff/"

Windows PowerShell:

New-Item -ItemType Directory -Force "$env:USERPROFILE\.codex\pets\fleetsnowfluff"
Copy-Item .\pet.json, .\spritesheet.webp "$env:USERPROFILE\.codex\pets\fleetsnowfluff\"

Then restart Codex and return to:

Settings -> Appearance -> Pets

Choose FleetSnowfluff.

3. Custom Pet File Requirements

3.1 Minimal `pet.json`

{
  "id": "fleetsnowfluff",
  "displayName": "FleetSnowfluff",
  "description": "A tiny pink-haired chibi coder sprite with oversized sunglasses, white-blue outfit, and small attached wings.",
  "spritesheetPath": "spritesheet.webp"
}

Notes:

id should use lowercase letters, numbers, and hyphens.
The folder name should preferably match the id.
displayName is the name shown in the UI and can keep capitalization.
spritesheetPath usually points to spritesheet.webp in the same directory.

3.2 Spritesheet Atlas Specs

The hatch-pet workflow uses a fixed atlas:

Size: 1536 x 1872
Grid: 8 columns x 9 rows
Cell: 192 x 208
Format: WebP or PNG, with transparent background support required

The 9 rows map to these states:

Row	State	Frames	Purpose
0	`idle`	6	Idle, breathing, blinking
1	`running-right`	8	Moving right
2	`running-left`	8	Moving left
3	`waving`	4	Waving
4	`jumping`	5	Jumping
5	`failed`	8	Failure or disappointment
6	`waiting`	6	Waiting
7	`running`	6	Task in progress
8	`review`	6	Checking or reviewing

Unused cells must be transparent.

4. How to Make Your Own Pet With `hatch-pet`

If you have not installed hatch-pet, type this in Codex:

$skill-installer hatch-pet

Restart Codex after installation.

If you need to manually install the curated skill, you can refer to the installation method in the OpenAI skills repository:

python "$CODEX_HOME/skills/.system/skill-installer/scripts/install-skill-from-github.py" \
  --repo openai/skills \
  --path skills/.curated/hatch-pet

Usually, you do not need to run this manually. Using $skill-installer hatch-pet in Codex is easier.

5. Create a Pet From a Reference Image

5.1 Prepare the Reference Image

The reference image can be:

a character avatar
a pixel character
a mascot
a screenshot
a logo or sketch

The clearer the image, the more stable the result. It is best to decide these things in advance:

the pet name
the core traits that must be preserved
any accessories or body structure that must remain
things that should not be generated

For FleetSnowfluff, the most important traits in the reference image were:

short pink hair
oversized black sunglasses
white and blue futuristic outfit
small boots
white and blue wings attached to both sides of the body

5.2 Recommended Prompt Pattern

You can ask Codex like this:

Use $hatch-pet to create a Codex pet based on this reference image.
Name: FleetSnowfluff
Must preserve: short pink hair, black sunglasses, white-blue clothing, white-blue wings.
Style: Codex digital pet, pixel-art-adjacent, small body, thick outline, transparent background.
Avoid: text, background, shadows, floating decorations, music notes, scattered stars.
When finished, generate pet.json, spritesheet.webp, QA contact sheet, and preview videos.

The important part is to state “must preserve” and “avoid” clearly.

5.3 Normal Generation Flow

The hatch-pet process can be understood as four steps:

Prepare the run directory, name, description, and prompt.
Generate the base pet, which becomes the main visual reference.
Generate the 9 rows of actions from the base.
Compose the spritesheet, run QA, and package it into ~/.codex/pets/<pet-id>/.

Our FleetSnowfluff run looked like this:

Getting FleetSnowfluff ready.
Imagining FleetSnowfluff's main look.
Picturing FleetSnowfluff's poses.
Hatching FleetSnowfluff.

5.4 Why You Should Confirm the Base First

The base image is the identity anchor for every later action row. If the base is wrong, the action rows are usually wrong too.

When checking the base, look for:

whether the character is a complete full-body sprite;
whether the core traits are preserved;
whether it has a clean solid chroma-key background;
whether it contains unwanted text, shadows, floating decorations, and similar artifacts;
whether it will still read well when scaled down to a 192 x 208 cell.

FleetSnowfluff’s first base did not include wings, so it had to be regenerated. The second base preserved the wings, and only then did we continue to action-row generation.

6. Action Row Generation Tips

6.1 Use Subagents to Generate Rows in Parallel

hatch-pet works well when each action row is handed to a subagent in parallel. Each subagent handles one state:

idle
running-right
running-left
waving
jumping
failed
waiting
running
review

The parent session only needs to:

record generation results
decide whether to mirror running-left
run the final composition
check QA
package the pet

This avoids multiple agents editing imagegen-jobs.json at the same time and causing conflicts.

6.2 Do Not Mirror `running-left` Casually

Some pets can use a horizontally mirrored running-right row as running-left. But if the character has asymmetric traits, do not mirror it.

FleetSnowfluff has a blue hair clip, sunglasses gradient, and directional wing details, so we generated running-left separately instead of mirroring it.

Use this rule of thumb:

If there is a one-sided hair clip, logo, text, or weapon, do not mirror.
If there is directional lighting or a handheld prop, do not mirror.
If the character is completely symmetrical, mirroring may be acceptable.

6.3 Common Rules for Each Row

idle: use only subtle breathing, blinking, and vertical bobbing.
waving: express the wave through the hand pose only; do not draw wave lines.
jumping: show the jump through body position only; do not draw ground shadows or landing smoke.
failed: small tears or smoke close to the body can work, but do not add floating red crosses or symbols.
waiting: keep it quiet and simple; do not add complex props.
running: this means “task in progress,” not literal running.
review: show focus through leaning, head angle, or hand pose; do not add code windows or sheets of paper.

7. QA and Validation

After generation, check at least these files:

qa/contact-sheet.png
qa/reports/review.json
qa/reports/validation.json
qa/videos/*.mp4

The QA files in this repo are:

qa/contact-sheet.png
qa/reports/review.json
qa/reports/validation.json
qa/videos/

7.1 What to Check in the Contact Sheet

Manually inspect the contact sheet:

whether each row represents the correct state;
whether each state has the correct frame count;
whether the character identity stays consistent;
whether wings, hairstyle, sunglasses, and outfit remain consistent;
whether there are white backgrounds, shadows, floating clutter, cropping issues, or empty frames.

7.2 What to Check in JSON Validation

validation.json should have no:

"errors": []

Ideally it should also have no:

"warnings": []

review.json should show ok: true for every row.

7.3 Preview Videos

If ffmpeg is installed, preview MP4 files can be generated for each state.

If ffmpeg is missing, the spritesheet and pet package can still be generated. You simply will not have video previews. When we created FleetSnowfluff, we hit this first, installed ffmpeg, and then generated:

qa/videos/idle.mp4
qa/videos/running-right.mp4
qa/videos/running-left.mp4
qa/videos/waving.mp4
qa/videos/jumping.mp4
qa/videos/failed.mp4
qa/videos/waiting.mp4
qa/videos/running.mp4
qa/videos/review.mp4

8. The Right Way to Rename a Pet

Changing only displayName is not enough. You should update all of these together:

~/.codex/pets/<pet-id>/
pet.json
run metadata
README / docs
QA summary
Git repository directory

For FleetSnowfluff:

{
  "id": "fleetsnowfluff",
  "displayName": "FleetSnowfluff",
  "spritesheetPath": "spritesheet.webp"
}

The directory should also be:

~/.codex/pets/fleetsnowfluff

If you keep the generation run directory, it is also worth replacing the old name globally to avoid confusion during uploads or future maintenance.

Check for leftover names:

rg -n "OldName|oldname" .

9. Package It as an Uploadable Repository

Recommended final repository structure:

my-pet/
  README.md
  pet.json
  spritesheet.webp
  qa/
    contact-sheet.png
    reports/
      review.json
      validation.json
    videos/
      idle.mp4
      running-right.mp4
      running-left.mp4
      waving.mp4
      jumping.mp4
      failed.mp4
      waiting.mp4
      running.mp4
      review.mp4

Initialize git:

git init
git add .
git commit -m "Add FleetSnowfluff Codex pet"

Upload to GitHub:

git remote add origin git@github.com:<user>/<repo>.git
git push -u origin main

If you use HTTPS:

git remote add origin https://github.com/<user>/<repo>.git
git push -u origin main

10. FAQ

The Pet Does Not Appear in Codex

Check:

whether it is placed under ~/.codex/pets/<pet-id>/;
whether pet.json and spritesheet.webp both exist;
whether spritesheetPath in pet.json is correct;
whether id matches the directory name;
whether Codex has been restarted.

The Pet Has a White Background or Background Residue

This usually means transparency handling failed. Regenerate or repair the affected row and make sure:

the background is a solid chroma-key color;
there are no shadows, gradients, or glows;
the background color is not used on the character itself.

One Action Row Is Broken

Do not remake the whole pet. Repair only the failed row:

queue repair -> regenerate that row -> record result -> finalize again

The Character Changes During Animation

This is identity drift. When repairing it, use the base image, original image, contact sheet, and failure description as grounding context. Ask it to regenerate only the failed row.

I Want to Preserve a Specific Detail

Say so before generating the base. For example, FleetSnowfluff’s wings were required:

Must preserve the white-blue wings. The wings are part of the body silhouette, not floating decorations.

11. A Copy-ready Pet Creation Request

Use $hatch-pet to help me create a Codex pet.

Name: <YourPetName>
Reference image: attached
Must preserve:
- <core trait 1>
- <core trait 2>
- <core trait 3>

Style:
- Codex digital pet
- pixel-art-adjacent
- small chibi proportions
- thick dark outline
- transparent background
- flat cel shading

Avoid:
- text
- background
- shadows
- floating decorations
- wave lines
- speed lines
- particle effects

Please generate:
- pet.json
- spritesheet.webp
- QA contact sheet
- preview videos for every state

If one step fails, retry only the failed row instead of remaking the whole pet.
When finished, organize it as a git repository so it can be uploaded easily.

12. FleetSnowfluff Output From This Repo

pet.json
spritesheet.webp
qa/contact-sheet.png
qa/reports/review.json
qa/reports/validation.json
qa/videos/*.mp4

Example install path:

~/.codex/pets/fleetsnowfluff

This repository can be uploaded directly, or copied directly to ~/.codex/pets/fleetsnowfluff for use.

References

How to Create an Apple ID for Another Region on the Web

Wed, 06 May 2026 00:00:00 GMT

Note

When creating or using an account, follow Apple’s terms of service and the laws and regulations that apply to you. I do not recommend buying, sharing, or using accounts from unclear sources.

When This Is Useful

This guide is useful if you:

want to download apps available in the U.S. App Store or another regional App Store;
need to try Apple services that are available in the U.S. or another region;
want to keep your main account separate from a regional App Store account, reducing the impact on your primary iCloud account.

It is not recommended for:

bypassing copyright, payment, subscription, or local legal restrictions;
using a fake identity, fake payment method, or billing details from an unverified source;
creating or buying ready-made third-party Apple IDs.

What to Prepare

Before you start, prepare:

an email address that has never been used for an Apple ID;
a phone number that can receive verification codes. A foreign phone number is preferred when you have one, but a +86 number can also work. The same phone number can be used to register multiple accounts;
a computer, phone, or tablet that can access Apple’s website;
a stable network connection. A proxy is usually not required;
if you plan to buy paid content later, a legitimate payment method that matches the U.S. or target region. For users in mainland China, gift cards are often the easier option.

When creating an Apple Account on the web, the important parts are the email address, password, country or region, birthday, and phone verification. Payment information is usually not the core step during web registration. You may only be asked to add it later when signing in to services such as the App Store, Apple Music, Apple TV, or iCloud+.

Registration Steps

Open this page in your browser:

https://account.apple.com/account

I recommend using an incognito window or a fresh browser profile so that an existing signed-in account does not affect the registration page.

2. Fill in the Account Information

Fill in the form as prompted:

Field	Suggestion
Name	Any name you can consistently remember
Country or region	Choose the `[U.S. or target region]`
Date of birth	Any date that makes the account holder over 18
Email	Use an email address that has not been used for an Apple ID
Password	Use a strong password, or one you know well, and store it safely
Phone number	Use a number that can receive verification codes normally

The country or region is the key part of this step. The region you choose affects the content you see in Apple services, available payment methods, billing information, and some age-verification requirements.

3. Choose Whether to Receive Apple Updates

The page may offer email subscriptions for Apple updates, news, software, products, and services.

This step is optional. If you want fewer emails, uncheck the boxes. If you want official Apple updates, leave them selected.

4. Complete Verification

After you click continue, Apple usually asks you to verify both your email address and phone number.

The flow is usually:

Open your email inbox and find the verification code from Apple.
Enter the email code on the web page.
Receive the SMS verification code.
Enter the phone code on the web page.
Wait for the account to be created.

If verification codes do not arrive, check spam, SMS filtering, phone number format, browser proxy settings, and network status. Avoid repeatedly submitting the form in a short period, as that may trigger extra restrictions.

After registration, you will usually be signed in to the Apple Account page automatically.

After signing in, check:

whether the name and birthday are correct;
whether the country or region is the U.S. or target region;
whether the email address and phone number are verified;
whether account security settings are complete;
whether two-factor authentication is already enabled or waiting to be enabled later.

6. Add Payment and Billing Information Later

Because binding a foreign bank card can be difficult, I recommend choosing None when it is available, then using gift cards instead.

Important

Although the web account page may still show the selected country or region, the account can be sent back to your original local region when you sign in to the App Store. So the next step is to switch the App Store region first.

This method uses regional redirect links.

First, sign out of your App Store account.

iOS 26.4 and later: open the App Store, tap the Apple account avatar in the top-right corner, tap the account at the top, verify if prompted, scroll to the bottom, and tap Sign Out.

iOS 26.3 and earlier: open the App Store, tap the Apple account avatar in the top-right corner, scroll to the bottom, and tap Sign Out.

macOS: open the App Store, click Store in the menu bar, then sign out.

Important

After signing out, do not sign in immediately. Otherwise, the account may be sent back to its original region.

Next, copy one of the links below into Safari and press Enter.

Region	Quick redirect link
United States	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143441&cc=us`
Japan	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143462&cc=jp`
South Korea	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143466&cc=kr`
Hong Kong	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143463&cc=hk`
Nigeria	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143561&cc=ng`
Turkey	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143480&cc=tr`
Egypt	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143516&cc=eg`
India	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143467&cc=in`
Argentina	`itms-apps://itunes.apple.com/WebObjects/MZStore.woa/wa/resetAndRedirect?dsf=143505&cc=ar`

It is normal if App Store says it cannot connect after you open the link.

8. Check the Account

Finally, sign in and check whether the country or region is correct. Download a few apps to help lock the region in place, or redeem a gift card directly.

One extra note: because Apple’s region-changing policy requires the account to have no remaining balance, redeeming a gift card can be a relatively stable way to lock the region.

Usage Tips

I recommend using a regional Apple ID only for App Store downloads, app updates, and necessary regional services. It should not replace your main iCloud account.

A practical daily setup is:

keep your main account signed in to iCloud;
switch to the regional account in the App Store when needed;
after downloading or updating apps, switch back to your main account.

This reduces the chance of affecting core data such as photos, backups, contacts, and Find My devices.

FAQ

Why Is There No `None` Payment Option?

Possible reasons include:

the current service or region does not support skipping payment details;
Apple requires billing information when the account first uses media services;
the payment method, billing address, and account region do not match;
the device, network, or account status triggered extra verification.

Web registration does not always ask for a payment method immediately. Whether None is available later when using Apple media or paid services depends on what Apple’s page shows at that moment.

Can a Regional Apple ID Use a Mainland China Bank Card?

Not always. Supported payment methods vary by country or region. In most cases, the payment method needs to match the account’s country or region. Check Apple’s official payment-method support list for details.

Can I Use It Together With My Main Account Long Term?

Yes, but I recommend switching only at the App Store level. Avoid frequently switching your main iCloud account.

Also note that apps are usually tied to the account that downloaded them. If an app was downloaded with the regional account, future updates may require signing in with that same regional account again.

What If the Account Gets Locked?

Use Apple’s official account recovery page first:

https://iforgot.apple.com/

Do not keep guessing the password, and do not use third-party unlocking services.

If I Already Have an Apple ID, Can I Just Change Its Region?

Yes, you can change the country or region in account settings. Before doing so, however, you usually need to handle subscriptions, remaining balance, payment methods, Family Sharing, and related issues. Changing the region of your main account has a larger impact, so I prefer using a separate account for regional App Store needs.

Notes

Enable two-factor authentication.
Keep the email address, phone number, and recovery methods safe.
Do not lend the account to other people.
Do not buy ready-made accounts.
Do not sign in on untrusted devices.
For payments, subscriptions, and Family Sharing, follow the prompts shown on Apple’s official pages.

About Gift Cards

Gift cards from Xianyu are often the most convenient, but they may come with risks such as black-card issues or slightly worse exchange rates.

For U.S. accounts, you can refer to this article: A simple, safe, and reliable guide to buying and redeeming U.S. Apple ID gift cards - Zhihu, Apple Dabai

For Turkey accounts, I recommend going directly to SEAGM or Oyunfor. SEAGM supports Alipay, while Oyunfor only supports cards such as MasterCard and Visa.

References

What Stays With Us Finds Its Way Back

Wed, 10 Jul 2024 00:00:00 GMT

What’s past is prologue.

A life keeps moving forward. Again and again, we begin somewhere new. And little by little, we start to forget so many people, so many things…

Some people say that is just how life is. We meet so many people and go through so much in one lifetime. How could anyone remember all of it?

Right. How could anyone remember all of it…

This is where I will write down the memories I am slowly losing. When I come back and see these words again, I hope they can still lead me back to what I have forgotten…

豕豕豕 - Blog (EN)

Play Tears of the Kingdom Natively on Mac: A MacNativeGames Build Guide

1. Check the requirements

Hardware and storage

Game files

2. Install the build tools

Optional: install the Metal toolchain

3. Download the source and organize your files

4. Choose your build command

XCI base: build version 1.0.0

NSP base: supply the shared fonts

Base plus update: build version 1.4.3

How long does it take?

5. Let the first launch finish preparing

Can you move the app?

6. Controller and keyboard controls

Controllers: watch the confirm button’s position

Keyboard layout for this revision

7. Adjust graphics one setting at a time

8. Find and back up your saves

9. Troubleshooting

Terminal cannot find brew or python3.14

Shared fonts are missing

A version or hash check fails

No game window appears after opening the app

Stutter persists or memory pressure is high

Effects play, but dialogue or music is missing

You want to install mods

References

Deploy Xboard Directly on Linux for a Self-Hosted Proxy Panel

Preparation Checklist

Architecture

Tutorial

1. Prepare the Servers

2. Configure DNS

3. Install Docker and Compose

4. Deploy Xboard

5. Install Caddy

6. Basic Xboard Configuration

7. SMTP Mail Configuration

8. Plan Design

9. Create HY2 Nodes

10. Install Xboard-Node

11. Configure HY2 Certificates

12. Firewall and Security Groups

13. HY2 Port Hopping

14. User Subscriptions and Clients

15. Pre-Launch Checklist

16. Final Hardening

Pitfalls

Broken apt source

Fake-IP interference

Caddy TLS EOF

Subscription 404

SMTP unauthorized IP

Server online but node not running

Node running but idle

UDP port range not visible

Cannot delete a plan

References

From Disk to Files: Understanding GPT, APFS, Containers, and Volumes on macOS

Physical Disks

GPT: The Partition Map

Partitions

File Systems

APFS Containers

Volumes

Mounting

Why Macintosh HD and Macintosh HD - Data Are Separate

APFS Volume Groups

Preboot, Recovery, and VM

Formatting, Erasing, Deleting Volumes, and Deleting Partitions

Snapshots

EFI Partition

RAID and Volumes

Reading diskutil Output

The Core Idea

References

Deploying a QQ Bot on Linux with NapCat, NoneBot2, GsCore, and Caddy

The Final Architecture

Terminal cannot find `brew` or `python3.14`

Problem 2: `nb` was not found

Fix A: install `nb-cli`

Fix B: install the plugin directly with `pip`

Add GsCore settings to the NoneBot `.env`

Configure `config.json` on the GsCore side

2. A missing `nb` command usually just means `nb-cli` is not installed

1.2 The `hatch-pet` Skill and the Pet Package Are Not the Same Thing

3.1 Minimal `pet.json`

4. How to Make Your Own Pet With `hatch-pet`

6.2 Do Not Mirror `running-left` Casually