Configuration¶

Options¶

Feather:init(config) accepts the following options:

Generated CLI Config¶

feather init defaults to CLI-managed mode. In that mode Feather creates feather.config.lua without patching game code, and feather run injects the runtime when you launch the game.

The generated CLI config includes:

return {
  managed = "cli",
  debug = true,
  autoRegisterErrorHandler = true,
  include = { "particle-system-playground", "shader-graph" },
  capabilities = { "draw", "filesystem" },
}

Those default plugins are normal bundled plugins, not special cases. Other plugins are enabled by adding their IDs to include, either manually or with the CLI:

feather config plugins --include input-replay
feather config plugins --exclude shader-graph

Plugins marked optIn = true or disabled = true in their manifest.lua only become active when included. This is how development-only tools such as Console and Hot Reload stay off unless you ask for them.

Runtime Budget And Panel Interest¶

Feather keeps connection, auth, errors, logs, debugger control, explicit profiler captures, and a low-rate performance heartbeat available while the game is connected. More expensive work such as observer serialization, asset payloads, plugin UI payloads, Time Travel, Session Replay, Runtime Snapshot, and creative preview sync is activated by opening the matching page or starting an explicit recording/preview workflow.

Non-critical work is spread across frames with runtimeBudget:

return {
  runtimeBudget = {
    maxFrameMs = 0.5,
    maxMessagesPerFrame = 20,
    maxSerializedBytesPerFrame = 32 * 1024,
  },
}

Critical messages still send immediately under budget pressure: auth/hello/bye, fatal errors, command/action responses, debugger pause/resume/status, runtime suspend/resume, and explicit preview clear/hide actions.

Hot Reload¶

Hot reload is configured under debugger.hotReload, but the command handler only exists when the opt-in hot-reload plugin is installed and included:

return {
  include = { "hot-reload" },

  debugger = {
    enabled = true,
    hotReload = {
      enabled = true,
      allow = { "game.player", "game.systems.*" },
      deny = { "main", "conf", "feather.*" },
      persistToDisk = false,
      clearOnBoot = false,
      requireLocalNetwork = true,
    },
  },
}

The CLI can write the same shape for you:

feather init path/to/my-game --plugins hot-reload --hot-reload-allow game.player,game.systems.combat --yes
feather config hot-reload --allow game.player,game.systems.combat --dir path/to/my-game

See Hot Reload for the full workflow.

Security¶

Feather uses a nonce-based challenge-response handshake to authenticate each connection before any game data is exchanged.

The CLI can audit these settings:

feather doctor path/to/my-game --production
feather doctor path/to/my-game --security --json

--production fails on unsafe release settings. --security --json emits a machine-readable security report and redacts sensitive values such as apiKey.

How it works¶

1. When the game connects, the desktop immediately sends a one-time challenge nonce.
2. The game responds with its configured appId and the nonce.
3. The desktop validates both. On success it sends auth:ok and the game begins pushing data. On failure it sends auth:fail and closes the connection.

No game data (feather:hello, observers, logs, etc.) is sent until the handshake completes.

Setting up appId¶

Copy your App ID from Feather → Settings → Security → Desktop App ID and add it to your config:

return {
  appId = "your-app-id-here",
}

The same appId must be set in both the desktop settings and your game config. If they don't match, the connection is rejected and the game logs:

[Feather] Auth failed. Check that appId in feather.config.lua matches your Feather desktop App ID.

Insecure mode¶

For quick local prototyping or LAN jam builds where you don't want to manage a fixed App ID:

return {
  __DANGEROUS_INSECURE_CONNECTION__ = true,
}

The desktop will accept the connection and show an insecure badge on the session tab. The field name is intentionally verbose — it must be set explicitly to acknowledge the risk.

Console API key¶

The Console plugin can evaluate Lua inside the running game. If console is included, configure a strong apiKey and match it in Feather desktop Settings:

return {
  include = { "console" },
  apiKey = "a-long-random-per-session-secret",
}

Doctor reports whether the key is configured or weak, but does not print the key value.

MCP Access¶

Feather can expose live desktop sessions to AI clients through a local Model Context Protocol server:

feather mcp
feather mcp --transport http
feather mcp setup --client codex
feather mcp setup --client claude

Enable Feather → Settings → Security → MCP Access first. The desktop bridge binds to 127.0.0.1:4005, is disabled by default, and requires a generated bearer token. The CLI reads that token from ~/.feather/mcp.json, or from FEATHER_MCP_TOKEN / --token.

Use feather mcp setup --client codex to install the Feather MCP server entry into ~/.codex/config.toml. Use feather mcp setup --client claude to install the Claude Code user entry into ~/.claude.json, or add --scope project to write a project .mcp.json. Restart the client after setup so the tools are loaded.

MCP resources expose sanitized JSON snapshots such as sessions, config, logs, performance, debugger state, plugin catalog/live payloads, assets, observers, Shader Graph, Particles Playground, and Texture Lab. MCP tools can control runtime/debugger/plugin workflows, Shader Graph compile/preview/import/export, Particle Playground authoring/export actions, and Texture Lab recipe/generation actions. Console eval still works only when the existing Console gates are satisfied (console included, evalEnabled = true, and matching apiKey). See MCP for setup, resource/tool lists, and troubleshooting.

References: MCP specification, MCP architecture, and MCP transports.

Connecting¶

Feather uses a push-based WebSocket architecture. The desktop app runs a WebSocket server (port 4004 by default), and your game connects to it as a client.

1. Start the Feather desktop app from the releases page.
2. Run your game with Feather enabled — you'll see:

[Feather] WS client created — connecting to 127.0.0.1:4004
[Feather] Connected — handshake complete

The game automatically reconnects if the desktop app is restarted.

Mobile & Remote Devices¶

Android (USB via ADB reverse)¶

Forward the device's localhost:4004 to your computer:

adb reverse tcp:4004 tcp:4004

Then use the default config — the game connects to 127.0.0.1:4004, which ADB routes to your computer:

local debugger = FeatherDebugger({ debug = true })

Android / iOS (Wi-Fi)¶

Point host to your computer's local IP:

local debugger = FeatherDebugger({
  debug = true,
  host = "192.168.1.42",
})

Offline / disk mode¶

Skip WebSocket entirely and write only log files — useful when there's no shared network:

local debugger = FeatherDebugger({
  debug = true,
  mode = "disk",
})

Transfer the .featherlog file from the device and open it in the Feather app via Open Log File.