Installation

Installation

You need a Switch running Atmosphère and a computer on the same network.

1. Put the agent on the SD card

Download the latest release zip and extract it to the root of your SD card, letting the folders merge:

atmosphere/contents/420000000000AE57/exefs.nsp
atmosphere/contents/420000000000AE57/flags/boot2.flag   <- empty file
atmosphere/contents/420000000000AE57/toolbox.json
config/switch-agentd/config.ini.example

flags/boot2.flag is what makes Atmosphère start the module at boot. Without it nothing runs and the only symptom is a refused connection — so if you are copying files by hand, do not skip it.

Reboot the console.

2. Get your token

On first boot the agent writes sd:/config/switch-agentd/config.ini containing a randomly generated token. Read that file to get it.

The token never crosses the network. The client proves it knows the token by answering a challenge the console issues, so watching the Wi-Fi gets an attacker nothing reusable.

3. Check it is running

sd:/config/switch-agentd/agent.log should end with:

listening on port 6060

No log file at all means the module is not starting — see Troubleshooting.

4. Find the console's IP

Settings → Internet on the console. Or let the server scan for it:

cd server
SWITCH_TOKEN=<your-token> uv run python -c \
  'import asyncio,os,sys; sys.path.insert(0,"src"); from switch_mcp.discovery import scan; \
   print(asyncio.run(scan(token=os.environ["SWITCH_TOKEN"])))'

This console does not answer ping reliably. It drops ICMP but accepts TCP. A failed ping does not mean it is offline — probe port 6060 instead.

5. Connect an agent

cd server && uv sync

claude mcp add switch \
  -e SWITCH_HOST=<console-ip> \
  -e SWITCH_TOKEN=<token-from-config.ini> \
  -- uv --directory $(pwd) run switch-mcp

Any MCP client works. For one that takes JSON config:

{
  "mcpServers": {
    "switch": {
      "command": "uv",
      "args": ["--directory", "/path/to/switchMCP/server", "run", "switch-mcp"],
      "env": { "SWITCH_HOST": "10.0.0.5", "SWITCH_TOKEN": "your-token" }
    }
  }
}

Verify with the ping tool. You should get the agent version and firmware back.

6. Raise the tier

A fresh install is observe — read-only. It cannot press a button or write a file. To actually drive the console, edit sd:/config/switch-agentd/config.ini:

tier = control

and reboot. See Configuration for what each tier allows.

Removing it

Delete these and reboot:

sd:/atmosphere/contents/420000000000AE57/
sd:/config/switch-agentd/
sd:/switch-agentd/            (save backups and the audit journal — safe to keep)

If a bad build stops the console booting, hold Volume-Up during boot to skip boot2 sysmodules, then delete the contents folder.