Configuration

Configuration

Two places: config.ini on the SD card controls what the console permits, and environment variables control what the MCP server exposes.

Console: sd:/config/switch-agentd/config.ini

port = 6060
token = <generated on first boot>
log_level = info          # error | warn | info | debug

tier = observe

allow_nand_write = false
allow_overclock = false
allow_hardware = false

clear_lockscreen_on_boot = true
keep_awake_minutes = 10
require_hmac_auth = false
enable_psc = false
enable_usb = false

Changes need an agent restart (reboot the console).

Tiers

The single most important setting. Commands above the configured tier are refused before the handler runs, and the refusal names the setting that would allow them.

Tier	What it allows
observe	Default. Read only — screenshots, files, sysinfo, logs, crash reports, save enumeration. Cannot change anything.
control	Everything a person holding the console could do: controller and touch input, launch and close apps, read and write SD-card files, brightness, volume, reboot. Nothing here risks the firmware.
invasive	Writes that can leave the console unbootable or damage hardware: NAND/BIS writes, raw i2c, live memory patching, uninstalls, clock changes.

Sub-gates

Independent of the tier. Reaching invasive is necessary but not sufficient for these — each is its own deliberate opt-in.

Option	Gates
allow_nand_write	uninstall_title, restore_save — anything writing NAND
allow_overclock	Clock changes. Thermal risk.
allow_hardware	Raw i2c and GPIO. PMIC writes can physically damage the console.

Staying reachable

Option	Default
clear_lockscreen_on_boot	true	The console boots to a lockscreen that sleeps even with auto-sleep set to Never, and sleeping drops the network. The agent presses B three times, 12 s after boot, on its own thread. Needs tier >= control.
keep_awake_minutes	10	Periodic nudge so the console does not idle back to the lockscreen. Skipped whenever a game is running, so it can never interfere with play. 0 disables.

Security

Option	Default
require_hmac_auth	false	Refuse the legacy cleartext-token handshake. The current client always uses challenge-response regardless; turn this on once nothing old connects.

Off by default, and why

Option
enable_psc	Cleaner sleep/wake handling. A power-state module that fails to acknowledge a sleep request hangs the console — an early version did exactly that. The implementation is now correct (dedicated acknowledgement thread), but the fallback path cannot hang anything, so it stays the default.
enable_usb	USB bulk transport. Compiles, initialises lazily, never tested against hardware and there is no host client. Inert.

emuMMC

Detected automatically and reported in the handshake — you do not configure it. It matters because on emuMMC a mistake is recoverable by restoring your SD image; on sysMMC it may not be. The preflight tool warns when you are on sysMMC.

Server: environment variables

Variable	Default
SWITCH_HOST	(required)	Console IP
SWITCH_TOKEN	(required)	From config.ini
SWITCH_PORT	6060
SWITCH_MCP_TOOLS	(see below)	Which tool groups to register
SWITCH_MCP_ALLOW_DESTRUCTIVE	unset	Skip confirmation tokens. For unattended use.
SWITCH_MCP_LOCAL_ROOTS	unset	Restrict which host paths fs_download/fs_upload may touch
SWITCH_MCP_TRANSPORT	stdio	streamable-http / sse for a shared instance
SWITCH_MCP_HOST / _PORT	127.0.0.1 / 8730	Bind address for network transports

Tool groups

102 tools is more than most MCP clients handle well — the model spends its attention picking from a menu instead of doing the task. So they are grouped:

SWITCH_MCP_TOOLS	Tools
(unset)	69	core,fs,apps,system
all	102	Everything
core	15	Connectivity, screen, input
core,debug	32	Add the debugger

Groups: core, fs, apps, system, debug, cheat, hardware. The last three are off by default — powerful but narrow, and noise for the common case of "look at the screen and press a button".

An unknown group name falls back to the default rather than registering nothing, so a typo cannot leave you with no tools.

Exposing it over the network

The server refuses to bind a non-loopback address with a network transport unless SWITCH_MCP_ALLOW_REMOTE=1. That is deliberate: there is no authentication on the MCP side, and these tools can reboot a console, patch process memory, and read and write host files. If you do expose it, put your own authentication in front and set SWITCH_MCP_LOCAL_ROOTS.