xa.hosts

Host abstraction — local, SSH, HTTP backends.

A Host is anything that can enumerate Claude Code sessions and perform lifecycle actions on them (spawn / resume / kill). All transports return the same xa.sessions.Session shape so higher layers don’t care whether sessions live on this machine, on another machine over SSH, or behind another xa server over HTTPS.

The protocol is duck-typed (runtime_checkable), so user extensions only need to implement the methods they actually use — unused methods can raise NotImplementedError.

Functions

default_hosts()

The out-of-the-box registry: one local host, nothing else.

Classes

Host(*args, **kwargs)	Duck-typed interface every transport satisfies.
LocalHost([name, claude_home, claude_bin, ...])	The machine xa is running on.
SSHHost(name, *, host[, user, ...])	Transcripts via rsync; actions via ssh exec.
HTTPHost(name, *, base_url[, auth, ...])	Client for a remote xa serve instance.

class xa.hosts.HTTPHost(name, *, base_url, auth=None, username=None, password=None, token=None, timeout=30.0)

Bases: object

Client for a remote xa serve instance.

sync(*, force=False)

HTTP sessions are fetched fresh on each listing — no separate sync.

Return type:

None

class xa.hosts.Host(*args, **kwargs)

Bases: Protocol

Duck-typed interface every transport satisfies.

class xa.hosts.LocalHost(name='local', *, claude_home=PosixPath('/home/runner/.claude'), claude_bin='claude', tmux_bin='tmux', alive_predicate=None)

Bases: object

The machine xa is running on.

sync(*, force=False)

No-op — local has nothing to sync.

Return type:

None

class xa.hosts.SSHHost(name, *, host, user=None, remote_claude_home='~/.claude', cache_dir=PosixPath('/home/runner/.cache/xa/remotes'), stale_threshold_sec=3600, claude_bin='claude', tmux_bin='tmux', ssh_bin='ssh', rsync_bin='rsync')

Bases: object

Transcripts via rsync; actions via ssh exec.

Parameters:

• name (str) – Logical name used in Session.host and elsewhere.

• host (str) – SSH hostname / alias. Matches cc-sessions: either an ~/.ssh/config alias (devbox) or a raw host (1.2.3.4).

• user (Optional[str]) – Optional SSH user for raw hosts.

• remote_claude_home (str) – Remote path to ~/.claude/. Defaults to ~/.claude which resolves relative to the SSH user’s home on the remote side.

• cache_dir (Path) – Where to stage the rsync’d tree locally.

• stale_threshold_sec (int) – Re-sync when the cached copy is older than this. 0 means always sync.

spawn(name, *, cwd, **opts)

Spawn tmux new-session -d 's <name>' 'cd <cwd> && exec claude' over SSH.

URL detection is left to the caller’s next sync() + listing — we don’t round-trip waiting for the bridge URL here (that would hold an SSH connection open for up to 2 minutes).

Return type:

SpawnResult

sync(*, force=False)

Pull <remote_claude_home>/projects/ and /sessions/ into the cache.

Non-existent remote directories are tolerated (rsync returns 23).

Return type:

None

xa.hosts.default_hosts()

The out-of-the-box registry: one local host, nothing else.

Return type:

dict[str, Host]

Modules

http	HTTP host — a remote xa serve instance.
local	Local in-process host.
ssh	SSH-backed host.