Manage Rundesk
Use Rundesk's commands to answer questions about this install. Do not guess at its state or paths.
Use the right install
Run "$RUNDESK_COMMAND", never bare rundesk. It is the absolute command for the install running
this turn. $RUNDESK_HOME already points to that install; do not change it or introduce another
location.
"$RUNDESK_COMMAND" status
"$RUNDESK_COMMAND" --help
Treat generated help as authoritative. If a verb is absent, Rundesk cannot perform it. A command
exits 0 when it answered or completed, 1 when understood but not completed, and 2 for invalid
command syntax. Never report success from wording alone; read the exit code and result.
Common entry points
| Priority |
Need |
Command |
| 1 |
Prove which install this is and whether it is healthy |
"$RUNDESK_COMMAND" status |
| 2 |
See the agents and their providers |
"$RUNDESK_COMMAND" agents |
| 3 |
See whether gateways are running |
"$RUNDESK_COMMAND" gateways |
| 4 |
Explain gateway trouble |
"$RUNDESK_COMMAND" gateways logs <agent> |
| 5 |
Check provider, channel, and skill readiness |
"$RUNDESK_COMMAND" providers check <provider> · "$RUNDESK_COMMAND" channels doctor <agent> · "$RUNDESK_COMMAND" skills doctor <agent> |
| 6 |
Protect approved risky work |
"$RUNDESK_COMMAND" backups save |
Choose the narrowest command that answers the request. Before a mutation, inspect only enough state
to identify the exact target and consequence. Most groups list when called with no subcommand.
Safety boundaries
- Never open or edit Rundesk databases, conversation records, or lock files directly. If a command
fails, use documented read-only surfaces or report it; do not bypass the command with file tools.
- Never stop your own gateway. Restarting it is allowed: Rundesk queues the restart until the active
turn finishes, then brings the gateway back online.
- Require an explicit request for agent removal, schedule removal, backup restore, uninstall, purge,
or forced gateway shutdown. Name the exact target.
- Run a guarded command without
--confirm first when it offers a preview. Add --confirm only
after the preview matches the request.
- Save a backup before an approved destructive change. A backup contains the sealed credential store
and its key, so protect its location as credential-bearing data.
- Never ask for a credential in chat or pass one as an argument. Tell the owner to run
"$RUNDESK_COMMAND" env set <NAME> in their own terminal.
- Prefer diagnosis before restart: inspect status, listings, logs, and the relevant
doctor or
check command.
Read only the reference you need
| Area |
Read for |
| Agents |
Add, describe, reassign, or remove agents |
| Agent instructions |
Design or change persistent agent behavior |
| Gateways |
Start, stop, restart, run, inspect, or recover gateways |
| Conversations |
Ask agents; inspect messages, turns, usage, and failures; search the platforms an agent is connected to |
| Backups |
Save, locate, move, or restore copies |
| Schedules |
Create timed work and proactive verification check-ins |
| Channels |
Connect adapters, access lists, notifications, and diagnosis |
| Providers |
Discover, check, or inspect provider execution |
| Skills |
Catalogs, grants, profiles, values, and skill diagnosis |
| Maintenance |
Focused upkeep of this agent's memory, indexes, and home workspace |
| Retrospective |
Write the bounded usage-cycle diary from evidence and compare prior improvements |
| Self-improvement |
Review proven friction, continuity, capability gaps, and skills |
| Configuration |
Status, version, install settings, and secret values |
| Permissions |
What macOS lets this install do, and whose grants an answer is about |
| Teams |
Install and reconcile version-controlled agent teams |
| OAuth login |
Configure an installed provider; connect, select, extend, or recover accounts |
| Lifecycle |
Install, update, uninstall, and purge |
Use "$RUNDESK_COMMAND" <group> --help when exact help and a reference disagree. Report the command's
answer, including uncertainty or refusal, without translating it into a success it did not earn.
1---2name: managing-rundesk3description: Use when managing this agent, any other agent in its Rundesk install, or the install itself. It supplies verified operational workflows and safety rules for agent instructions, gateways, conversations, channels, schedules, providers, skills, backups, configuration, credentials, and the Rundesk lifecycle. Do not use for ordinary project work or for deciding, performing, or reviewing delegation.4---56# Manage Rundesk78Use Rundesk's commands to answer questions about this install. Do not guess at its state or paths.910## Use the right install1112Run `"$RUNDESK_COMMAND"`, never bare `rundesk`. It is the absolute command for the install running13this turn. `$RUNDESK_HOME` already points to that install; do not change it or introduce another14location.1516```sh17"$RUNDESK_COMMAND" status18"$RUNDESK_COMMAND" --help19```2021Treat generated help as authoritative. If a verb is absent, Rundesk cannot perform it. A command22exits `0` when it answered or completed, `1` when understood but not completed, and `2` for invalid23command syntax. Never report success from wording alone; read the exit code and result.2425## Common entry points2627| Priority | Need | Command |28|---|---|---|29| 1 | Prove which install this is and whether it is healthy | `"$RUNDESK_COMMAND" status` |30| 2 | See the agents and their providers | `"$RUNDESK_COMMAND" agents` |31| 3 | See whether gateways are running | `"$RUNDESK_COMMAND" gateways` |32| 4 | Explain gateway trouble | `"$RUNDESK_COMMAND" gateways logs <agent>` |33| 5 | Check provider, channel, and skill readiness | `"$RUNDESK_COMMAND" providers check <provider>` · `"$RUNDESK_COMMAND" channels doctor <agent>` · `"$RUNDESK_COMMAND" skills doctor <agent>` |34| 6 | Protect approved risky work | `"$RUNDESK_COMMAND" backups save` |3536Choose the narrowest command that answers the request. Before a mutation, inspect only enough state37to identify the exact target and consequence. Most groups list when called with no subcommand.3839## Safety boundaries4041- Never open or edit Rundesk databases, conversation records, or lock files directly. If a command42 fails, use documented read-only surfaces or report it; do not bypass the command with file tools.43- Never stop your own gateway. Restarting it is allowed: Rundesk queues the restart until the active44 turn finishes, then brings the gateway back online.45- Require an explicit request for agent removal, schedule removal, backup restore, uninstall, purge,46 or forced gateway shutdown. Name the exact target.47- Run a guarded command without `--confirm` first when it offers a preview. Add `--confirm` only48 after the preview matches the request.49- Save a backup before an approved destructive change. A backup contains the sealed credential store50 and its key, so protect its location as credential-bearing data.51- Never ask for a credential in chat or pass one as an argument. Tell the owner to run52 `"$RUNDESK_COMMAND" env set <NAME>` in their own terminal.53- Prefer diagnosis before restart: inspect status, listings, logs, and the relevant `doctor` or54 `check` command.5556## Read only the reference you need5758| Area | Read for |59|---|---|60| [Agents](references/agents.md) | Add, describe, reassign, or remove agents |61| [Agent instructions](references/agent-instructions.md) | Design or change persistent agent behavior |62| [Gateways](references/gateways.md) | Start, stop, restart, run, inspect, or recover gateways |63| [Conversations](references/conversations.md) | Ask agents; inspect messages, turns, usage, and failures; search the platforms an agent is connected to |64| [Backups](references/backups.md) | Save, locate, move, or restore copies |65| [Schedules](references/schedules.md) | Create timed work and proactive verification check-ins |66| [Channels](references/channels.md) | Connect adapters, access lists, notifications, and diagnosis |67| [Providers](references/providers.md) | Discover, check, or inspect provider execution |68| [Skills](references/skills.md) | Catalogs, grants, profiles, values, and skill diagnosis |69| [Maintenance](references/maintenance.md) | Focused upkeep of this agent's memory, indexes, and home workspace |70| [Retrospective](references/retrospective.md) | Write the bounded usage-cycle diary from evidence and compare prior improvements |71| [Self-improvement](references/self-improvement.md) | Review proven friction, continuity, capability gaps, and skills |72| [Configuration](references/configuration.md) | Status, version, install settings, and secret values |73| [Permissions](references/permissions.md) | What macOS lets this install do, and whose grants an answer is about |74| [Teams](references/teams.md) | Install and reconcile version-controlled agent teams |75| [OAuth login](references/oauth-login.md) | Configure an installed provider; connect, select, extend, or recover accounts |76| [Lifecycle](references/lifecycle.md) | Install, update, uninstall, and purge |7778Use `"$RUNDESK_COMMAND" <group> --help` when exact help and a reference disagree. Report the command's79answer, including uncertainty or refusal, without translating it into a success it did not earn.
rundesk-ai