docs menudevelopment setup

development setup

build from source and load the agent into a compatible app.

what you need

this is a developer workflow for native apps, with no public fpui installer. use a local source checkout, a rust toolchain, a compatible macos arm64 target, and an adapter authored for that exact executable. theme and plugin files supply the customizations; they do not replace the adapter.

injection and patching operate on the native process and its machine code. the target’s ui framework does not select a different engine; its adapter supplies the sites and values to change, and the backends must support the target’s calling conventions. current live demonstrations include controlled gpui targets. signing policy can prevent agent loading or code writes.

build from source

get the framework source and run these commands from its root:

cargo build -p fpui-agent --features frida
cargo build -p fpui-install -p fpui-monitor -p fpui-discover

the debug agent is target/debug/libfpui_agent.dylib. the three tools are built under target/debug/. the frida backend is bundled into the agent; a separate frida runtime installation is not required.

loading the agent

the loader library’s launch_macos path verifies the whole executable against the adapter before starting it with the agent attached. fpui-loader is a library, not a standalone installer command.

for controlled development targets, the agent can also be loaded directly through the operating system. replace every path below with an absolute path to your own compatible test build and files:

DYLD_INSERT_LIBRARIES=/absolute/path/libfpui_agent.dylib \
FPUI_ADAPTER=/absolute/path/adapter.json \
FPUI_THEME=/absolute/path/theme.json \
/absolute/path/target-binary

direct loading does not use the loader’s strict launch gate. the agent reads its executable, reports a non-exact identity, and attempts supported relocation and per-site checks. an unreadable executable stops the agent. FPUI_PLUGINS can additionally point to a plugin configuration, and FPUI_VARIANT=light requests a light theme variant.

three ways to load the agentthe loader launch path refuses a different executable build. direct loading and the wrapper skip that strict launch gate. the agent refuses an unreadable executable, reports a non-exact identity, and checks each supported site before changing it.no matchmatchloader launchwhole-filegaterefusedagent checkseach sitedirect loador wrapper
three ways to load the agentthe loader launch path refuses a different executable build. direct loading and the wrapper skip that strict launch gate. the agent refuses an unreadable executable, reports a non-exact identity, and checks each supported site before changing it.no matchmatchloader launchwhole-filegaterefusedagent checkseach sitedirect loador wrapper

launching without these environment variables leaves this direct-loading path out. live memory patches do not rewrite the executable file; that does not mean every installation method leaves the app bundle unchanged.

wrapping an app

the macos wrapper edits an app bundle’s Contents/Info.plist and ad-hoc re-signs it so normal launches load the agent. it changes the installed bundle and replaces the vendor signature. use it only on an app copy you are prepared to modify.

./target/debug/fpui-install wrap /Applications/Example.app \
  DYLD_INSERT_LIBRARIES=/absolute/path/libfpui_agent.dylib \
  FPUI_ADAPTER=/absolute/path/adapter.json \
  FPUI_THEME=/absolute/path/theme.json

./target/debug/fpui-install unwrap /Applications/Example.app \
  DYLD_INSERT_LIBRARIES FPUI_ADAPTER FPUI_THEME

include FPUI_PLUGINS=/absolute/path/plugins.json when wrapping if you also want plugins, and include FPUI_PLUGINS among the keys when unwrapping. the wrapper uses the direct agent path, with its readable-image requirement and per-site checks.

unwrapping removes the listed keys and re-signs again; it cannot restore the vendor signature. reinstalling or updating from the vendor restores the original bundle. the native ui experiments also use a re-signed app copy, rather than an untouched installed bundle.

an app update may replace the wrapped bundle. verify the new build and its adapter before wrapping again. signing restrictions still apply to live patches; wrapping is not universal compatibility.