Skip to main content

Getting Started

Discord-PXE is a bare-metal x86-64 Discord Gateway runtime that boots through legacy BIOS PXE, loads a larger runtime over TFTP, switches into long mode, drives supported Realtek hardware directly, and implements the network/TLS/WebSocket/Gateway path without a conventional operating system.

There is no Linux, Windows, libc, OpenSSL, curl, Node.js, or Discord SDK on the target machine.

Current hardware baseline

The current main branch has completed a 128-shard READY bring-up on real hardware in stable BSP scheduler mode. SMP shard-state execution exists in source but remains experimental and disabled by default.

Requirements​

Build host​

  • Windows
  • PowerShell
  • NASM on PATH or in the standard Program Files NASM location
  • a working PXE/TFTP environment
  • Git for normal source updates

Target​

  • legacy BIOS / CSM PXE boot
  • x86-64 CPU
  • supported Realtek NIC for the native runtime path
  • serial output strongly recommended

Discord​

  • a Discord bot token
  • a bot configuration that can connect with the current intents: 0 Identify payload

Configure the bot token​

Create:

config/token.txt

Place the bot token in that file. A leading Bot prefix is accepted and normalized by the build tooling.

Built images may contain secrets

The bot credential is embedded into generated runtime data. Treat runtime.bin and other generated outputs as secret material when built with a real token.

Build​

Run:

build.bat

Successful output includes:

build\stage1.pxe
build\runtime.bin

The build path validates image sizes and prints SHA-256 hashes for the generated images.

Build, install, and refresh PXE​

For the normal hardware workflow:

git pull
run.bat

run.bat invokes the PXE setup tooling, rebuilds the project, installs the generated PXE payload, updates configuration, and restarts the PXE service.

After it finishes, boot the target using Legacy Network/PXE.

Serial console​

The target emits serial diagnostics at:

115200 baud
8 data bits
no parity
1 stop bit
no flow control

Keep serial attached from power-on. The earliest breadcrumbs exist before the full runtime shell.

Debug by last successful layer

Do not jump directly to TLS or sharding if PXE/TFTP or long mode is already broken. Follow the boot chain upward and stop at the first layer that fails to make progress.

Expected boot path​

BIOS PXE
  -> stage1.pxe
  -> PXENV+ / DHCP / TFTP
  -> runtime.bin @ physical 0x20000
  -> E820 / page tables
  -> x86-64 long mode
  -> SMP bring-up
  -> native Realtek networking
  -> DNS
  -> TCP
  -> TLS 1.2 / X.509
  -> WebSocket
  -> Discord Gateway

Prove the singleton path first​

Before testing the shard pool, a healthy boot should reach a sequence resembling:

[DNS] query sent
[DNS] gateway.discord.gg=...
[TCP] gateway connection established
[X509] leaf chain verified locally
[TLS] authenticated tls established
[DISCORD] http 101 + websocket accept verified
[DISCORD] READY, bot online

If that path is not healthy, do not debug sharding first.

Start a shard plan​

For a small isolation test:

shardtest2
shardteststatus

For the current stable full local baseline:

shardplan 128 0 128
shardstart

Local shell plans currently force Identify concurrency to 1 until runtime /gateway/bot discovery is implemented.

Runtime commands​

The interactive pxe> shell includes system inspection, network/PXE status, TFTP file access, configuration reload, serial telemetry controls, reboot, and shard-management commands.

For the complete syntax and behavior of every command, see the Command Reference.

Common shard commands include:

shards
shardplan <total> <start> <count> [max-concurrency]
shardstart
shardstop
shardreset <local-slot>
shardlease <seconds>
shardtest2
shardteststatus