START NOW
API Reference

qbraid agents

Manage AI coding agent sessions.

Launch, monitor, and control AI coding agents. Run Claude Code, OpenCode, or Codex in managed tmux sessions. Send instructions, stream transcripts, handle permissions, and orchestrate multiple agents — all from one place. Works locally and on remote compute servers via SSH.

Use this when you want to:

  • Spin up agents on specific repos or projects
  • Watch what agents are doing in real-time
  • Approve or deny tool-use permissions remotely
  • Manage agents running on cloud compute machines
  • Resume previous coding sessions

Getting started:

qbraid agents launch                    # Interactive launch
qbraid agents list                      # Show active sessions
qbraid agents watch <name>              # Stream live activity
qbraid agents send <name> --text "..."  # Send instructions

Usage:

$ qbraid agents [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • register: Register an agent session.
  • deregister: Deregister an agent session.
  • list: List agent sessions.
  • discover: Discover new agent sessions.
  • status: Show detailed status for an agent session.
  • update: Update metadata fields on an agent session.
  • kill: Stop an agent by name, session ID, or PID.
  • readiness: Check this destination before launch.
  • machine: Serve the fleet machine protocol.
  • settings: Inspect or configure agent execution.
  • launch: Launch an AI coding agent.
  • resume: Resume a previous agent session.
  • send: Send text to a running agent’s terminal.
  • read: Read recent terminal output from an agent.
  • notifier: Wake idle agents when inbox mail arrives.
  • approve: Approve a tool-use prompt.
  • watch: Stream agent transcript.
  • attach: Attach to an agent’s terminal.
  • clean: Clean up orphaned sessions.
  • send-to: Send a message to another agent’s inbox.
  • broadcast: Broadcast to multiple agent inboxes.
  • team: Show a team roster with unread counts.
  • hooks: Manage agent lifecycle hooks.
  • inbox: Read messages sent to this agent’s inbox.

qbraid agents register

Register an agent session.

Reads session data from stdin JSON (used by hooks).

Usage:

$ qbraid agents register [OPTIONS]

Options:

  • --help: Show this message and exit.

qbraid agents deregister

Deregister an agent session.

Reads session data from stdin JSON (used by hooks).

Usage:

$ qbraid agents deregister [OPTIONS]

Options:

  • --help: Show this message and exit.

qbraid agents list

List agent sessions.

Use —compute to list on a remote server.

Usage:

$ qbraid agents list [OPTIONS]

Options:

  • -t, --tool <str>: Filter by tool (claude, codeq, codex)
  • --status <str>: Filter by status
  • --tag <str>: Filter by tag (repeatable)
  • --since <str>: Time window (e.g., ‘1h’, ‘30m’, ‘2d’)
  • -c, --compute <str>: SSH alias for remote compute (runs list on remote)
  • -s, --search <str>: Text search across name/cwd/tags
  • -a, --all: Include stopped sessions
  • -l, --limit <int range>: Entries per page [default: 25; x>=1]
  • -p, --page <int range>: Page number (non-interactive mode) [default: 1; x>=1]
  • --sort <str>: Sort by: recent, oldest, name, tool, status, cwd, model [default: recent]
  • --no-interactive: Disable interactive pagination
  • --json: Output as JSON array (for programmatic use)
  • --help: Show this message and exit.

qbraid agents discover

Discover new agent sessions.

Scans transcript files and registers new agent sessions.

Usage:

$ qbraid agents discover [OPTIONS]

Options:

  • -f, --full: Full data enrichment for all sessions (slower)
  • -c, --compute <str>: Sync sessions from remote compute server (SSH alias)
  • --help: Show this message and exit.

qbraid agents status

Show detailed status for an agent session.

Without --compute this reads the local registry, which is per-host: an agent on another machine is simply absent and reports as not found.

Usage:

$ qbraid agents status [OPTIONS] {session_id}

Arguments:

  • session_id: Session ID (full or prefix) [required]

Options:

  • -c, --compute <str>: SSH alias for remote compute
  • --help: Show this message and exit.

qbraid agents update

Update metadata fields on an agent session.

Usage:

$ qbraid agents update [OPTIONS] {session_id}

Arguments:

  • session_id: Session ID (full or prefix) [required]

Options:

  • --tag <str>: Tag to add (can be repeated)
  • --name <str>: Set terminal name for the session
  • --model <str>: Set model name (e.g. claude-sonnet-4-20250514)
  • --cwd <str>: Set working directory for the session
  • --status <str>: Set session status (working, waiting, idle, error, stopped)
  • --help: Show this message and exit.

qbraid agents kill

Stop an agent by name, session ID, or PID.

With --compute the agent is stopped on that machine. Without it, an agent running elsewhere is simply not in this host’s registry and reports as not found — the registry is per-host.

Usage:

$ qbraid agents kill [OPTIONS] {target}

Arguments:

  • target: Agent name, ID prefix, or PID [required]

Options:

  • -f, --force: Use SIGKILL instead of SIGTERM
  • -c, --compute <str>: SSH alias for remote compute
  • --help: Show this message and exit.

qbraid agents readiness

Check this destination before launch.

Known blockers exit with status 1.

Usage:

$ qbraid agents readiness [OPTIONS]

Options:

  • --tool <str>: Provider to inspect: claude, codex, or codeq. [required]
  • --cwd <str>: Working directory on this machine.
  • --approval <ask|auto|manual|auto-review|yolo>
  • --execution-mode <native|workspace|container>
  • --json: Print structured checks and recovery actions.
  • --verify-auth: Explicitly check provider authentication; does not sign in or transfer credentials.
  • --help: Show this message and exit.

qbraid agents machine

Serve the fleet machine protocol.

Protocol v1 writes only JSON frames to stdout.

Usage:

$ qbraid agents machine [OPTIONS]

Options:

  • --serve: Serve JSON lines over authenticated SSH stdin/stdout.
  • --once: Read one JSON request from stdin and return one response.
  • --help: Show this message and exit.

qbraid agents settings

Inspect or configure agent execution.

Defaults are shared by the CLI and dashboard on this machine.

Usage:

$ qbraid agents settings [OPTIONS]

Options:

  • --execution-mode <native|workspace|container>: Save the Codex execution default for this machine.
  • --reset: Remove this machine’s execution preference.
  • --json: Print structured settings and sandbox readiness.
  • --help: Show this message and exit.

qbraid agents launch

Launch an AI coding agent.

Uses the owning Lab terminal when available; otherwise starts in tmux.

Detached agents may wait for approval until you open their terminal or dashboard. Approval and execution mode are independent and remembered for resume. —approval auto disables approval prompts; —execution-mode container explicitly uses the current user’s access without an extra Codex sandbox. Choose it only where you trust the surrounding machine/container isolation.

Usage:

$ qbraid agents launch [OPTIONS]

Options:

  • --backend <auto|jupyter|tmux>: auto: prefer the owning Lab terminal; jupyter: require Lab; tmux: run independently. [default: auto]
  • -t, --tool <str>: Agent tool (claude, codeq, codex; claude-auto = claude —approval auto)
  • --cwd <str>: Working directory
  • -n, --name <str>: Agent name
  • -i, --instructions <str>: Initial instructions
  • -r, --repo <str>: GitHub repo URL, org/repo, or issue/PR URL
  • --type <str>: Agent type: leader, worker, observer, reviewer
  • --parent <str>: Parent session ID
  • --team <str>: Team ID
  • --tag <str>: Tags (repeatable)
  • -c, --compute <str>: SSH alias for remote compute server
  • --request-id <str>: Remote launch UUID retained for reconciling an interrupted request.
  • --execution-mode <native|workspace|container>: Codex only: native uses Codex defaults; workspace adds its workspace sandbox; container uses current user access without an extra Codex sandbox (no sudo). Omitted preserves existing behavior. Independent of —approval.
  • --approval <ask|auto|manual|auto-review|yolo>: manual: the agent asks you. auto-review: the tool’s own automatic reviewer decides. yolo: no permission checks. ask/auto: legacy modes, unchanged.
  • --yolo: Claude: skip permissions. Codex: bypass approvals and its sandbox.
  • --help: Show this message and exit.

qbraid agents resume

Resume a previous agent session.

Resumes with the selected terminal backend. With --compute the session is resumed on that machine, and a session id is required — the interactive picker reads the local registry and cannot see another host’s sessions.

Usage:

$ qbraid agents resume [OPTIONS] [session_id]

Arguments:

  • session_id: Session ID, prefix, or name. Omit for interactive picker.

Options:

  • --backend <auto|jupyter|tmux>: auto: prefer the owning Lab terminal; jupyter: require Lab; tmux: run independently. [default: auto]
  • -n, --name <str>: Agent name for the resumed session
  • --execution-mode <native|workspace|container>: Override the recorded Codex execution mode for this resume.
  • --approval <ask|auto|manual|auto-review|yolo>: Override recorded permissions for this resume. Omit to preserve them.
  • -c, --compute <str>: SSH alias for remote compute
  • --help: Show this message and exit.

qbraid agents send

Send text to a running agent’s terminal.

Usage:

$ qbraid agents send [OPTIONS] {session_id}

Arguments:

  • session_id: Session ID (prefix match) [required]

Options:

  • -m, --text <str>: Text to send [required]
  • -c, --compute <str>: SSH alias for remote compute
  • --help: Show this message and exit.

qbraid agents read

Read recent terminal output from an agent.

Usage:

$ qbraid agents read [OPTIONS] {session_id}

Arguments:

  • session_id: Session ID (prefix match) [required]

Options:

  • -n, --lines <int>: Number of lines to capture [default: 50]
  • -c, --compute <str>: SSH alias for remote compute
  • --help: Show this message and exit.

qbraid agents notifier

Wake idle agents when inbox mail arrives.

Inbox delivery is passive: an agent parked at its prompt never notices a message. This watches the inboxes of this machine’s managed agents and types a one-line nudge into an idle agent’s pane. Busy agents are left alone until they go idle, and a burst of messages is one nudge.

qBraid Lab runs this for you. Use it on a machine reached only over SSH. Same-host: it watches the inboxes on the machine it runs on.

Usage:

$ qbraid agents notifier [OPTIONS]

Options:

  • -i, --interval <float range>: Seconds between checks [default: 4.0; x>=1.0]
  • --once: Check once, print who was nudged, and exit
  • --help: Show this message and exit.

qbraid agents approve

Approve a tool-use prompt.

Sends ‘y’ + Enter to the agent’s terminal. With --compute the approval is sent on that machine.

Usage:

$ qbraid agents approve [OPTIONS] {session_id}

Arguments:

  • session_id: Session ID (prefix match) [required]

Options:

  • -c, --compute <str>: SSH alias for remote compute
  • --help: Show this message and exit.

qbraid agents watch

Stream agent transcript.

Streams live transcript from an agent session.

Usage:

$ qbraid agents watch [OPTIONS] {session_id}

Arguments:

  • session_id: Session ID (prefix match) [required]

Options:

  • -n, --lines <int>: Initial history lines [default: 20]
  • --interactive / --no-interactive: Prompt for permission decisions [default: interactive]
  • --stream: Stream-only mode: emit JSON events, no interactive prompts (for frontends)
  • -c, --compute <str>: SSH alias for remote compute
  • --help: Show this message and exit.

qbraid agents attach

Attach to an agent’s terminal.

Reconnects to its recorded native terminal or tmux window.

Usage:

$ qbraid agents attach [OPTIONS] [session_id]

Arguments:

  • session_id: Session ID (prefix match). Omit for interactive picker.

Options:

  • -c, --compute <str>: SSH alias for remote compute
  • --help: Show this message and exit.

qbraid agents clean

Clean up orphaned sessions.

Removes orphaned tmux windows and stopped sessions.

Usage:

$ qbraid agents clean [OPTIONS]

Options:

  • -y, --yes: Skip confirmation
  • --help: Show this message and exit.

qbraid agents send-to

Send a message to another agent’s inbox.

For multi-recipient / team broadcast, use qbraid agents broadcast.

Same-host only: an inbox is a JSONL file under ~/.qbraid/inboxes/ on the machine that owns it, so there is no --compute. Cross-host messaging needs a transport, tracked in qBraid-CLI#328 / qbraid-core#307.

Delivery is a JSONL append at ~/.qbraid/inboxes/<to-session-id>.jsonl (local host only — cross-host messaging isn’t yet supported and will raise a clear error). Permission rules (leader/worker/observer/reviewer) are enforced by default.

Usage:

$ qbraid agents send-to [OPTIONS] {to} {text}

Arguments:

  • to: Target session id (full or prefix), tmux window name, or terminal name. [required]
  • text: Message body. [required]

Options:

  • --from <str>: Sender session id. Defaults to $QBRAID_SESSION_ID (set by the qBraid launcher for every managed agent shell).
  • --type <str>: One of: message, task_assignment, status_update, shutdown_request. Controls how the recipient’s UI/hooks categorize it. [default: message]
  • --no-permission-check: Skip the sender→target permission check (agent-type rules from qbraid_core.services.agents.types.can_message). Use for testing.
  • --help: Show this message and exit.

qbraid agents broadcast

Broadcast to multiple agent inboxes.

Same-host only: an inbox is a JSONL file under ~/.qbraid/inboxes/ on the machine that owns it, so there is no --compute. Cross-host messaging needs a transport, tracked in qBraid-CLI#328 / qbraid-core#307.

Two selectors — pick exactly one:

  • --team &lt;team_id&gt; — every session with that team_id (except sender)
  • --to A,B,C — explicit id/prefix/name list

Delivery is all-or-nothing on target resolution: if any target can’t be resolved, NOTHING is sent (avoids partial-delivery surprises). Once resolved, per-target send failures are reported individually; a partial delivery exits with code 3.

Usage:

$ qbraid agents broadcast [OPTIONS] {text}

Arguments:

  • text: Message body — delivered to every target. [required]

Options:

  • --team <str>: Deliver to every session with this team_id (excluding the sender). Use one of —team or —to.
  • --to <str>: Comma-separated list of target session ids/prefixes/names for multi-recipient send. Use one of —team or —to.
  • --from <str>: Sender session id. Defaults to $QBRAID_SESSION_ID.
  • --type <str>: One of: message, task_assignment, status_update, shutdown_request. Controls how the recipient’s UI/hooks categorize it. [default: message]
  • --no-permission-check: Skip the sender→target permission check. Use for testing.
  • --help: Show this message and exit.

qbraid agents team

Show a team roster with unread counts.

Same-host only: an inbox is a JSONL file under ~/.qbraid/inboxes/ on the machine that owns it, so there is no --compute. Cross-host messaging needs a transport, tracked in qBraid-CLI#328 / qbraid-core#307.

Answers the leader-orchestrator question “who is on my team, how many unread messages do they have, and what was the last thing they heard from anyone?” — which today requires peeking each worker’s inbox individually.

Rows are sorted with the current session first (identified via $QBRAID_SESSION_ID), then by agent_type (leader → worker → observer → reviewer), then by session_id.

Usage:

$ qbraid agents team [OPTIONS] {team_id}

Arguments:

  • team_id: Team identifier (matches AgentSession.team_id). [required]

Options:

  • -w, --wide: Show full session ids instead of the 12-char prefix.
  • --help: Show this message and exit.

qbraid agents hooks

Manage agent lifecycle hooks.

Usage:

$ qbraid agents hooks [OPTIONS] COMMAND [ARGS]...

Options:

  • --help: Show this message and exit.

Commands:

  • install: Install agent lifecycle hooks.
  • uninstall: Remove agent lifecycle hooks.

qbraid agents hooks install

Install agent lifecycle hooks.

Installs hooks for AI coding tools.

Usage:

$ qbraid agents hooks install [OPTIONS]

Options:

  • -t, --tool <str>: Install hooks for a specific tool (claude, codeq, codex)
  • --help: Show this message and exit.

qbraid agents hooks uninstall

Remove agent lifecycle hooks.

Removes hooks from all supported tools.

Usage:

$ qbraid agents hooks uninstall [OPTIONS]

Options:

  • --help: Show this message and exit.

qbraid agents inbox

Read messages sent to this agent’s inbox.

Follow, filter unread, and mark-read messages sent to this agent session’s inbox. Inboxes are per-session JSONL files at ~/.qbraid/inboxes/. Every agent session has one; peers use qbraid agents send-to to write to it.

Usage:

$ qbraid agents inbox [OPTIONS] COMMAND [ARGS]...

Options:

  • -s, --session <str>: Session whose inbox to read. Accepts full id, prefix, or tmux/terminal name (resolved via the registry). Defaults to $QBRAID_SESSION_ID.
  • -f, --follow: Stream new messages as they arrive.
  • -u, --unread: Show only unread messages.
  • -n, --limit <int>: Max messages to show (most recent). [default: 50]
  • --mark-read / --no-mark-read: Mark shown messages as read after display. Default on. [default: mark-read]
  • -w, --wide: Show full session ids in the From column and title (not the 12-char prefix). Use when multiple senders share a prefix.
  • --help: Show this message and exit.

Commands:

  • mark-read: Mark inbox messages as read.

qbraid agents inbox mark-read

Mark inbox messages as read.

Without —message-id, marks every unread message in the session’s inbox.

Usage:

$ qbraid agents inbox mark-read [OPTIONS]

Options:

  • -s, --session <str>: Session whose inbox to update. Accepts full id, prefix, or tmux/terminal name. Defaults to $QBRAID_SESSION_ID.
  • -m, --message-id <str>: Specific message id(s) to mark. May be passed multiple times. Omit to mark ALL unread messages in the inbox.
  • --help: Show this message and exit.
© 2026 qBraid