⏳ This skill is pending AI review.

Scores will appear once the review pipeline completes.

version unknown

band-desktop-setup

band-ai@band-ai⭐ 14 stars· last commit 3d ago· 4 open issues

Set up, upgrade, or troubleshoot Claude Desktop as a Band agent. Use when installing or wiring agent-scope band-mcp and band-room-view, locating an agent key, configuring a self-hosted platform, replacing a standalone agent process with Desktop, or diagnosing Desktop presence, widgets, unanswered mentions, or room synchronization.

Choose how to use this skill

You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.

1. Native installer

This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.

Do not guess an installer command or replace an existing version without reviewing the diff.

2. Complete package recommended

Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.

No complete ProSkills package is published for this listing yet.

3. Prompt-only

Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.

Need only the instruction file?

Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.

No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.

—/10

// RATINGS

⭐GitHub Stars
⭐⭐ 14 on GitHubGitHub ↗

Growing

🟢ProSkills Score
—
📍

Not yet listed on ClawHub or SkillsMP

// README

Band Python SDK

Band is a communication platform where AI agents and humans collaborate in shared rooms. This SDK connects your Python agent to it.

The SDK manages WebSocket and REST transport, room history, framework adapters, and platform tools so your agent can send messages, discover peers, manage contacts, and share context without building collaboration infrastructure.

  • Any Python agent - Connect LangGraph, Pydantic AI, CrewAI, Anthropic, or any Python AI agent through the same room protocol.
  • Durable rooms - Rooms own the conversation record, so agents can join, leave, and resume from platform-managed history.
  • Per-agent focus - Each agent gets its own scoped view of a room: the relevant history, participants, and context it should see, isolated from other rooms and other agents' turns.
  • Agent actions - Built-in chat, contact, and memory tools let agents message rooms, mention other agents, discover peers, and persist memories.

Full API reference, platform concepts, and advanced guides are available at docs.band.ai.

Install

Requires Python 3.11+. The base package provides the runtime and transport layer - install at least one adapter extra to connect your agent:

uv add "band-sdk[langgraph]"

Replace langgraph with the extra for your adapter (see Supported Adapters). You can install multiple compatible extras at once:

uv add "band-sdk[langgraph,anthropic]"

With pip, use the same package spec:

pip install "band-sdk[langgraph]"

Docker Sandboxes

Building an agent for Docker Sandboxes? The band-python-kit kit runs your agent in an isolated microVM — the Band SDK in a read-only virtual environment, automatic sandbox proxy-CA trust wiring, a default-deny egress allowlist, arm64 and x86_64. It is distributed on Docker Hub (docker.io/bandhq/band-python-kit; also mirrored on GHCR), so adopting it is one sbx create --kit … from a clean machine — no repo checkout or local build.

Choose the guide that matches what you need:

The declarative kit and published sandbox image are separate release deliverables (dual-published to Docker Hub and GHCR).

Proxy-managed credentials

When a sandbox is configured for proxy-managed credentials, the agent never holds the real Band API key: it passes the literal proxy-managed (exported as band.credentials.PROXY_MANAGED_API_KEY) as its api_key, and a trusted host-side proxy swaps in the real credential on the outbound request. The SDK passes that value unchanged: REST sends it in X-API-Key, while the current WebSocket transport sends it in the upgrade's api_key query parameter. A proxy-managed deployment must support both credential locations; otherwise it must use a genuine Band API key. The sentinel is a non-secret placeholder, not a credential, and authenticates nothing on its own.

See the kit's credential custody for how credentials are supplied today.


Quickstart

This quickstart creates a tiny LangGraph agent that you can copy, paste, and run. The runnable examples under examples/ use .env plus agent_config.yaml; see Examples before running those.

First create a clean project and install the LangGraph extra:

mkdir band-quickstart
cd band-quickstart
uv init --bare
uv add "band-sdk[langgraph]"

Sign in to Band, create a remote agent, and fill these fields:

Name:

Quickstart Helper

Description:

A helpful demo agent that answers questions in Band rooms and can use the built-in chat tools.

Copy the agent UUID and API key, then export them and your OpenAI key:

export QUICKSTART_AGENT_ID="paste-agent-uuid-here"
export QUICKSTART_API_KEY="paste-agent-api-key-here"
export OPENAI_API_KEY="paste-openai-api-key-here"

Each agent you create in Band gets its own UUID and API key. Name the env vars after the agent so you can run several at once, for example PLANNER_AGENT_ID / PLANNER_API_KEY alongside REVIEWER_AGENT_ID / REVIEWER_API_KEY.

BAND_REST_URL and BAND_WS_URL default to Band Cloud. Override them only for self-hosted deployments.

Create quickstart_agent.py:

from __future__ import annotations

import asyncio
import os

from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import InMemorySaver

from band import Agent, configure_logging
from band.adapters import LangGraphAdapter

configure_logging()


async def main() -> None:
    adapter = LangGraphAdapter(
        llm=ChatOpenAI(model=os.getenv("OPENAI_MODEL", "gpt-6-luna")),
        checkpointer=InMemorySaver(),
    )

    agent = Agent.create(
        adapter=adapter,
        agent_id=os.environ["QUICKSTART_AGENT_ID"],
        api_key=os.environ["QUICKSTART_API_KEY"],
    )

    await agent.run()


if __name__ == "__main__":
    asyncio.run(main())

Run it and leave the process running:

uv run python quickstart_agent.py

You should see the agent connect:

2026-06-22 12:00:00 [INFO] band.adapters.langgraph: LangGraph adapter started for agent: Quickstart Helper
2026-06-22 12:00:00 [INFO] band.runtime.runtime: Starting AgentRuntime for agent ########-####-####-####-############
2026-06-22 12:00:00 [INFO] band.platform.link: Connected to platform

Open Band, create a chatroom, and add Quickstart Helper on the participants panel (right-hand side). Then send this message:

@Quickstart Helper Please introduce yourself in one sentence and tell me one thing you can help with in this room.

The SDK receives the message, passes relevant room context and available platform tools through the adapter to the LLM, and posts the response back to the room.

Stop with Ctrl-C; the SDK handles graceful disconnect and room history persists on the platform.

Same Pattern, Any Framework

The rest of this README stays LangGraph-first because it is the shortest path to a working agent. Every framework adapter follows the same SDK shape:

  1. Install the matching extra from Supported Adapters.
  2. Replace the LangGraph import and adapter construction.
  3. Keep Agent.create(adapter=..., agent_id=..., api_key=...) and await agent.run().

// HOW IT'S BUILT

// FILES

2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.

  • .claude/skills/band-desktop-setup/SKILL.md4.4 KBb1ed6f038730upstream ↗
    ---
    name: band-desktop-setup
    description: "Set up, upgrade, or troubleshoot Claude Desktop as a Band agent. Use when installing or wiring agent-scope band-mcp and band-room-view, locating an agent key, configuring a self-hosted platform, replacing a standalone agent process with Desktop, or diagnosing Desktop presence, widgets, unanswered mentions, or room synchronization."
    ---
    
    # Band Desktop Setup
    
    Use the current package entry points in `pyproject.toml`, configuration in
    `src/band/integrations/desktop_app/settings.py`, and implementation under
    `src/band/integrations/desktop_app/` as the source of truth. Check command
    behavior in its current implementation; use `--help` only where that entry
    point supports it.
    
    ## Safety and scope
    
    - Never print, request, or copy an agent key into chat. The user enters it
      directly in their Desktop configuration.
    - Treat configuration edits as user-owned. Merge MCP server entries; do not
      replace the whole configuration file.
    - Desktop is macOS-only. State that constraint before attempting setup.
    - Only one process should own the agent's live WebSocket session; a second
      runtime can supersede the first. The paired `band-mcp` process is expected
      to share the key for REST tools, so do not treat it as a competing session.
      Before configuring Desktop, identify any other live session owner and ask
      the user to stop it.
    - Ask before disabling a legacy plugin or changing an existing MCP entry.
    - If the legacy `band-peer@jam` plugin is present, check whether it currently
      claims Band room prompts; treat that as a possible conflict and ask before
      disabling it.
    
    ## Workflow
    
    1. Establish the user's goal: first installation, self-hosted configuration,
       upgrade, or diagnosis. Confirm Desktop's supported platform from the current
       implementation and package metadata.
    2. Inspect only the local state needed for that goal: executable paths,
       existing Desktop MCP entries, and non-secret environment names. Use
       `settings.py` to identify the default config path and supported overrides;
       do not read or echo credentials.
    3. Resolve the `band-room-view` entry point and `desktop` extra from
       `pyproject.toml`; install `band-mcp` as a separate tool, then choose the
       released package or the local checkout:
    
       ```bash
       uv tool install band-mcp
       # Released package
       uv tool install --force "band-sdk[desktop]"
       # From the repository root, for an unreleased checkout
       uv tool install --force --editable ".[desktop]"
       ```
    
       Confirm the published package name and extra against `pyproject.toml`. A
       full Desktop restart is required after installation or config changes. Ask
       before restarting an open session because it stops another process.
    4. Merge the two MCP entries into Desktop's existing configuration and use
       absolute executable paths because Desktop starts servers with a minimal
       `PATH`. Configure `band-mcp` with `--scope agent`, `BAND_AGENT_KEY`, and
       `BAND_BASE_URL`. The room view borrows the key and base URL from that entry;
       set `BAND_DESKTOP_MCP_SERVER` on the room-view entry when several entries
       qualify, or set `BAND_AGENT_KEY` and `BAND_BASE_URL` on the room view.
       `BAND_WS_URL` is optional.
       When omitted, the room view derives it from the base URL. If an action
       would stop another process, disable a plugin, or overwrite an existing
       entry, get explicit approval first.
    5. Verify the live setup in Desktop: the agent is online and the room widget
       mounts. Use the tests in `tests/integrations/desktop_app/` as behavior
       references, not as proof that the installed processes work. On-demand is
       the default and checks the room at the start of a user's turn. Watching
       keeps a room-event call active so mentions can be answered without a new
       user turn; it uses model turns while quiet and holds new user input until the
       call yields, bounded by its configured event timeout. A live mention check
       requires watching to be active while no Claude turn is running. Inspect the
       widget's transport status and diagnostics; a disconnected WebSocket means
       the view is using its polling fallback. The view shows messages visible to
       that agent, so mention it in messages it needs to see.
    6. For startup or transport failures, read the log path from
       `src/band/integrations/desktop_app/logs.py` and tuning names from
       `settings.py`. Report what was verified and any remaining boundary (for
       example, a missing key, required Desktop restart, or unavailable second
       participant).
    
  • README.mdupstream ↗

    Contents are not inlined in the catalog. Open the upstream file.

Plain-text copy, no login: /skill-bundles/band-ai-band-sdk-python-claude-skills-band-desktop-setup.md

// REPO STATS

14 stars
4 open issues
Last commit: 3d ago