Discord-PXE Command Reference
After the runtime finishes booting, the serial/keyboard shell presents:
pxe>
Commands are intentionally small and direct. The shell is part of the bare-metal runtime, not a POSIX shell: there are no pipes, redirects, environment variables, working directories, or general-purpose process execution.
Use the serial console at 115200 8N1 with no flow control for hardware work. Serial captures the early loader output and then becomes the interactive runtime shell after boot.
Quick reference
| Command | Syntax | Purpose |
|---|---|---|
help | help | Print the built-in command list. |
cpu | cpu | Print CPU/runtime CPU information. |
mem | mem | Print memory information. |
memmap | memmap | Print the collected BIOS E820 memory map. |
pci | pci | Print PCI/device information exposed by the runtime. |
net | net | Print current network state. |
stats | stats | Print network/runtime counters. |
input | input | Print input subsystem status. |
pxe | pxe | Print PXE/runtime PXE state. |
discord | discord | Print Discord/Gateway state. |
ls | ls | List runtime virtual files. |
cat | cat <file> | Print a runtime virtual file. |
fetch | fetch <pxe filename> | Fetch a file through the runtime TFTP path. |
fcat | fcat | Print the most recently fetched file. |
hex | hex | Hex-dump the fetched-file buffer. |
config | config | Print config status. |
config reload | config reload | Reload configuration through TFTP. |
seriallive | seriallive [on|off|status] | Control or inspect live serial telemetry. |
reboot | reboot | Reset the machine. |
restart | restart | Alias for reboot. |
shards | shards | Print the current local shard plan and per-slot state. |
shardplan | shardplan <total> <start> <count> [max-concurrency] | Apply a local shard test plan. |
shardstart | shardstart | Start the sharded transport scheduler. |
shardstop | shardstop | Stop shard-owned transport. |
shardreset | shardreset <local-slot> | Reset one local shard connection. |
shardlease | shardlease <seconds> | Arm or clear local lease enforcement. |
shardtest2 | shardtest2 | Start the built-in two-shard hardware test. |
shardteststatus | shardteststatus | Evaluate the two-shard acceptance conditions. |
System inspection
help
help
Prints the command list compiled into the shell.
Use this first when working with a build whose command set may have changed.
cpu
cpu
Prints the runtime's CPU information through the virtual cpu status path.
Useful early in bring-up to verify that the machine reached the 64-bit runtime and that processor discovery completed.
mem
mem
Prints the runtime memory summary.
Use it to check allocator/runtime memory state before debugging higher-level transport failures.
memmap
memmap
Prints the BIOS E820 memory map collected during boot.
This is particularly useful when debugging physical machines with unusual reserved-memory regions or firmware-dependent layout problems.
pci
pci
Prints PCI/device discovery information exposed by the runtime.
Use it when the runtime boots but expected hardware, especially the NIC, does not appear to initialize correctly.
input
input
Prints the input subsystem status.
The runtime accepts both keyboard and serial input; this command is useful when output works but interactive input does not.
Network and protocol state
net
net
Prints current network state.
Use this before assuming a TLS or Gateway problem. If IP/gateway/DNS state is not healthy, upper layers will not be meaningful.
stats
stats
Prints network/runtime counters.
Counters are useful for deciding whether a state machine is actually moving. For example, increasing RX with no TLS progression points somewhere different from no RX at all.
pxe
pxe
Prints PXE-related runtime state.
Use this when debugging cached DHCP data, PXE handoff state, or firmware/runtime boundary issues.
discord
discord
Prints current Discord/Gateway status from the runtime's Discord virtual status path.
Use it after basic network state is healthy and before switching into the experimental shard pool.
Runtime files and TFTP
ls
ls
Lists files exposed by the runtime's small virtual filesystem.
This is not a disk filesystem in the normal OS sense; the entries expose runtime state and diagnostic views.
cat <file>
cat <file>
Prints a virtual file.
If no file is supplied, the shell prints:
usage: cat <file>, use ls to see files
Run ls first, then use cat for the specific state view you want instead of relying only on the convenience commands such as cpu or net.
fetch <pxe filename>
fetch <pxe filename>
Fetches a named file through the runtime's TFTP/PXE file path.
If no filename is supplied:
usage: fetch <pxe filename>
This is useful for proving that post-boot file transfer works independently of the original stage-1 download.
fcat
fcat
Prints the contents of the fetched-file buffer.
Typical flow:
pxe> fetch example.cfg
pxe> fcat
hex
hex
Displays the fetched-file buffer as hexadecimal data.
Use it when text output is inappropriate or when validating exact bytes transferred over TFTP.
Configuration
config
config
Prints configuration status.
This is the first command to use when a Discord command or shard test reports that token/configuration state is not ready.
config reload
config reload
Starts a manual TFTP configuration reload.
The shell reports:
[CONFIG] manual TFTP reload started
Unknown config arguments produce:
usage: config [reload]
A configuration reload affects the runtime configuration used by later network/Gateway operations. Capture the serial log when diagnosing behavior immediately before and after a reload.
Serial telemetry
seriallive
seriallive
seriallive status
seriallive on
seriallive off
Controls or reports the live serial telemetry mode.
With no argument, seriallive behaves as a status request.
Invalid arguments print:
usage: seriallive [on|off|status]
The shell includes input-busy detection specifically so asynchronous telemetry does not constantly overwrite a command while the operator is typing.
Reboot
reboot
reboot
Resets the target machine.
The runtime first attempts the classic 8042 keyboard-controller reset pulse. If the controller does not reset the system, the runtime falls back to a deliberate triple fault.
restart
restart
Alias for reboot.
The reset path executes immediately. Save/capture whatever serial diagnostics you need before issuing it.
Shard commands
The shard commands operate on the experimental per-shard transport path on main.
Starting the shard pool can stop the hardware-proven singleton Discord transport for the current boot. The runtime explicitly treats the shard pool as owning Discord transport after takeover. Reboot to return to the normal singleton path.
shards
shards
Prints the current shard-plan summary and each active local slot.
The summary includes values such as:
health ready=...
starting=...
backoff=...
fatal=...
total=...
local-start=...
local-count=...
generation=...
ticks=...
Each local slot then reports fields including:
slot
global shard ID
state
Identify bucket
Gateway sequence
TCP state
TLS state
heartbeats sent
heartbeat ACKs
reconnect count
last error
This is the main command for inspecting a shard that is stuck in STARTING, BACKOFF, or FATAL.
shardplan
shardplan <total> <start> <count> [max-concurrency]
Applies a contiguous local shard plan.
Arguments:
| Argument | Meaning |
|---|---|
total | Global Discord shard count. |
start | First global shard ID owned by this node. |
count | Number of contiguous local shard slots. |
max-concurrency | Optional Identify concurrency value. |
The architecture supports up to 128 local shard slots and a global total up to 65535.
Invalid plans print:
usage: shardplan <total> <start> <count> [max-concurrency]
A local slot is not the same thing as a global shard ID. For a plan such as total=16, start=8, count=4, local slots 0 through 3 correspond to global shards 8 through 11.
shardstart
shardstart
Starts the shard-owned transport scheduler.
Before takeover, the runtime requires shared Gateway DNS state to be ready. If it is not ready, the singleton connection is left untouched and the command reports that shard networking could not start yet.
On success, the shard scheduler owns Discord transport for the boot.
shardstop
shardstop
Stops the shard scheduler and aborts shard-owned TCP connections.
The runtime reports that a reboot is required to return to singleton Gateway mode.
shardreset <local-slot>
shardreset 0
shardreset 1
Resets one local shard connection without intentionally resetting its neighbors.
The reset path rebuilds connection state while preserving resumable Gateway state only when both the retained session and Gateway sequence are valid.
Invalid input prints:
usage: shardreset <local-slot>
If shard 0 is unhealthy while shard 1 remains READY, use shardreset 0 and watch whether shard 1 stays healthy. That is a practical test of the per-shard failure boundary.
shardlease <seconds>
shardlease 30
shardlease 0
Arms the local lease deadline using the runtime TSC calibration.
A nonzero value sets a deadline. When the lease expires, shard-owned network traffic is stopped and shard sessions are invalidated/aborted.
A value of 0 clears local lease enforcement. This is used by local shell tests that are not controller-driven.
Invalid input prints:
usage: shardlease <seconds>
Lease expiry is intentionally destructive to shard connectivity. Its purpose is to prevent a stale PXE node from continuing to own Discord shards after its control-plane lease has expired.
Built-in two-shard acceptance test
shardtest2
shardtest2
Starts the smallest useful multi-shard hardware validation.
The command:
- verifies configuration/token readiness
- applies a two-shard plan
- sets global total to 2
- assigns local shard IDs 0 and 1
- uses Identify
max_concurrency=1 - takes over from the singleton Gateway path
- disables controller lease enforcement for the local test
- allocates private per-shard connection state
- enables the shard scheduler
The runtime reports:
[SHARDTEST] two-shard bring-up started: shard 0 then shard 1
If configuration is not ready:
[SHARDTEST] token/config is not ready
If bring-up cannot start:
[SHARDTEST] two-shard bring-up could not start
shardteststatus
shardteststatus
Evaluates the current two-shard acceptance state.
A complete pass is:
[SHARDTEST] PASS: 2/2 isolated shards READY with TLS + heartbeat ACKs
The check does more than confirm that two READY events occurred. It verifies structural isolation and health, including:
- two active local slots
- separate shard contexts
- separate TCP contexts
- different local TCP ports
- separate TLS workspaces
- separate WebSocket workspaces
- separate Discord workspaces
- shard IDs 0 and 1
- global total of 2
- READY lifecycle state and flag
- TLS in the UP state
- at least one heartbeat ACK
- no shard-level error
If mutable state is shared:
[SHARDTEST] FAIL: shard contexts are not isolated
If the test has not reached all acceptance conditions:
[SHARDTEST] not passed yet; current shard state follows
The runtime then prints the shard state so the failing layer can be identified.
Recommended command sequence after a fresh PXE boot
For normal bring-up:
pxe> help
pxe> cpu
pxe> mem
pxe> pci
pxe> net
pxe> stats
pxe> pxe
pxe> config
pxe> discord
For the current two-shard hardware milestone:
pxe> shards
pxe> shardtest2
pxe> shards
pxe> shardteststatus
If one shard fails independently:
pxe> shards
pxe> shardreset 0
pxe> shards
pxe> shardteststatus
When finished:
pxe> shardstop
pxe> reboot
For a useful hardware bug report, keep the serial log from the initial PXE loader breadcrumbs through the command that exposes the failure. A state dump without the events leading into it often loses the most useful timing information.
Source
The command dispatcher and shell behavior are implemented in: