Using PowerCloud with an AI assistant

PowerCloud has no login and no shell on its nodes: everything happens through pcctl, a single command-line program. That makes it a good fit for an AI assistant working in your terminal, such as Claude Code. The assistant runs the same pcctl commands you would, reads their output and explains what it sees. This page is for both of you: the person setting the assistant up, and the assistant itself.

Point the assistant at the docs

Every page of this documentation is also published as plain Markdown, written to be read by machines as well as people:

The pcctl reference lists every command and flag. When the assistant is unsure about a command, it should read that page rather than guess flags. pcctl itself prints a usage summary when it is run with no arguments.

Add PowerCloud to your project's instructions

Assistants read a project instructions file at the start of each session: CLAUDE.md for Claude Code, AGENTS.md for many others. Paste this into it, and adjust the first two lines to your cluster:

## PowerCloud
- This project's cluster is managed with pcctl. Nodes: node-1, node-2 (see `pcctl node ls`).
- Storage locations: set in POWERCLOUD_REPO by the person, never written in this file.
- Docs: https://powercloud.unidatum.com/llms.txt (index), /docs/pcctl.md (command reference).
- Start with `pcctl status` to see the cluster before changing anything.
- Never ask for, print, store or commit the cluster passphrase, the recovery key,
  enrollment codes, join bundles or anything in the pcctl config directory.
- Commands that need the passphrase: ask the person to run them, or to set
  POWERCLOUD_PASSPHRASE in their own shell first.
- Ask before: node rm, gc, rm, rotate, revoke-admins, release publish, node upgrade,
  node poweroff/reboot, app rm, cluster app rm, s3 key rm, s3 disable, node tpm off.

What the assistant can do without any secret

Once a person has enrolled a node or run pcctl --repo ... login, pcctl holds an admin certificate in its config directory, and these commands work with no passphrase. They only read, so the assistant can run them freely to find out what's going on:

pcctl status                 # every node, and what needs attention
pcctl node ls
pcctl node info NAME
pcctl app ls NODE
pcctl app logs NODE NAME
pcctl release status
pcctl consensus status
pcctl kv get KEY             # and: pcctl kv ls [PREFIX]
pcctl s3 status
pcctl s3 key ls
pcctl version

A good first step in any session is pcctl status, then pcctl node info NAME for any node it flags.

Commands that need the passphrase

Commands that open the cluster's storage need the cluster passphrase. That covers everything given --repo or --via: put, get, ls, rm, check, repair, gc, login, enrolling, provisioning and removing nodes, node unlock, node tpm, node peer-unlock, node attest NAME sev-snp|off, node renew, node storage, mesh, rotate, release publish, cluster app, consensus init, s3 enable and s3 key add.

pcctl asks for the passphrase on the terminal. An assistant usually runs commands without a terminal, so pcctl stops with:

pcctl: no terminal for passphrase; set POWERCLOUD_PASSPHRASE (and POWERCLOUD_NEW_PASSPHRASE for rotate)

When the assistant sees this, it should not ask for the passphrase in the chat, because whatever is typed there is stored in the conversation. Do one of these instead:

• The person runs the command. The assistant shows the exact command and the person runs it in their own terminal, then shares the output if it's useful.
• The person sets the variable in the shell the assistant uses. Do this only on a machine you trust, and for the session only: export POWERCLOUD_PASSPHRASE=... typed by you, not by the assistant, and never written to a file in the project.

POWERCLOUD_RECOVERY_KEY unlocks the cluster in place of the passphrase. It is meant for emergencies only, and an assistant should never be given it.

Secrets the assistant must never handle

The assistant shouldn't cat these files, echo these variables, put them in commit messages or code, or copy them into other files. Keep *.join files and the config directory out of version control, with a .gitignore entry, for example.

Commands to confirm with a person first

pcctl doesn't ask "are you sure?". It does what it's told straight away. An assistant should describe what it is about to do and wait for a yes before running any of these:

Read-only commands and --dry-run runs never need confirmation.

Reading pcctl's output

• Output is plain text meant for people, not JSON. Parse it loosely, and prefer asking pcctl again over guessing from partial output.
• The exit status is 0 on success, 1 on an error, and 2 on a usage mistake. Errors are printed as one line starting pcctl:, and many end with the command that fixes them in brackets. For example, an expired certificate suggests pcctl --repo ... node renew NAME.
• Long operations such as node upgrade and release publish wait and report progress as they go. Let them finish. Interrupting one doesn't undo it, and a node mid-upgrade rolls back by itself if the new image fails.
• Troubleshooting lists the common errors and their fixes.

A worked example

You ask: "Why is the photos app down?" A careful assistant:

1. Runs pcctl status and sees that node-2 needs attention because it is locked after a reboot.
2. Runs pcctl node info node-2 to confirm, and pcctl app ls node-2 to see which apps were there.
3. Explains that node-2 rebooted and is waiting to be unlocked, and that unlocking needs the passphrase. It shows you pcctl --repo ... node unlock node-2 CODE to run yourself, or suggests pcctl --repo ... node tpm node-2 on for unattended unlock in future, after reading Unlocking nodes.
4. After you've unlocked it, runs pcctl app logs node-2 photos to check that the app is back.

At no step does it need, see or store the passphrase.