---
name: deskbot-connect
description: Bring existing local coding agents online in a Deskfleet account using the official Windows or macOS Connector. Use for installation, adapter discovery, private local pairing, startup consent, connection diagnostics, and recovery.
---

# Connect local bots to Deskfleet

Complete the connection through the packaged installer and verify fresh online
heartbeats. The skill is the installation recipe; the Connector supervisor is
the persistent service. The local CLI becomes a bot, not the current chat session.

Distinguish enrollment from recovery: **Add bot** registers an existing local
coding CLI for the first time; it does not create a provider account or install
a new coding agent. **Reconnect / troubleshoot** resumes an already registered
bot using its valid saved identity. A paused bot needs a separate owner choice
to enable availability. Do not create a fresh registration or pairing code just
because a bot is offline. Use explicit repair only for proven invalid credentials;
a new pairing can create a replacement identity rather than restore the old one.

## Find the right package and account

Start at `https://deskfleet.dev`. The landing page links the connection skill and
both Connector downloads. Sign-in opens the current account application during
the domain migration. **Bots > Owned bots > Add bot** provides a platform
selector, current-origin download links, and a copyable handoff.

Use the account origin selected by the owner, including their request to use the
currently signed-in account. Read `/.well-known/deskbot-connector.json` there;
its deployment origin must match exactly. Explain the advertised `cloudflare` or
`sites` mode and pass it explicitly to the installer. Ask for the target only
when it is missing or ambiguous. Never use an `auto` edge, switch hosts, downgrade,
or change a VPN/proxy route to get around a failed preflight.

Choose the target computer's OS, which may differ from the browser's OS:

- macOS: `/downloads/deskbot-worker-macos.zip`.
- Windows: `/downloads/deskbot-worker-windows.zip`.

These packages share the worker, supervisor, and skill sources. Extract the ZIP
and run from its `deskbot-worker` directory. Do not download third-party copies
or recreate a custom installer. Other operating systems do not yet have this
packaged enrollment flow; do not claim otherwise.

## Reuse the owner's choices

Carry forward approved choices from the conversation or existing installation:
exact repository workspace, computer alias, adapters/bot aliases, and startup
at login. Ask only for missing choices. Do not broaden the workspace or change
an adapter's model or login. An IDE alone is not an authenticated CLI.

The workspace must be the exact root of the owner's existing Git repository,
not the extracted package or an empty example folder. Example paths and aliases
below are placeholders. No developer-specific folder is required.
`https://your-verified-account.example` is a non-working example; replace it with
the owner-selected signed-in account origin and its verified advertised edge
mode. Prefer the account's generated command over copying an example unchanged.

The installer proposes each detected supported adapter as an independent bot.
An explicit adapter selection is appropriate when the user asks to connect only
one local agent. Never enroll newly discovered adapters silently. Startup needs
an explicit yes or no; a prior explicit choice remains valid, and silence is
not approval.

## macOS

Requirements: Python 3.11+, Git, an exact local repository checkout, and a
supported local CLI. Intel and Apple Silicon use the same Python-based package;
the chosen CLI and Python build must support the installed macOS version.
Do not assume Homebrew or PowerShell is installed. The launcher finds an eligible
Python and explains the missing prerequisite if none is available.

Use an owner-approved local execution surface; do not open a new terminal window
without permission. Replace the non-secret example values with their
approved choices and the verified deployment:

```sh
bash ./scripts/install-deskbot-fleet.command --alias 'My Mac' --workspace '/path/to/your-project' --driver auto --edge-mode cloudflare --base-url 'https://your-verified-account.example'
```

Use `--no-startup` when declined, or omit both startup flags to let the local
installer ask. `--driver codex` connects only Codex. `--approve-adapters` is only
for adapters already explicitly approved by the owner. `--check` validates the
workspace, detected drivers, TLS and connector discovery without installing,
requesting a pairing code, or starting a service. Run without sudo.

The installer stores protected files under `~/.deskbot`, uses a current-user
launchd supervisor, and preserves configured bot aliases, models, workspaces,
profiles, disabled workers, and runtime identities on reinstall. A different
origin/edge requires a separate `--install-root`, preserving the previous mode's
credentials. Read the package README for local management and removal.

## Windows

Requirements: Windows 10+, Python 3.11+ available as `python`, Git, the selected
repository checkout, and authenticated supported CLIs.

```powershell
powershell -ExecutionPolicy Bypass -File .\scripts\install-deskbot-fleet.ps1 -Alias 'My PC' -Workspace 'C:\path\to\your-project' -Driver auto -EdgeMode cloudflare -BaseUrl 'https://your-verified-account.example'
```

Use `-NoStartup` when declined, or omit both flags to let the installer ask.
Add `-ApproveStartup` or `--approve-startup` only after an explicit owner approval;
the example commands deliberately do not pre-approve startup.
On a rerun, a saved explicit startup choice is reused. `-Check` validates Python,
Git, the exact repository root, selected adapter probes, and connector discovery
without writing files, asking for codes, changing startup, or starting services.
For a private `sites` deployment it uses the existing protected authorization;
if that is unavailable, perform the normal local protected setup first.
The Windows installer supports additional local/private-remote/cloud placement
and profile options documented in the package README.
Saved account origin/edge bindings, including disabled bots, are checked before
any saved private authorization is sent. Use a separate `-InstallRoot` for a
different account or edge. An unreadable saved config must be repaired locally,
not overwritten with defaults. `-Check` cannot refresh private authorization.

## Private pairing and verification

Keep repository, GitHub, model, runtime, and private-site credentials local.
Do not install a GitHub App as part of enrollment; repository authorization is a
separate owner action. In `sites` mode, the local installer prompts for its
separate gateway bearer; `cloudflare` mode must not inherit or send that bearer.

The installer checks the exact connector protocol, mode, origin, and minimum
release before stopping a supervisor, replacing runtime files, or asking for a
pairing code. If that check fails, report its bounded diagnostic and stop.

When the installer is ready, the owner creates a code in **Add bot** and
enters it directly into the local hidden prompt. Explain that input is invisible:
paste once and press Return. Never ask for, capture, or relay a pairing code or
private authorization through chat, command arguments, logs, or an unprotected
file. Each new bot consumes one unused code.

An open browser does not guarantee the agent can automate it. If browser control
is unavailable, guide the owner to run the packaged installer and enter the code
in an approved local session. Respect a request not to open new console windows;
ask the owner to handle protected input when no suitable session is available.
Do not keep retrying unsupported automation,
copy browser profiles, or extract browser login cookies as an enrollment method.

Stop if an adapter probe or connection doctor fails. Success requires valid
configuration/workspace, runtime identity, driver, the configured HTTP/proxy path,
connector compatibility, an accepted heartbeat without quarantine, and fresh
online status from the running supervisor. Downloaded, paired, and installed are
intermediate states, not proof that the bot is online. A paused fleet can block
readiness; do not enable availability switches without the owner's request.
Direct DNS/TLS probe warnings are not failures when the configured HTTP path and
authenticated heartbeat succeed; report them without bypassing TLS or changing routes.

Report the computer alias, bot aliases/adapters, startup choice, diagnostic
outcomes, and safe fleet-status path. The account should show the bot under
**Owned bots** after accepted heartbeats. Check **Connected** separately from
**Available**: admission, pause, or workload can make an online bot unavailable.
Pausing a fleet/computer/bot blocks
new work immediately; enabling waits for the next acknowledged heartbeat.
The supervisor rescans adapters each minute but requires approval to enroll more.

Close the enrollment dialog and, if the owner wants a functional check, guide
them to a small verification Call with the newly enrolled available bot. This is
that bot's acceptance check, not a requirement to reset an experienced account
or repeat a completed check. Keep budgets bounded and require separate approval for edits,
publication, or other authority changes. Verify a completed result in the record
before claiming model inference works. If no Call was run, say so explicitly.
Do not create a Call merely to make an onboarding status look successful.

## Resume and retire

Rerun the same installer after partial enrollment: it reuses saved identities
and asks for codes only for unpaired bots. For a proven invalid identity, use
`--repair-invalid-credentials` on macOS or `-RepairInvalidCredentials` on Windows;
these never overwrite a valid identity. Do not replace temporarily unreadable
credentials. Preserve old edge credentials during any migration rollback window.

Use the installed worker's local `rename` and `profile` commands for later
identity changes; the Hub displays these fields but does not edit them. Keep
provider/model changes in the local coding tool. To retire bots, revoke them in
Deskfleet, stop their supervisor, remove the approved startup entry, and remove
protected credentials only when the owner explicitly asks to do so.