View as markdown

Daemons in Hub

A daemon is one of your machines running the Paseo daemon. Enroll it once with your Hub organization, grant execution permission, and reference its slug in your triggers.

Connect a daemon

Log in from the machine first:

paseo hub login https://hub.example.com

The CLI prints a URL and verification code and opens your browser. After approval, Paseo stores an organization-scoped CLI login under PASEO_HOME.

In an interactive terminal, login offers to connect this daemon and separately asks whether to allow Hub automations to run agents. Connection defaults to yes, and execution permission defaults to no. --json and non-TTY logins do not prompt.

If you skipped connection during login, enroll the daemon separately:

paseo hub connect

connect uses your active login to request a single-use enrollment token. The daemon exchanges that token for its own relationship credential, so your CLI login is never stored as daemon authority.

Hub derives the daemon's initial slug from its hostname using lowercase words joined by hyphens, such as build-studio. If that slug is already taken in the organization, Hub appends a short daemon ID suffix.

You can rename the slug later in Hub without changing the immutable daemon ID, then update any triggers that reference the old slug.

For unattended setup, pass an organization API key through the environment:

PASEO_HUB_URL=https://hub.example.com PASEO_HUB_API_KEY=paseo_pk_... paseo hub connect

Origin precedence is explicit [origin] or --hub, then PASEO_HUB_URL, then the active stored login, then https://hub.paseo.sh. An explicit --api-key <secret> takes precedence over environment variables and stored logins.

Check status or disconnect a daemon:

paseo hub status
paseo hub disconnect
paseo hub disconnect --force   # drop local authority when Hub is unreachable

One daemon connects to one Hub organization at a time. Connecting a daemon that already belongs to a Hub is refused.

paseo hub logout removes the stored CLI login. In an interactive terminal, it offers to disconnect a daemon connected to the same Hub first. In --json or non-interactive mode, logout never disconnects the daemon unless you pass --disconnect-daemon:

paseo hub logout --disconnect-daemon
paseo hub logout --disconnect-daemon --force

Grant execution permission

Enrolling a daemon does not allow Hub to start agents on it. Grant the hub.execute permission from that machine:

paseo hub permissions list
paseo hub permissions grant hub.execute
paseo hub permissions revoke hub.execute

Until hub.execute is granted, Hub tracks the daemon for identity and presence only. Daemons marks it as Connected only and Home notes that it cannot run agents. See Choose daemon authority for what hub.execute permits.

Target a daemon from a trigger

Reference the daemon slug and an existing working directory under run.target:

name: repo-triage
on:
  manual.run: {}
run:
  target:
    daemon: my-macbook
    cwd: /Users/you/code/your-repo
  agent:
    provider: codex
    mode: full-access
  prompt: Inspect the repository status and call hub.finish_execution.

daemon resolves to the immutable daemon ID when you save or deploy the trigger. cwd is an absolute path that already exists on that machine. Hub does not clone repositories for you.

To isolate each run on its own git branch instead of editing your working tree, add a worktree block:

name: isolate-fix
on:
  manual.run: {}
run:
  target:
    daemon: build-server
    cwd: /workspace/project
    worktree:
      mode: branch-off
      newBranch: trigger-${{ paseo.execution.id }}
      base: origin/main
  agent:
    provider: codex
    mode: full-access
  prompt: Run tests and call hub.finish_execution.

${{ paseo.execution.id }} renders the execution UUID, giving each run a unique branch off origin/main that survives retries and recovery. See Trigger YAML reference and Git worktrees.

Provider discovery

When you select a daemon and working directory in the Hub trigger editor, Hub asks that daemon for its configured providers, models, execution modes, and thinking options.

Hub works with any provider configured on your Paseo daemon, including Claude Code, Codex, OpenCode, Pi, and custom or plugin providers.

Recovery and ownership

For agents it dispatches, Hub owns creation, reconnect recovery, output tracking, and completion. Agents you start locally are untouched.

If Hub loses the create response or the daemon restarts mid-run, Hub resends the same create intent with the same execution ID. The daemon returns the existing agent instead of running the prompt twice. If an agent closes or crashes, Hub marks the run interrupted and does not silently start a second agent.

Daemon status

StatusMeaning
Approval requiredThe CLI is waiting for browser approval.
ConnectedOnline and connected to Hub.
OfflineEnrolled, but not currently connected.
RevokedAccess was removed from Hub.

While the daemon is offline, you can save dashboard edits that keep the same target and agent settings, such as a prompt change. paseo hub deploy and direct API installs require a connected target daemon even for that edit. See trigger validation.

Revoking from Daemons → Revoke daemon ends the relationship from Hub's side while leaving local agents running.

Sponsors

⌂ 换网址