---
title: Host Runtime
description: The TypeScript bridge that orchestrates processes and talks to the macOS-native Swift binaries.
---

The host runtime connects the React renderer to macOS. It lives in
`@filedom/host` and is public through the [`filedom/system`](/docs/reference/system)
entry point.

## What it does

The bridge:

- launches and supervises the long-lived native controllers
- turns renderer intent (move this icon, set this color, play this sound) into
  native operations
- keeps macOS-specific behavior out of the React layer
- captures global keyboard input and desktop mouse input

## Mental model

```text
reconciler intent
  -> host bridge command
  -> native controller process
  -> icon movement / input / audio / desktop interaction
```

The bridge is split into modules (daemon for metrics and lifecycle, input,
finder-commands, background, positions, system, system-ui, permissions, and
audio), and its index re-exports the public surface. Native controllers stay
alive across commands instead of being spawned per operation. `IconController`
receives newline-delimited JSON commands over stdio. Keyboard capture and mouse
capture run as separate `InputListener` processes. When Finder Mode launches a
game, the app owns the keyboard tap and streams key events to the game over a
loopback socket.

## Reliability details

- `flushPendingCommands()` waits for in-flight native commands to finish, so a
  fast process exit does not drop moves or a desktop restore. It gives up after
  a timeout so a hung daemon cannot block exit.
- The run log is JSONL in `~/Library/Logs/filedom/`, one file per process.
  Set `FILEDOM_DEBUG=true` for reconciler and template timing events in that
  log, and `FILEDOM_DEBUG_ICONS=true` for icon-pipeline detail. The Swift icon
  daemon keeps its own text log at `/tmp/filedom.log` (override the path with
  `FILEDOM_LOG_FILE`).
- Desktop icon-view settings such as icon size and grid spacing are written
  through CFPreferences, not by editing Finder's plist file, so a relaunched
  Finder reads the new values and not a stale cached copy.

## Read next

- [Swift Runtime](/docs/reference/swift-runtime): the native binaries themselves
- [Architecture](/docs/reference/architecture): where the bridge sits in the stack