fleet

# Fleet Skill

This skill defines how to interact with fleet infrastructure: registering and onboarding members, managing permissions, dispatching work, monitoring tasks, and handling provider-specific differences.

## Core Fleet Tools

| Tool | Purpose |
|------|---------|
| `register_member` | Add a new member to the fleet |
| `list_members` | List all fleet members and their status |
| `member_detail` | Get detailed info on a member (provider, OS, icon, etc.) |
| `update_member` | Update member metadata (icon, name, etc.) |
| `remove_member` | Remove a member from the fleet |
| `fleet_status` | Check member idle/busy state before dispatch |
| `execute_command` | Run shell commands on a member |
| `execute_prompt` | Dispatch a prompt to a member's LLM agent |
| `send_files` | Push files from local to a member's work folder |
| `receive_files` | Pull files from a member's work folder |
| `monitor_task` | Check status of a long-running background task on any member. The `auto_stop` parameter and GPU utilization polling are cloud-only features. |
| `compose_permissions` | Generate and deliver provider-native permission config |
| `provision_llm_auth` | Provision LLM authentication for a **remote** member.  |
| `provision_vcs_auth` | Provision VCS credentials (GitHub, Bitbucket, Azure DevOps) |
| `revoke_vcs_auth` | Revoke VCS credentials |
| `setup_ssh_key` | Migrate remote member from password to key-based auth |
| `setup_git_app` | Configure GitHub App for token minting |
| `update_llm_cli` | Update the LLM CLI on a member |
| `cloud_control` | Manage cloud infrastructure for members |
| `shutdown_server` | Shut down a remote member's server |
| `credential_store_set` | Store a secret credential for use in commands (entered OOB  -  never in chat) |
| `credential_store_list` | List stored credential names (values are never returned) |
| `credential_store_delete` | Delete a stored credential by name |
| `credential_store_update` | Update credential metadata (members, TTL, network policy) without re-entering the secret |
| `stop_prompt` | Kill the active LLM process on a member. **Always call `TaskStop` after calling `stop_prompt`**.<br><br>**Use when:** a member is hung, working on the wrong thing, or needs to be cancelled. |

See sub-documents for detailed usage:
- `onboarding.md`  -  full 8-step member onboarding sequence
- `permissions.md`  -  permission composition and denial handling
- `profiles/`  -  stack permission profiles (base-dev, base-reviewer, node, python, go, etc.)  -  add new profiles here to support additional stacks or roles
- `troubleshooting.md`  -  fleet tool troubleshooting by symptom
- `skill-matrix.md`  -  skill installation matrix by project + VCS + role
- `auth-github.md`, `auth-bitbucket.md`, `auth-azdevops.md`  -  VCS auth provisioning per provider
- `beads.md`  -  Beads persistent task DB: commands, backlog ops, session recovery patterns

## Beads  -  Persistent Task Tracking

Beads (`bd` CLI) is installed automatically by `apra-fleet install`. It gives fleet users a persistent, dependency-aware task database that survives across sessions, branches, and members.

**Run `bd` via `Bash` on the orchestrator  -  never via `execute_command` on a member.**

See `beads.md` for the full command reference and workflow examples.

## Secure Credentials

The `{{secure.NAME}}` pattern lets you reference stored secrets in any command without ever exposing plaintext to the LLM or logs.

**How it works:**
1. Store a secret with `credential_store_set`  -  Fleet opens an OOB terminal prompt, so the value never appears in chat
2. Reference it as `{{secure.NAME}}` anywhere in a command string passed to `execute_command`, `register_member`, `update_member`, `provision_vcs_auth`, or `provision_auth`
3. Fleet resolves the token server-side before execution; LLM does not see the secret.

**When to use:**
- Any API key, token, or password that a member needs in a shell command
- Rotating credentials: `credential_store_delete` then `credential_store_set`  -  no re-provisioning required
- Pre-loading secrets before a dispatch so members can authenticate in commands autonomously

NOTE: **`{{secure.NAME}}` only resolves in specific credential fields** (listed above). Using it in any other parameter (e.g. a prompt, a path field in a non-credential tool, or any other unsupported parameter) will pass the token string through literally  -  the secret will NOT be injected, and the raw handle name will be visible in logs. Only use `{{secure.NAME}}` in the fields documented above.

**Access control (scoping):** Credentials can be scoped to specific members.
- `members="*"` (default)  -  all members can access the credential
- `members="alice,bob"`  -  only those members can access it
- Scoping is enforced at resolve time  -  a member outside the allowed set receives an access-denied error
- **Updating scope or metadata:** Use `credential_store_update` to change `members`, `ttl_seconds`, or `network_policy` without re-entering the secret. Use `credential_store_set` again only if you need to change the secret value (triggers OOB re-entry).

**TTL (time-to-live):** Set `ttl_seconds` to auto-expire a credential. Expired credentials
are rejected at resolve time with a clear error (not silently empty).

Example: `credential_store_set  name=ci_token  ttl_seconds=3600`

**Network egress policy:** Attach a network policy to a credential to control outbound
network access for commands that use it:

| Policy | Behaviour |
|--------|-----------|
| `'allow'` (default) | No restriction |
| `'deny'` | Commands invoking network tools (curl, wget, ssh, git push, etc.) are blocked |
| `'confirm'` | OOB prompt before the network call is allowed |

## Member Identification

All tools accept `member_id` (UUID) or `member_name` (friendly name) to identify a member. `member_id` takes precedence when both are provided.

## Tool Boundaries

- **Local members:** ALWAYS use fleet tools (`execute_command`, `execute_promp