First request and daily operation

Use one of the complete routes in Installation. Start with a request whose result you can check, such as “Read README.md and summarize what this project does. Do not change files.” Check the tool results and answer in the client. A successful launch alone says nothing about model authentication or useful work.

Inventory, status, and health

cowboy list
cowboy status
cowboy doctor

These answer different questions. The list shows registered agents that can run. Status shows runtime instances and their last reported activity. Doctor checks whether services are up, the event loop responds, and inbox consumers are still reading. A local session need not have a registry entry, and doctor cannot verify every deployment from every account. An unknown result is not a pass. Use Troubleshooting to interpret it.

For a named managed agent:

cowboy status dev
cowboy doctor dev --json
journalctl -u cowboy-serve-dev --since today

cowboy logs reads the launch log of a backgrounded local serve process; it is not a general transcript or journal reader. For example, cowboy logs agent reads the unnamed headless instance’s log when it was started with --daemon. Use the system journal for managed units, Docker logs for containers, and the client/session history for conversation content.

Review external actions

Approvals are configured per bridge or effect. For a gated Git push, review the runner’s target, execution identity, commit SHA, changed files, and diffstat. The agent’s prose is not the runner’s description. An authorized approver chooses ✅ to push exactly that SHA or ❌ to reject it. An expired request needs a new review; a branch that moved requires a newly prepared request.

The operation result returns to the agent’s inbox and the configured status channel. Keep the request ID and SHA if delivery or execution is uncertain. An accepted message or approval is not proof that the push or rebuild finished. See approvals and gated effects.

Restart and recover

Managed daemons restart after exit, including clean socket quits, with a five-second delay and a start-rate limit. A changed per-agent component also triggers a restart on NixOS activation. Use systemd for an explicit restart:

sudo systemctl restart cowboy-serve-dev
cowboy doctor dev

A deliberate systemd stop leaves the daemon down. Ordinary containers in the installation example have no Docker restart policy; start them explicitly. For local headless and cage launches, retain the original launch command: cowboy restart cannot reconstruct their transient socket, sandbox, and exposure flags. It stops those instances and asks you to relaunch. For a settings-based Docker agent it can reuse the declared volume.

After a crash, a sender may receive no answer even though a request was accepted, or see a duplicate after redelivery. Resumed work can also lose the original reply destination; inspect state and external outcomes before resubmitting. Message reliability gives the exact recovery contract.

Back up mutable state

Stop the agent and its writers before copying state. Keep ownership and modes, especially for keys. A Nix closure rebuilds software; it does not restore conversations, working files, credentials, or pending approvals.

• Local: preserve the workspace and Cowboy’s XDG data/config directories (normally under ~/.local/share and ~/.config).
• Managed: preserve the configured agent home and writable mounts, plus the enabled broker/bridge services’ persistent state and secret sources. Include Redis persistence when recovering queued messages and approvals matters.
• Docker walkthrough: preserve both named volumes, including the explicit data directory under the configuration volume. Container removal does not remove these named volumes.
• Settings-based Docker CLI: config and workspace are under ~/.local/share/cowboy/agents/<name>/ by default. The current supervisor leaves Montana’s default data directory in the container layer. Preserve it separately before replacing the container, or configure a data directory in a mounted volume in the generated supervisor. The config/workspace mounts alone are not a complete session backup.
• OCI: preserve the writable mounts you declared in the bundle; do not treat runtime scratch or the CLI companion’s Redis as a durable backup.

Upgrade and rebuild

Keep the old revision, lock file, and a state backup until the new deployment has answered a test request. Build the new CLI or image from the chosen source revision. On NixOS, update the host’s Cowboy input and rebuild the host, then check doctor and the first real request.

For the Docker walkthrough, stop and remove the old container after backing up, load the new image, and repeat the run command with the same named volumes. A settings-based container also has a generated flake and result link under its configuration volume. Edit that persistent configuration and run cowboy bake inside the container to build a generation; restarting with an existing result link does not itself rebuild it. A new base image alone does not replace that existing generation.

An approval-gated rebuild pins the main commit and resolved input overrides before asking for approval. The result reports when a successful build produced the same system or home generation. Treat that as no deployment change, not evidence that the requested behavior reached the running agent. See rebuild diagnostics.

Stop and remove

Stop local or CLI-managed agents with cowboy stop <name>. For a managed daemon, stop its systemd unit, disable the agent in the NixOS configuration, and rebuild. For the Docker walkthrough, stop and remove the named container. Keep backups, then deliberately remove only the state and volumes you no longer need. Removing software or disabling a service is separate from erasing its history and keys. Revoke provider or publishing credentials when retiring the deployment.

Continue with Configuration to change models, tools, message access, and service settings.