Processes & Environment

Spawning processes

COMPOSITOR.process launches external programs. There are three methods, differing in how the compositor tracks the process.

Method	Lifecycle	Use for
`once(id, spec)`	Run once at startup	Daemons/agents that start with the session
`service(id, spec)`	Long-running, monitored & restarted	Watchers that must stay alive
`spawn(spec)`	Fire-and-forget, untracked	On-demand launches (keybindings)

`once`

Runs a command once at session startup.

COMPOSITOR.process.once('fcitx5', {
  command: 'fcitx5 -d',
  runPolicy: 'once-per-session',
});

runPolicy controls re-runs:

"once-per-session" (default) — run a single time per login session.
"once-per-config-version" — also re-run after the config changes (hot reload).

`service`

Starts a long-running process the compositor monitors and restarts.

COMPOSITOR.process.service('cliphist-text', {
  command: ['wl-paste', '--type', 'text', '--watch', 'cliphist', 'store'],
  restart: 'on-exit',
});

restart policy: "never", "on-failure" (restart only on non-zero exit), or "on-exit" (always restart).

`spawn`

Launches a process and forgets it — not tracked or restarted. Ideal inside keybinding handlers.

COMPOSITOR.key.bind('terminal', 'Super+T', () => {
  COMPOSITOR.process.spawn({command: ['kitty']});
});

The command spec

Every method takes a spec with a command, plus optional cwd and env:

Field	Type	Meaning
`command`	`string \| string[]`	The program to run (see below)
`cwd`	`string`	Working directory
`env`	`Record<string, string \| number \| boolean>`	Extra environment for this process

How command is interpreted:

A single string runs via /bin/sh -lc <command>, so shell features (pipes, redirection, ~, env expansion) work:
```
COMPOSITOR.process.spawn({command: 'hyprshot -m region --raw | swappy -f -'});
```
A string array is exec'd directly with no shell — each element is one argv entry, taken literally (safer, no quoting pitfalls):
```
COMPOSITOR.process.spawn({command: ['kitty', '--title', 'My Terminal']});
```

Environment variables

COMPOSITOR.env manages the environment inherited by processes the compositor spawns. Changes affect processes started after the call; running processes are unaffected unless you publish.

COMPOSITOR.env.set('QT_QPA_PLATFORM', 'wayland;xcb');

COMPOSITOR.env.apply({
  QT_IM_MODULE: 'fcitx',
  XMODIFIERS: '@im=fcitx',
  MOZ_ENABLE_WAYLAND: 1,
});

Method	Meaning
`set(key, value)`	Set one variable (value may be string/number/boolean)
`unset(key)`	Remove a variable
`get(key)`	Read the current value (`string \| undefined`)
`apply(values)`	Bulk set; pass `null`/`undefined` as a value to unset that key
`publish(keys?)`	Broadcast the current env to running services; all keys if omitted

tip

Set environment variables before spawning the processes that need them. The default config sets the Qt platform and input-method variables near the top, then launches the relevant apps afterward.

Spawning processes​

once​

service​

spawn​

The command spec​

Environment variables​