Pithos documentation
Live output of s3d and Pithos's own notes (why it started or did not start s3d, flushes, errors).
Addresses, updates and the lock
- In Theseus, the full page lives at
pithos.sia/<user>/<drive>/<folder>(andpithos.sia/settings,pithos.sia/account…). The barepithos.siais this website. - The footer shows the version. ↻ checks for updates; a newer version shows as "↑ vX". Click it to install; recent Theseus versions apply it without a restart, older ones offer a restart.
- When the vault locks, Pithos locks too; Unlock asks for your PIN.
Drives on Silent Mode
+By default s3d runs on your computer. Settings › Where your drives live can move it to Silent Mode's server (s3.silentmode.st) instead. It keeps working with your computer off, other devices can reach it, and the Pithos screens stay the same.
- Still your own Sia account. Only s3d's data folder (its database and the files still waiting) moves; nothing already on Sia is uploaded again, and the recovery phrase never leaves your computer. Moving back works the same way.
- Encrypted before it leaves. Pithos encrypts file names and contents on your computer, with keys from your Theseus vault (or a key file beside
s3d.ymlthat you should back up). - Sharing a plain s3d cannot do. Public folders, expiring share links, and S3 keys for other people limited to one folder with read, add-only or edit rights. Shared files are stored readable, because the people they are for have no key; stop sharing and Pithos encrypts them again.
- Signing up needs a signature from the wallet that owns a BNS name: one hosted account per name.
Public folders anyone can open. Make a folder public (⋯ › Share… on a drive on Silent Mode) and it gets an address like https://navigate.st/s3/<your-bns-name>/<drive>/<folder>/: a page with its files, small pictures and a player, which works in any browser. A single file is at the same address plus its name. Tools can add ?json to a folder address for a JSON listing.
Other ways to run Pithos
Web console
npm install
@@ -175,7 +179,7 @@ rclone copy ./photos s3d:my-drive/photos --progress
Troubleshooting
| What you see | What it means / what to do |
|---|---|
| "N files waiting to upload", or "0 B on Sia" | Files are still in the local buffer. Click Upload now (or s3d flush); automatic upload does it after 10 quiet minutes. |
| s3d "stopped" or "crashed" | Overview › Start; read Logs for the reason. "Not registered" means s3d login has not been done for this config. |
A link with 127.0.0.1 does not open elsewhere | Expected: it points to the computer running s3d. |
SignatureDoesNotMatch in an S3 app | Wrong secret, or the app uses virtual-host style; switch to path-style and region us-east-1. |
| "address already in use" | Another program (or another s3d) uses port 8000/8001; change apiAddress/adminAddress or stop the other one. |
| Pithos shows "external" | Another s3d is already running for this config; Pithos reads its stats but leaves it alone. |
| Pithos is locked | Your Theseus vault is locked; Unlock asks for the PIN. |
| A different account than expected | The account is the indexer login plus the phrase. Accounts › Which Sia account this is shows the account key; compare it on sia.storage under My apps › S3d. |
Limits
-- Public access is per drive, read-only for others; s3d has no folder-level rules or write rights for other people.
- Single uploads are capped at 5 GiB (multipart uploads from S3 tools work for larger files).
- Share links and public files reach other people only when s3d has a public address.
- Running s3d on Silent Mode's server ("On Silent Mode", with encryption in the browser and folder-level sharing) is built into Pithos but the service is not open yet.
- Public access is per drive, read-only for others; s3d has no folder-level rules or write rights for other people.
- Single uploads are capped at 5 GiB (multipart uploads from S3 tools work for larger files).
- Share links and public files reach other people only when s3d has a public address.
- Folder-level sharing and rights for other people need drives on Silent Mode (see that section); a plain s3d cannot do them.
For AI assistants
You are helping someone run s3d (the Sia S3 gateway), optionally through Pithos. Facts to rely on:
- s3d v0.2.0+, S3 API on
127.0.0.1:8000, admin API on127.0.0.1:8001(Basic auth, empty user,adminPassword), regionus-east-1, path-style addressing. - Setup order:
s3d config→s3d login(indexer URL + 12-word phrase, approve the "S3d" app at the indexer) → runs3d→s3d users create→s3d keys create→ use any S3 client. - Small files wait locally until a ~40 MB block fills;
s3d flushorPOST /objects/flushuploads them now. - Buckets ("drives") can be private, public read, or public read + list; nothing finer.
- Config lookup:
S3D_CONFIG_FILE, else the OS default path listed above.