Quickstart

This page walks through PowerCloud on a single computer, with no spare hardware, cloud account or VM. Three local directories stand in for three storage providers, so you can see the encrypted store survive one of them disappearing; then you run the node daemon, pcd, as an ordinary program and enroll it as a node. Everything here takes a few minutes, and nothing is installed system-wide.

What you need

• pcctl, the PowerCloud command-line tool, for Linux or macOS (amd64 or arm64). Either take pcctl-VERSION-OS-ARCH from a PowerCloud release (check it against the release's SHA256SUMS, then chmod +x it and rename it pcctl), or build it from the PowerCloud source with a Go toolchain.
• For the second half (running a node locally), a Linux machine and the PowerCloud source, because pcd runs only on Linux and isn't shipped as a separate download.

To build both from a checkout of the source:

go build -o pcctl ./cmd/pcctl
go build -o pcd ./cmd/pcd        # Linux only

Keep this trial separate from any real cluster: pcctl stores admin credentials in its configuration directory, so point it at a scratch one for now.

mkdir -p ~/pc-try && cd ~/pc-try    # put pcctl (and pcd) here
export POWERCLOUD_CONFIG=$PWD/config

1. Create a cluster over three locations

A repository is a comma-separated list of storage locations. Here they are three directories, ./home, ./colo and ./cloud; in real use they would be a disk at home, a server in a colo and a cloud bucket.

./pcctl --repo ./home,./colo,./cloud init

pcctl asks for a new passphrase twice (at least 12 characters), creates the cluster's root key, and writes a key header to every location:

Initialized cluster 66770d7cd1f5522f114c0381e8fe93e1

RECOVERY KEY (write it down and store it offline — it is shown only once):

    LJRF-5NB4-BMPX-PAB2-CZVD-JRKL-XB6L-TF52

Without your passphrase or this recovery key, no one — including you — can read this data.

The long hex string is your cluster ID. The recovery key unlocks the cluster without the passphrase; for a real cluster, write it down and keep it offline, because it is never shown again. For what the passphrase and recovery key protect, see Concepts.

Every later command asks for the passphrase. For a trial you can set it in the environment instead, and you can set the repository once too, so that pcctl ls means pcctl --repo ./home,./colo,./cloud ls:

export POWERCLOUD_PASSPHRASE='your passphrase'   # trial only: it ends up in shell history
export POWERCLOUD_REPO=./home,./colo,./cloud     # optional; this page keeps --repo explicit

2. Store and read a file

put NAME FILE stores a file under a name of your choosing; get NAME [FILE] reads it back (to standard output if no file is given).

printf 'hello, PowerCloud\n' > notes.txt
./pcctl --repo ./home,./colo,./cloud put docs/notes.txt notes.txt
./pcctl --repo ./home,./colo,./cloud ls
./pcctl --repo ./home,./colo,./cloud get docs/notes.txt

stored docs/notes.txt (18 bytes, 1 chunks)
18  2026-10-29 01:16  docs/notes.txt
hello, PowerCloud

Look inside ./home: there are no file names and nothing readable, only blobs with opaque IDs. The file was split into chunks, each encrypted on your machine, and its name lives in an encrypted manifest. All three directories got a copy, because a write must reach a quorum (by default a majority) of the locations.

3. Lose a provider

Delete one location entirely, as if a provider closed your account:

rm -rf ./colo
./pcctl --repo ./home,./colo,./cloud get docs/notes.txt out.txt
cat out.txt

hello, PowerCloud

The read still works: pcctl falls back to the locations that have the data, and checks every chunk it reads against its MAC, so a location that returned altered data would be caught. check shows what each location is missing:

./pcctl --repo ./home,./colo,./cloud check

1 objects, 0 deleted, 1 chunks in use, 0 unreferenced (reclaimed by gc)

LOCATION  BLOBS  MISSING  STALE  CORRUPT  REPAIRED  STATUS
./home    3      0        0      0        0         ok
./colo    0      3        0      0        0         needs repair
./cloud   3      0        0      0        0         ok
pcctl: locations differ; run 'pcctl repair'

The three blobs per location are the key header, the file's manifest and its one chunk.

4. Repair

repair copies every missing or outdated blob back, authenticating each copy before it writes it, so it can't spread corruption:

./pcctl --repo ./home,./colo,./cloud repair

1 objects, 0 deleted, 1 chunks in use, 0 unreferenced (reclaimed by gc)

LOCATION  BLOBS  MISSING  STALE  CORRUPT  REPAIRED  STATUS
./home    3      0        0      0        0         ok
./colo    0      3        0      0        3         repaired
./cloud   3      0        0      0        0         ok

Adding a new provider works the same way: add its location to --repo and run repair. Real locations are usually S3-compatible buckets; see Storage.

5. Run a node locally

On Linux, start pcd with a state directory and a local listen address. In the OS, pcd starts at boot; here it is an ordinary program.

./pcd --state ./node-state --listen 127.0.0.1:7443

It logs a few lines and prints an enrollment code:

level=WARN msg="no state disk (powercloud.state=); node state is kept in RAM and lost at reboot" svc=pcd
level=WARN msg="apps unavailable" svc=pcd err="apps: enabling cgroup controllers in /sys/fs/cgroup: open /sys/fs/cgroup/cgroup.subtree_control: permission denied"

  PowerCloud node 262c2fdc861a9cf2 is waiting to be enrolled.
  On your admin machine run:
    pcctl node enroll <this-node-address> <code> <name>
  enrollment code: EYWC-7XEG-DKOP-F2IR-23UA-GTJQ-5G3M-ZXTO

level=INFO msg="API listening" svc=pcd addr=127.0.0.1:7443

The warnings are expected when pcd runs as an ordinary user outside PowerCloud OS: there is no encrypted state disk, and no permission to run apps. 262c2fdc861a9cf2 is the node ID, a hash of the key pcd just generated.

6. Enroll it

In a second terminal, in the same directory and with the same POWERCLOUD_CONFIG (and POWERCLOUD_PASSPHRASE, if you set it), enroll the node under a name of your choosing. Use your own code:

./pcctl --repo ./home,./colo,./cloud node enroll 127.0.0.1 EYWC-7XEG-DKOP-F2IR-23UA-GTJQ-5G3M-ZXTO my-node

enrolled node my-node (262c2fdc861a9cf2) at 127.0.0.1:7443
mesh membership: 1 node (serial 1)
  NODE     MEMBERSHIP
  my-node  serial 1

pcctl checked that the key it reached matches the fingerprint in the code (so nothing in between could pose as the node), issued the node a certificate from the cluster CA, recorded it in the cluster's registry, wrote you an admin certificate, and published a membership list. From now on the node accepts only clients with a certificate from this cluster. The port defaults to 7443 when you give only a host.

7. Look at the node

Day-to-day commands need only the admin certificate, not the passphrase or the repository:

./pcctl node ls
./pcctl node info my-node

NAME     ID                ADDRESS
my-node  262c2fdc861a9cf2  127.0.0.1:7443
name         my-node
id           262c2fdc861a9cf2
cluster      66770d7cd1f5522f114c0381e8fe93e1
arch         amd64
kernel       ...
boot         UEFI, Secure Boot off
lockdown     none
state        RAM (lost at reboot)
version      dev
uptime       1530h17m52s
certificate  expires 2027-10-29 01:14 UTC
cluster CA   8471c8d7afafd600
membership   list serial 1
mesh      not configured yet

Running locally, the node reports your computer's kernel, uptime and lockdown setting. A real node shows lockdown confidentiality, its encrypted volume under state, and its mesh address and peers. The mesh isn't configured here because creating a WireGuard interface needs privileges pcd doesn't have as an ordinary user.

pcctl status shows every node on one line, then anything that needs attention:

./pcctl status

NODE     STATE  ARCH   VERSION  UPTIME       CPU       MEMORY            MESH       APPS  STORAGE  CERT
my-node  ok     amd64  dev      1530h17m52s  0% of 32  52864/192933 MiB  0/0 peers  0/0   -        364d

needs attention:
  my-node: state is in RAM, lost at reboot

The warning is the one you'd want on a real node: without an encrypted state disk, its identity would be lost at reboot.

8. Clean up

./pcctl node poweroff my-node     # or Ctrl-C in pcd's terminal
./pcctl --repo ./home,./colo,./cloud node rm my-node

node poweroff on a node outside PowerCloud OS just makes pcd exit. node rm revokes the node's certificate and removes it from the registry and from this machine's list of nodes. Then delete the trial directory (~/pc-try), which holds the three locations, the node's state and the trial's admin credentials.

Next steps

• Install a node: run a real node on a physical machine, a VM or a cloud.
• Enroll a node: enroll nodes from the console or join them unattended.
• Storage: use S3-compatible buckets and your nodes' disks as locations.
• Concepts: the concepts and a glossary.