Pithos documentation

Pithos is a control panel for s3d, the Sia Foundation's S3 gateway. With it you connect s3d to a Sia storage account, create S3 users and access keys, keep files in drives, play and share them, and watch uploads reach the Sia network. Everything Pithos does can also be done by hand with the s3d command line; this page explains both, so you can set it up yourself or hand the page to an AI assistant and let it guide you.

This page is also published as plain Markdown at pithos.sia/docs/pithos-docs.md for AI assistants.

#How the pieces fit

Data flow: your app or Pithos → s3d on your computer → (encrypted, erasure-coded) → Sia hosts, tracked by your indexer account.

Two things to know early:

1. s3d waits before uploading small files. It packs uploads into blocks of about 40 MB before sending them to Sia. Until a block is full, files exist only on your computer. Pithos shows a "files waiting to upload" banner and uploads leftovers automatically after 10 quiet minutes (Settings › automatic upload); s3d flush or Upload now sends them immediately.
2. 127.0.0.1 means "this computer". s3d listens on 127.0.0.1:8000 by default, so links that start with it work only on the machine running s3d. Other devices cannot open them.

#Getting started (Pithos in Theseus)

Pithos comes with Theseus, the Silent Mode browser. Open it from the Pithos icon in the left-hand strip.

1. Unlock. Pithos opens only while your Theseus password vault is unlocked (PIN or master password), because it shows access-key secrets.
2. Accounts › Get started. The guide walks through each step:
   1. Sia Storage account: sign up or sign in at sia.storage (the guide opens it for you). Tick "I have created my Sia Storage account and I am signed in", or choose your own indexer.
   2. Install s3d: Pithos downloads the pinned s3d release and checks its SHA-256.
   3. Recovery phrase: choose From my vault (Pithos derives the phrase from your Theseus vault, so there is nothing to write down) or use your own 12-word phrase.
   4. Connect: Pithos runs s3d login and opens the indexer's approval page. Approve the app named S3d there.
   5. Start gateway: s3d starts and keeps running (Pithos restarts it after a crash and when Theseus starts).
   6. Access key: Pithos creates your first S3 user, its drive and an access key. Save the key (Copy, or Save to encrypted file).
3. Drives. Open your drive and drag files in.

Which Sia account you end up with depends on two things together: the indexer login that approved the connection and the recovery phrase. The same phrase approved from two different logins makes two different accounts.

#The Pithos screen

The menu is in setup order. In the narrow sidebar it is the ☰ button at the top right; the ⤢ button next to it opens Pithos as a full page.

#Accounts

• Your Sia accounts at the top: the account in use (with its free space) and any accounts set aside on this computer, each with Switch to, plus Add another account.
• Add another account sets the current account aside (its users, keys and drives are kept on this computer, nothing is deleted), stops s3d and runs the guide for the new account. Files already on Sia stay in the old account; switch back any time.
• Account label: Sia Storage does not tell apps who signed in, so the guide asks for your Sia Storage email at the approval step and names the account after it. Change it here any time.
• Which Sia account this is: the account key, app name, storage used, last use and indexer, read from the indexer.

#Overview

• Gateway: s3d's state (running, stopped, crashed, external), endpoint, version, config and data folders; Start, Restart, Stop.
• Upload pipeline: pending (waiting on this computer), on Sia, awaiting pin, open multipart uploads, failed and orphaned objects; Flush now.
• Free space: used and free storage on your Sia account.

#Users & keys

• Create a user (and its drive, named after it), delete a user.
• Create and revoke access keys. Each key shows ready-made settings for the AWS CLI, rclone and environment variables.
• Save to encrypted file / Open saved credentials: keep keys in a password-protected .pithoskey file (in Theseus it can be sealed with your vault instead).

#Drives

• Views: Icons (with picture previews), List, Details. Each page remembers its view.
• Upload: drag files in or use Upload. Single uploads up to 5 GiB (1 GiB from the sidebar).
• New folder, Rename… (files, folders and whole drives; a rename is an instant server-side copy, nothing is uploaded again), Delete.
• Viewer: pictures, video and text open in place; music plays in the player at the bottom, which keeps playing while you browse and moves on through the folder (volume, seek, media keys).
• Share…: a public link at https://navigate.st/sia/<id>/<name> that anyone can open on any device, even with this computer off, for 1 month, 1 year or 5 years. On a folder, ⋯ › Public link… makes a page with the files in it (not sub-folders). Files still waiting on this computer are uploaded to Sia first. Settings › Public links lists them; Switch off stops a link at once. Under "Link for this computer, or your own server" is the old signed s3d link (1 hour to 7 days), which opens only where s3d is reachable.
• Access…: private, public read, or public read + list, for the whole drive (s3d cannot make a single folder public). Change it any time.
• Free space line under the account name.

#Settings

Edits s3d.yml; s3d reads it at start, so restart to apply. Also: automatic upload of leftovers (on by default, after 10 minutes with no new uploads) and where your drives live.

#Logs

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> (and pithos.sia/settings, pithos.sia/account …). The bare pithos.sia is 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.yml that 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

Copynpm install
node bin/pithos-web.js

It prints a one-time sign-in link for http://127.0.0.1:8700. Options:

Remote access: PITHOS_PASSWORD='long random secret' node bin/pithos-web.js --listen 0.0.0.0:8700 --allow-host pithos.example.org, behind a TLS reverse proxy.

#Desktop app

Windows: installer or portable exe (SHA-256 sums in releases-manifest.json under pithos-desktop). The builds are not code-signed yet, so Windows SmartScreen may ask you to confirm with More info › Run anyway.

Linux (x86-64): AppImage, .deb for Debian and Ubuntu, or tar.gz.

Copychmod +x Pithos-*.AppImage && ./Pithos-*.AppImage     # needs FUSE 2 (libfuse2 / libfuse2t64 on Ubuntu)
sudo apt install ./Pithos-*-amd64.deb                 # then start Pithos from the app menu

On Linux, s3d's own defaults (/etc/s3d/s3d.yml, /var/lib/s3d) are for a system service. When those do not exist and you cannot write there, Pithos keeps s3d in your home folder instead: ~/.config/s3d/s3d.yml and ~/.local/share/s3d. A hand-run s3d finds that config with S3D_CONFIG_FILE=~/.config/s3d/s3d.yml.

macOS builds are not published yet; run it from source:

Copynpm install
npm run desktop

The window signs itself in, installs s3d into its own folder (%APPDATA%\pithos\bin on Windows) and stops s3d when you quit. The version in the footer turns into "↑ vX" when a newer build is out; click it to download that build, then run it to update. Build the installers yourself with npm run dist:win (or dist:linux / dist:mac on those systems).

#Opening Pithos in another browser

Pithos runs on your computer, not on the pithos.sia website. Two ways to reach it from a browser other than Theseus:

• Open in browser (under the navigation, or in the ☰ menu) in Theseus or the desktop app opens the page you are on in your default browser, signed in with a one-time link.
• Open my Pithos on the pithos.sia website, or Open in my Pithos on a pithos.sia app address such as pithos.sia/<user>/<drive>, goes to http://127.0.0.1:47621/open. The Pithos running on this computer (Theseus or the desktop app) then asks you, in its own window, whether to open in that browser. Nothing is signed in unless you say yes, and the website learns nothing either way.

A browser opened this way has the same access as Pithos itself until you quit Pithos (or restart Theseus). It works on the same computer only: port 47621 listens on 127.0.0.1. If both Theseus and the desktop app run, the one that started first answers.

#Which s3d Pithos manages

The same one a hand-run s3d uses: S3D_CONFIG_FILE if set, otherwise %APPDATA%\s3d\s3d.yml (Windows), ~/Library/Application Support/s3d/s3d.yml (macOS), /etc/s3d/s3d.yml (Linux). If another s3d already serves that config, Pithos shows it as external and does not start a second one.

#s3d on the command line

Pithos needs s3d v0.2.0 or newer. Download it from the s3d releases on GitHub (SiaFoundation/s3d), or let Pithos install it.

#Commands

#A full setup by hand

Copys3d config                 # set addresses, admin password, data folder
s3d login                  # indexer URL (https://sia.storage) + 12-word phrase, then approve
s3d                        # start the gateway (leave running, or install as a service)
s3d users create alice     # in another terminal
s3d keys create alice      # note the access key ID and secret
aws configure --profile s3d          # paste the key, region us-east-1
aws --profile s3d --endpoint-url http://127.0.0.1:8000 s3 mb s3://alice-files
aws --profile s3d --endpoint-url http://127.0.0.1:8000 s3 cp photo.jpg s3://alice-files/photos/
s3d flush                  # send it to Sia now instead of waiting for a full block

Keep the recovery phrase offline. It is the only way to reconnect this storage on another machine or after a reinstall; never paste it into a chat or a website you did not open yourself.

#Where things live

Environment variables: S3D_CONFIG_FILE (use this config file), S3D_DATA_DIR (data folder).

#s3d.yml

CopyapiAddress: 127.0.0.1:8000        # S3 API
apiHTTPSAddress: ""               # optional TLS listener (self-signed)
adminAddress: 127.0.0.1:8001      # admin API (must differ from the S3 addresses)
adminPassword: change-me          # required for status/flush
directory: /var/lib/s3d           # data folder
sia:
  diskUsageLimit: 10737418240     # local buffer limit in bytes (default 10 GiB)
  uploadThreads: 4                # parallel uploads to Sia
  dataShards: 10                  # erasure coding: data shards per slab
  parityShards: 20                # recovery shards per slab (10-of-30 by default)
s3:
  hostBases: []                   # host names for virtual-host style buckets
log:
  stdout: { enabled: true, level: info }
  file: { enabled: true, level: info }

#Admin API

HTTP Basic auth with an empty user name and adminPassword:

Copycurl -u :change-me http://127.0.0.1:8001/stats/uploads

#Using drives from other apps

Any S3 app works. Use the endpoint http://127.0.0.1:8000, region us-east-1, path-style addressing, and an access key from Users & keys.

AWS CLI (~/.aws/config):

Copy[profile s3d]
region = us-east-1
endpoint_url = http://127.0.0.1:8000
s3 =
  addressing_style = path

Copyaws --profile s3d s3 ls
aws --profile s3d s3 sync ./music s3://my-drive/music
aws --profile s3d s3 presign s3://my-drive/music/song.mp3 --expires-in 3600

rclone (rclone config, or ~/.config/rclone/rclone.conf):

Copy[s3d]
type = s3
provider = Other
access_key_id = YOUR_ACCESS_KEY_ID
secret_access_key = YOUR_SECRET_KEY
endpoint = http://127.0.0.1:8000
region = us-east-1
force_path_style = true

Copyrclone ls s3d:my-drive
rclone copy ./photos s3d:my-drive/photos --progress

Environment variables for SDKs and tools: AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_DEFAULT_REGION=us-east-1, AWS_ENDPOINT_URL=http://127.0.0.1:8000.

#Storage for scripts, backups and AI agents

A script, a backup tool or an AI agent uses your storage like any S3 app: an endpoint and an access key. Give each one its own key, so you can see what it does and switch it off alone.

#1. Give it its own user and key

1. Users & keys › New user, named after the job (backup-agent, claude-notes). Pithos creates its key and a drive of the same name.
2. Optional: Drives › New drive for that user if you want a differently named drive.
3. Open the key (Show secret & config) and press Export JSON…. Pick the drive and save the file.

The file looks like this:

Copy{
  "endpoint": "http://127.0.0.1:8000",
  "accessKey": "…",
  "secretKey": "…",
  "bucket": "backup-agent"
}

• The key reaches every drive of that user; bucket only says which one to use. A user's keys cannot see other users' drives, which is why one user per job is the boundary.
• The file is not encrypted. Keep it out of git, chats and shared folders. Save credentials… makes an encrypted copy instead (password or Theseus vault) for keeping.
• To stop the agent: Users & keys › Revoke on its key (or delete the user). Nothing else changes.

#2. Use it

Environment variables (most tools read these):

Copyexport AWS_ACCESS_KEY_ID=$(jq -r .accessKey pithos-backup-agent.json)
export AWS_SECRET_ACCESS_KEY=$(jq -r .secretKey pithos-backup-agent.json)
export AWS_REGION=us-east-1
export AWS_ENDPOINT_URL=$(jq -r .endpoint pithos-backup-agent.json)
BUCKET=$(jq -r .bucket pithos-backup-agent.json)
aws s3 cp report.pdf "s3://$BUCKET/reports/report.pdf"
aws s3 ls "s3://$BUCKET/reports/"

Backups with restic (encrypted, deduplicated snapshots; restore any day):

Copy# the four exports above, then:
export RESTIC_REPOSITORY="s3:$AWS_ENDPOINT_URL/$BUCKET/restic"
export RESTIC_PASSWORD_FILE=~/.config/restic/password   # keep this password: without it the backup cannot be read
restic -o s3.bucket-lookup=path -o s3.region=us-east-1 init
restic -o s3.bucket-lookup=path -o s3.region=us-east-1 backup ~/Documents
restic -o s3.bucket-lookup=path -o s3.region=us-east-1 snapshots

rclone (sync, mount, serve): add a remote with the four values (provider = Other, force_path_style = true), as in "Using drives from other apps" above, then rclone sync ~/Projects backup:backup-agent/projects.

Python (boto3):

Copyimport json, boto3
from botocore.config import Config
c = json.load(open("pithos-backup-agent.json"))
s3 = boto3.client("s3", endpoint_url=c["endpoint"], aws_access_key_id=c["accessKey"],
                  aws_secret_access_key=c["secretKey"], region_name="us-east-1",
                  config=Config(s3={"addressing_style": "path"}))
s3.upload_file("notes.md", c["bucket"], "notes/notes.md")
print([o["Key"] for o in s3.list_objects_v2(Bucket=c["bucket"]).get("Contents", [])])

Node (AWS SDK v3): new S3Client({ endpoint: c.endpoint, region: "us-east-1", forcePathStyle: true, credentials: { accessKeyId: c.accessKey, secretAccessKey: c.secretKey } }).

#3. Where the agent can reach it

• On the same computer as s3d: the endpoint http://127.0.0.1:8000 works as is. Local agents (Claude Code, a cron job, a backup app) need nothing else.
• From another machine or a cloud agent: 127.0.0.1 points to that machine, so it fails. Either move the drives to Drives on Silent Mode (the endpoint becomes https://s3.silentmode.st and keeps working with your computer off) or put s3d behind your own server with TLS and write that address into the JSON as endpoint.
• Narrower keys: on Drives on Silent Mode, ⋯ › Share… on a folder can make a key for one folder only: read, add new files (it can create files but never overwrite or delete one, good for an agent that drops reports or exports) or add, change and delete. restic needs the last one, because it removes its own lock files. A plain s3d only has whole-user keys.
• Files a tool uploads wait on this computer until a ~40 MB block fills; automatic upload sends leftovers after 10 quiet minutes, or press Upload now. Until then they are not on Sia yet.

#SSH keys and SFTP

s3d speaks only S3: there is no SSH login or SSH key to add. If a tool insists on SFTP, run rclone in front of it:

Copyrclone serve sftp backup:backup-agent --addr 127.0.0.1:2022 --authorized-keys ~/.ssh/authorized_keys

That gives SSH-key logins to one drive, but underneath it is the same S3 key, and rclone has to keep running. For agents and scripts, an S3 key per job (above) is simpler and easier to revoke; use SFTP only for tools that cannot do S3. rclone serve webdav and rclone mount work the same way for apps that want a network drive.

#Telling an AI agent

Give the agent the JSON file path, not the secret in the chat, and a short brief such as:

> Use the S3 storage described in pithos-backup-agent.json (keys endpoint, accessKey, secretKey, bucket; region us-east-1; path-style addressing). Only read and write inside that bucket, under backups/. Never print the secret key. Do not delete objects unless I ask.

#Common tasks

• Give an app its own key. Users & keys › create a user for the app (or use yours) › Create key. Revoke it later without touching your other keys.
• Share one file or folder with anyone. ⋯ › Share… › Create public link. The link reads only that file from your Sia account; nothing else in the account is exposed.
• Make a whole drive public. Keep the files in a drive of their own and set Access › Public read. Files are then at http://<s3d address>/<drive>/<path>. On a default setup that address is reachable only from this computer; for other people s3d needs a public address (for example behind your own server and a TLS proxy).
• Rename or move. ⋯ › Rename… on a file, folder or drive. Renaming a drive changes its name for S3 apps too.
• Back up. Keep the recovery phrase offline (or use the vault-derived phrase and back up the Theseus vault). Optionally POST /snapshots to keep a copy of s3d's database on Sia.
• Move to another computer. Install s3d, run s3d login with the same indexer login and the same phrase, then restore the database snapshot or recreate users and keys.

#Troubleshooting

#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).
• Signed s3d links and public drives reach other people only when s3d has a public address; navigate.st/sia public links do not need one.
• navigate.st/sia links have a daily download cap per link, and anyone with the link can read the file: it is decrypted on navigate.st to stream it.
• 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 on 127.0.0.1:8001 (Basic auth, empty user, adminPassword), region us-east-1, path-style addressing.
• Setup order: s3d config → s3d login (indexer URL + 12-word phrase, approve the "S3d" app at the indexer) → run s3d → s3d users create → s3d keys create → use any S3 client.
• Small files wait locally until a ~40 MB block fills; s3d flush or POST /objects/flush uploads 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.

For an agent that should store files: ask the user to create a separate S3 user in Pithos and export its key as JSON (Users & keys › Show secret & config › Export JSON…), then read the file instead of having secrets pasted. See "Storage for scripts, backups and AI agents".

Rules: never ask the user to paste their recovery phrase or secret keys into the conversation; have them type secrets only into s3d or Pithos on their own machine. Prefer read-only checks (s3d status, s3d users list, aws s3 ls) before changing anything, and confirm before deleting users, keys, drives or files.