The Host Daemon

ps-bash -c "<command>" does not start PowerShell from scratch each time. A cold PowerShell runspace takes a second or more, which is too slow when an AI agent runs hundreds of commands. So the ps-bash launcher hands each command to a long-lived background process, ps-bash-host, and exits once the command finishes.

This page covers what that process is, how many you should expect to see, and how to change its behaviour.

---

One warm host per session

The first ps-bash -c in a session starts a ps-bash-host. Every later -c from the same session reuses it, so only the first command pays the startup cost.

Each command still gets a clean PowerShell session. The host keeps a small pool of pre-warmed runspaces, hands each command its own runspace, and throws that runspace away when the command ends. Variables, functions and cd from one -c don’t leak into the next.

What counts as a session. The launcher walks up its process tree to the nearest long-lived shell or agent: pwsh, powershell, cmd, bash, zsh, fish, node, bun, deno, python, claude, opencode. That process is the session anchor. Every ps-bash -c under the same anchor shares one host. Two terminal windows or two agents get separate hosts, so one busy agent never queues behind another.

When the host exits

Situation	Host exits
The session anchor (your terminal, your agent) exits	About 5 s after its last command finishes
No command for PSBASH_HOST_IDLE_SECS (default 600 s)	When the idle time runs out
PSBASH_PER_INVOCATION=1	With the launcher, after every command
ps-bash host shutdown	Right away (graceful)

The anchor rule means a host never outlives its session by more than a few seconds. Closing the terminal or ending the agent cleans up its host.

Seeing several ps-bash-host processes?

One host per open terminal or agent is expected. So is a short-lived extra one for a nested bash -c inside a script. Up to v0.11.5, an agent whose own process name wasn’t on the list above could leave one host per command, each idling for 10 minutes (#7). From v0.11.6 each of those hosts exits a few seconds after its command. To get a single warm host for the whole agent session, set PSBASH_SESSION (below).

Environment variables

Set these in the environment of the shell or agent that runs ps-bash. For an agent, that means setting them before you start it.

Variable	Default	Effect
PSBASH_SESSION	(automatic)	Fixed session name. Every ps-bash -c with the same value shares one host, whatever process tree it runs in. The host then exits only on idle (PSBASH_HOST_IDLE_SECS), because no single process stands for the session.
PSBASH_PER_INVOCATION	0	1 gives every ps-bash -c its own private host that exits with it. No process is left behind, but every command pays a cold start.
PSBASH_HOST_IDLE_SECS	600	Seconds a host with no running command waits before exiting.
PSBASH_POOL_WARM	2	Pre-warmed runspaces the host keeps ready. 0 builds each runspace on demand.
PSBASH_POOL_MAX	CPU count, clamped to 2–8	Most commands one host runs at once.
PSBASH_STARTUP_TIMEOUT	60	Seconds a launcher waits for a new host to come up.
PSBASH_IPC_ENDPOINT	(automatic)	Explicit unix:<path> or pipe:<name> endpoint. Mostly for tests. Like PSBASH_SESSION, the host exits only on idle.

Recipes

An agent launched from PowerShell: one warm host for the whole session

$env:PSBASH_SESSION = "claude"
claude

Nothing left running between commands (slower)

$env:PSBASH_PER_INVOCATION = "1"

Shorter idle time

$env:PSBASH_HOST_IDLE_SECS = "60"

Managing the host by hand

ps-bash host status     # is this session's host up, and which endpoint is it on?
ps-bash host start      # warm it now so the next command is fast (alias: warm)
ps-bash host restart    # replace it, e.g. after upgrading ps-bash
ps-bash host shutdown   # stop it

These act on the current session’s host, the one a ps-bash -c from this shell would use.

Tip

PSBASH_PER_INVOCATION=1 is the only mode where nothing runs between commands. Use it when you care about stray processes more than about latency, for example in a CI step that runs a single command.