pithos-site/docs/index.html
Local Dev 0092662b57 pithos.sia: public links, the source code, and the new silentmode.st/pithos address
The Share links card described the old week-long s3d links; public links
at navigate.st/sia are now the feature that works for anyone. The web
console no longer says "source release coming" because the code is public
on the forge, and canonical URLs follow the mirror to silentmode.st/pithos.
2026-10-04 20:15:41 +02:00

198 lines
32 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<script>/* /docs and /docs/ (and the silentmode.st/pithos/ mirror) resolve links the same way */ if (!location.pathname.endsWith("/")) document.write('<base href="' + location.pathname + '/">');</script>
<title>Pithos documentation — pithos.sia</title>
<meta name="description" content="Everything about Pithos and s3d, the Sia S3 gateway: the Pithos screens, the s3d command line, configuration, S3 clients, troubleshooting, and a brief for AI assistants.">
<link rel="icon" href="../assets/favicon.svg" type="image/svg+xml">
<link rel="alternate" type="text/markdown" href="pithos-docs.md" title="Markdown version for AI assistants">
<style>
:root{ --bg:#0b100e; --panel:#121a17; --panel2:#17211d; --line:rgba(255,255,255,.08); --ink:#e6ece9; --mut:#8e9c96; --acc:#3ddc97; }
*{box-sizing:border-box}
html{scroll-behavior:smooth;scroll-padding-top:70px}
body{margin:0;background:radial-gradient(1100px 560px at 50% -12%,#14271f,var(--bg));color:var(--ink);font:16px/1.7 system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;padding-top:52px}
a{color:var(--acc)}
code{font-family:ui-monospace,"Cascadia Mono","SF Mono",Consolas,monospace;font-size:.86em;background:var(--panel2);padding:.12em .4em;border-radius:5px;overflow-wrap:anywhere}
.topnav{position:fixed;top:0;left:0;right:0;z-index:20;display:flex;gap:4px;align-items:center;padding:10px 1.2rem;background:rgba(11,16,14,.9);backdrop-filter:blur(10px);border-bottom:1px solid var(--line)}
.topnav .brand{font-weight:600;color:var(--ink);text-decoration:none;margin-right:12px;font-size:15px;display:flex;align-items:center;gap:8px}
.topnav .brand img{width:20px;height:20px}
.topnav .brand .g{color:var(--acc)}
.topnav a{color:var(--mut);text-decoration:none;padding:6px 12px;border-radius:8px;font-size:14px}
.topnav a:hover{color:var(--ink);background:var(--panel)}
.topnav a.on{color:var(--acc)}
.topnav a.md{margin-left:auto}
.layout{max-width:1180px;margin:0 auto;padding:2rem 1.2rem 5rem;display:grid;grid-template-columns:230px minmax(0,1fr);gap:2.4rem}
.toc{position:sticky;top:72px;align-self:start;display:flex;flex-direction:column;gap:2px;font-size:14px;max-height:calc(100vh - 90px);overflow:auto}
.toc .t{color:var(--mut);font-size:12px;text-transform:uppercase;letter-spacing:.07em;margin:0 0 6px 10px}
.toc a{color:var(--mut);text-decoration:none;padding:5px 10px;border-radius:7px}
.toc a:hover{color:var(--ink);background:var(--panel)}
article{min-width:0}
h1{font-size:clamp(1.9rem,4.6vw,2.5rem);margin:0 0 .4rem;letter-spacing:-.4px}
h2{font-size:1.45rem;margin:2.6rem 0 .8rem;padding-top:1.2rem;border-top:1px solid var(--line)}
h3{font-size:1.1rem;margin:1.8rem 0 .5rem}
h2 .anchor,h3 .anchor{color:var(--mut);text-decoration:none;margin-left:-1.1em;padding-right:.3em;opacity:0}
h2:hover .anchor,h3:hover .anchor{opacity:.6}
p,li{color:#cfd8d4}
strong{color:var(--ink)}
.lede{color:var(--mut);font-size:1.05rem}
.table{overflow-x:auto;margin:1rem 0;border:1px solid var(--line);border-radius:10px}
table{border-collapse:collapse;width:100%;font-size:14.5px}
th,td{text-align:left;vertical-align:top;padding:9px 12px;border-bottom:1px solid var(--line)}
th{background:var(--panel);color:var(--mut);font-weight:600}
tr:last-child td{border-bottom:none}
pre.code{position:relative;background:#0f1613;border:1px solid var(--line);border-radius:10px;padding:14px 16px;overflow:auto;margin:1rem 0}
pre.code code{background:none;padding:0;font-size:13.5px;line-height:1.6;overflow-wrap:normal;white-space:pre}
pre.code .copy{position:absolute;top:8px;right:8px;font:12px system-ui;color:var(--mut);background:var(--panel2);border:1px solid var(--line);border-radius:6px;padding:3px 9px;cursor:pointer;opacity:.75}
pre.code .copy:hover{opacity:1;color:var(--ink)}
.agent{background:var(--panel);border:1px solid rgba(61,220,151,.25);border-radius:12px;padding:14px 18px;margin:1.2rem 0}
footer{color:var(--mut);font-size:14px;border-top:1px solid var(--line);margin-top:3rem;padding-top:1.2rem}
@media (max-width:860px){
.layout{grid-template-columns:1fr;gap:0;padding-top:1.2rem}
.toc{position:static;max-height:none;flex-direction:row;flex-wrap:wrap;gap:4px;margin-bottom:1rem}
.toc .t{width:100%;margin-left:4px}
.toc a{background:var(--panel);font-size:13px}
.topnav a:not(.brand):not(.md){display:none}
}
</style>
</head>
<body>
<nav class="topnav">
<a class="brand" href="../"><img src="../assets/favicon.svg" alt=""><span>pithos<span class="g">.sia</span></span></a>
<a href="../#features">Features</a>
<a href="../#get">Get Pithos</a>
<a class="on" href="./">Docs</a>
<a class="md" href="pithos-docs.md" title="The same page as plain Markdown, for AI assistants">Markdown ↓</a>
</nav>
<div class="layout">
<nav class="toc" aria-label="On this page"><div class="t">On this page</div><a href="#how-the-pieces-fit">How the pieces fit</a><a href="#getting-started-pithos-in-theseus">Getting started (Pithos in Theseus)</a><a href="#the-pithos-screen">The Pithos screen</a><a href="#drives-on-silent-mode">Drives on Silent Mode</a><a href="#other-ways-to-run-pithos">Other ways to run Pithos</a><a href="#s3d-on-the-command-line">s3d on the command line</a><a href="#using-drives-from-other-apps">Using drives from other apps</a><a href="#common-tasks">Common tasks</a><a href="#troubleshooting">Troubleshooting</a><a href="#limits">Limits</a><a href="#for-ai-assistants">For AI assistants</a></nav>
<article>
<h1>Pithos documentation</h1>
<div class="agent"><strong>Using an AI assistant?</strong> Give it this page or the <a href="pithos-docs.md">Markdown version</a>, then describe what you want to do. Type recovery phrases and secret keys only into s3d or Pithos on your own computer, never into a chat.</div>
<p>Pithos is a control panel for <strong>s3d</strong>, 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 <code>s3d</code> 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.</p>
<p>This page is also published as plain Markdown at <code>pithos.sia/docs/pithos-docs.md</code> for AI assistants.</p>
<h2 id="how-the-pieces-fit"><a class="anchor" href="#how-the-pieces-fit" aria-hidden="true">#</a>How the pieces fit</h2>
<div class="table"><table><thead><tr><th>Piece</th><th>What it is</th></tr></thead><tbody><tr><td><strong>Sia</strong></td><td>A decentralized storage network: independent hosts store your data, paid in siacoin.</td></tr><tr><td><strong>Indexer</strong></td><td>A service that rents space from Sia hosts and keeps track of where your data is. <code>sia.storage</code> is the indexer run by the Sia Foundation; you can run your own (<code>indexd</code>).</td></tr><tr><td><strong>Sia account</strong></td><td>Your account at an indexer. It holds the storage you pay for (sia.storage's free plan: 50 GB).</td></tr><tr><td><strong>s3d</strong></td><td>A program on your computer that speaks the S3 protocol and stores everything through your Sia account.</td></tr><tr><td><strong>S3 user</strong></td><td>A login inside your own s3d. Each user owns drives and has access keys.</td></tr><tr><td><strong>Access key</strong></td><td>An access key ID and secret key pair that S3 apps use to sign in as a user.</td></tr><tr><td><strong>Drive</strong></td><td>Top-level storage owned by one S3 user. S3 apps call it a <strong>bucket</strong>.</td></tr><tr><td><strong>Folder</strong></td><td>Part of a file's name (<code>photos/2026/beach.jpg</code>). Pithos keeps empty folders visible with a small marker.</td></tr><tr><td><strong>Pithos</strong></td><td>This app. It runs s3d for you and puts a screen over all of the above.</td></tr></tbody></table></div>
<p>Data flow: your app or Pithos → s3d on your computer → (encrypted, erasure-coded) → Sia hosts, tracked by your indexer account.</p>
<p><strong>Two things to know early:</strong></p>
<ol><li><strong>s3d waits before uploading small files.</strong> It packs uploads into blocks of about 40 MB before sending them to Sia. Until a block is full, files exist <strong>only on your computer</strong>. Pithos shows a "files waiting to upload" banner and uploads leftovers automatically after 10 quiet minutes (Settings › automatic upload); <code>s3d flush</code> or <strong>Upload now</strong> sends them immediately.</li><li><strong><code>127.0.0.1</code> means "this computer".</strong> s3d listens on <code>127.0.0.1:8000</code> by default, so links that start with it work only on the machine running s3d. Other devices cannot open them.</li></ol>
<h2 id="getting-started-pithos-in-theseus"><a class="anchor" href="#getting-started-pithos-in-theseus" aria-hidden="true">#</a>Getting started (Pithos in Theseus)</h2>
<p>Pithos comes with Theseus, the Silent Mode browser. Open it from the Pithos icon in the left-hand strip.</p>
<ol><li><strong>Unlock.</strong> Pithos opens only while your Theseus password vault is unlocked (PIN or master password), because it shows access-key secrets.</li><li><strong>Accounts › Get started.</strong> The guide walks through each step:<ol><li><em>Sia Storage account</em>: 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.</li><li><em>Install s3d</em>: Pithos downloads the pinned s3d release and checks its SHA-256.</li><li><em>Recovery phrase</em>: choose <strong>From my vault</strong> (Pithos derives the phrase from your Theseus vault, so there is nothing to write down) or use your own 12-word phrase.</li><li><em>Connect</em>: Pithos runs <code>s3d login</code> and opens the indexer's approval page. Approve the app named <strong>S3d</strong> there.</li><li><em>Start gateway</em>: s3d starts and keeps running (Pithos restarts it after a crash and when Theseus starts).</li><li><em>Access key</em>: Pithos creates your first S3 user, its drive and an access key. Save the key (Copy, or <strong>Save to encrypted file</strong>).</li></ol></li><li><strong>Drives.</strong> Open your drive and drag files in.</li></ol>
<p>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.</p>
<h2 id="the-pithos-screen"><a class="anchor" href="#the-pithos-screen" aria-hidden="true">#</a>The Pithos screen</h2>
<p>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.</p>
<h3 id="accounts"><a class="anchor" href="#accounts" aria-hidden="true">#</a>Accounts</h3>
<ul><li><strong>Your Sia accounts</strong> at the top: the account in use (with its free space) and any accounts set aside on this computer, each with <strong>Switch to</strong>, plus <strong>Add another account</strong>.</li><li><strong>Add another account</strong> 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.</li><li><strong>Account label</strong>: Pithos cannot see the login email, so name the account yourself (for example the email you approved the connection with).</li><li><strong>Which Sia account this is</strong>: the account key, app name, storage used, last use and indexer, read from the indexer.</li></ul>
<h3 id="overview"><a class="anchor" href="#overview" aria-hidden="true">#</a>Overview</h3>
<ul><li><strong>Gateway</strong>: s3d's state (running, stopped, crashed, external), endpoint, version, config and data folders; Start, Restart, Stop.</li><li><strong>Upload pipeline</strong>: pending (waiting on this computer), on Sia, awaiting pin, open multipart uploads, failed and orphaned objects; <strong>Flush now</strong>.</li><li><strong>Free space</strong>: used and free storage on your Sia account.</li></ul>
<h3 id="users-keys"><a class="anchor" href="#users-keys" aria-hidden="true">#</a>Users &amp; keys</h3>
<ul><li>Create a user (and its drive, named after it), delete a user.</li><li>Create and revoke access keys. Each key shows ready-made settings for the AWS CLI, rclone and environment variables.</li><li><strong>Save to encrypted file</strong> / <strong>Open saved credentials</strong>: keep keys in a password-protected <code>.pithoskey</code> file (in Theseus it can be sealed with your vault instead).</li></ul>
<h3 id="drives"><a class="anchor" href="#drives" aria-hidden="true">#</a>Drives</h3>
<ul><li><strong>Views</strong>: Icons (with picture previews), List, Details. Each page remembers its view.</li><li><strong>Upload</strong>: drag files in or use Upload. Single uploads up to 5 GiB (1 GiB from the sidebar).</li><li><strong>New folder</strong>, <strong>Rename…</strong> (files, folders and whole drives; a rename is an instant server-side copy, nothing is uploaded again), <strong>Delete</strong>.</li><li><strong>Viewer</strong>: 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).</li><li><strong>Share…</strong>: a <strong>public link</strong> at <code>https://navigate.st/sia/&lt;id&gt;/&lt;name&gt;</code> 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.</li><li><strong>Access…</strong>: private, public read, or public read + list, for the <strong>whole drive</strong> (s3d cannot make a single folder public). Change it any time.</li><li><strong>Free space</strong> line under the account name.</li></ul>
<h3 id="settings"><a class="anchor" href="#settings" aria-hidden="true">#</a>Settings</h3>
<p>Edits <code>s3d.yml</code>; 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.</p>
<h3 id="logs"><a class="anchor" href="#logs" aria-hidden="true">#</a>Logs</h3>
<p>Live output of s3d and Pithos's own notes (why it started or did not start s3d, flushes, errors).</p>
<h3 id="addresses-updates-and-the-lock"><a class="anchor" href="#addresses-updates-and-the-lock" aria-hidden="true">#</a>Addresses, updates and the lock</h3>
<ul><li>In Theseus, the full page lives at <code>pithos.sia/&lt;user&gt;/&lt;drive&gt;/&lt;folder&gt;</code> (and <code>pithos.sia/settings</code>, <code>pithos.sia/account</code> …). The bare <code>pithos.sia</code> is this website.</li><li>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.</li><li>When the vault locks, Pithos locks too; Unlock asks for your PIN.</li></ul>
<h2 id="drives-on-silent-mode"><a class="anchor" href="#drives-on-silent-mode" aria-hidden="true">#</a>Drives on Silent Mode</h2>
<p>By default s3d runs on your computer. Settings › <strong>Where your drives live</strong> can move it to Silent Mode's server (<code>s3.silentmode.st</code>) instead. It keeps working with your computer off, other devices can reach it, and the Pithos screens stay the same.</p>
<ul><li><strong>Still your own Sia account.</strong> 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.</li><li><strong>Encrypted before it leaves.</strong> Pithos encrypts file names and contents on your computer, with keys from your Theseus vault (or a key file beside <code>s3d.yml</code> that you should back up).</li><li><strong>Sharing a plain s3d cannot do.</strong> 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.</li><li><strong>Signing up</strong> needs a signature from the wallet that owns a BNS name: one hosted account per name.</li></ul>
<p><strong>Public folders anyone can open.</strong> Make a folder public (⋯ › Share… on a drive on Silent Mode) and it gets an address like <code>https://navigate.st/s3/&lt;your-bns-name&gt;/&lt;drive&gt;/&lt;folder&gt;/</code>: 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 <code>?json</code> to a folder address for a JSON listing.</p>
<h2 id="other-ways-to-run-pithos"><a class="anchor" href="#other-ways-to-run-pithos" aria-hidden="true">#</a>Other ways to run Pithos</h2>
<h3 id="web-console"><a class="anchor" href="#web-console" aria-hidden="true">#</a>Web console</h3>
<pre class="code" data-lang="bash"><button class="copy" type="button" aria-label="Copy">Copy</button><code>npm install
node bin/pithos-web.js</code></pre>
<p>It prints a one-time sign-in link for <code>http://127.0.0.1:8700</code>. Options:</p>
<div class="table"><table><thead><tr><th>Flag</th><th>Meaning</th></tr></thead><tbody><tr><td><code>--listen host:port</code></td><td>Address to serve on (default <code>127.0.0.1:8700</code>). Anything beyond loopback needs a password.</td></tr><tr><td><code>--config &lt;s3d.yml&gt;</code></td><td>Which s3d config to manage.</td></tr><tr><td><code>--s3d &lt;binary&gt;</code></td><td>Use this s3d binary.</td></tr><tr><td><code>--bin-dir &lt;dir&gt;</code></td><td>Where Pithos installs s3d.</td></tr><tr><td><code>--password-file &lt;file&gt;</code></td><td>Password login (or set <code>PITHOS_PASSWORD</code>, at least 12 characters).</td></tr><tr><td><code>--allow-host &lt;name[:port]&gt;</code></td><td>Extra Host names allowed (behind a reverse proxy). Repeatable.</td></tr></tbody></table></div>
<p>Remote access: <code>PITHOS_PASSWORD='long random secret' node bin/pithos-web.js --listen 0.0.0.0:8700 --allow-host pithos.example.org</code>, behind a TLS reverse proxy.</p>
<h3 id="desktop-app"><a class="anchor" href="#desktop-app" aria-hidden="true">#</a>Desktop app</h3>
<pre class="code" data-lang="bash"><button class="copy" type="button" aria-label="Copy">Copy</button><code>npm run desktop</code></pre>
<p>The window signs itself in; quitting stops s3d.</p>
<h3 id="which-s3d-pithos-manages"><a class="anchor" href="#which-s3d-pithos-manages" aria-hidden="true">#</a>Which s3d Pithos manages</h3>
<p>The same one a hand-run <code>s3d</code> uses: <code>S3D_CONFIG_FILE</code> if set, otherwise <code>%APPDATA%\s3d\s3d.yml</code> (Windows), <code>~/Library/Application Support/s3d/s3d.yml</code> (macOS), <code>/etc/s3d/s3d.yml</code> (Linux). If another s3d already serves that config, Pithos shows it as <strong>external</strong> and does not start a second one.</p>
<h2 id="s3d-on-the-command-line"><a class="anchor" href="#s3d-on-the-command-line" aria-hidden="true">#</a>s3d on the command line</h2>
<p>Pithos needs s3d <strong>v0.2.0</strong> or newer. Download it from the s3d releases on GitHub (SiaFoundation/s3d), or let Pithos install it.</p>
<h3 id="commands"><a class="anchor" href="#commands" aria-hidden="true">#</a>Commands</h3>
<div class="table"><table><thead><tr><th>Command</th><th>What it does</th></tr></thead><tbody><tr><td><code>s3d</code></td><td>Start the S3 gateway (runs until stopped).</td></tr><tr><td><code>s3d version</code></td><td>Print the version.</td></tr><tr><td><code>s3d config</code></td><td>Interactive setup; writes <code>s3d.yml</code>.</td></tr><tr><td><code>s3d login</code></td><td>Register this s3d with an indexer (asks for the indexer URL and the recovery phrase, prints an approval link).</td></tr><tr><td><code>s3d status</code></td><td>Upload pipeline stats from the running s3d.</td></tr><tr><td><code>s3d flush</code></td><td>Upload everything waiting to Sia now (blocks until done).</td></tr><tr><td><code>s3d users create &lt;name&gt;</code> / <code>delete &lt;name&gt;</code> / <code>list</code></td><td>Manage S3 users.</td></tr><tr><td><code>s3d keys create &lt;user&gt;</code></td><td>New access key (prints the ID and secret). <code>--access-key &lt;id&gt; --secret-key &lt;secret&gt;</code> sets them yourself (16-128 and 32-128 characters).</td></tr><tr><td><code>s3d keys list [user]</code> / <code>keys delete &lt;access-key-id&gt;</code></td><td>List or revoke keys.</td></tr></tbody></table></div>
<h3 id="a-full-setup-by-hand"><a class="anchor" href="#a-full-setup-by-hand" aria-hidden="true">#</a>A full setup by hand</h3>
<pre class="code" data-lang="bash"><button class="copy" type="button" aria-label="Copy">Copy</button><code>s3d 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</code></pre>
<p>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.</p>
<h3 id="where-things-live"><a class="anchor" href="#where-things-live" aria-hidden="true">#</a>Where things live</h3>
<div class="table"><table><thead><tr><th></th><th>Windows</th><th>macOS</th><th>Linux</th></tr></thead><tbody><tr><td>Config</td><td><code>%APPDATA%\s3d\s3d.yml</code></td><td><code>~/Library/Application Support/s3d/s3d.yml</code></td><td><code>/etc/s3d/s3d.yml</code></td></tr><tr><td>Data (database, files waiting)</td><td><code>%APPDATA%\s3d</code></td><td><code>~/Library/Application Support/s3d</code></td><td><code>/var/lib/s3d</code></td></tr></tbody></table></div>
<p>Environment variables: <code>S3D_CONFIG_FILE</code> (use this config file), <code>S3D_DATA_DIR</code> (data folder).</p>
<h3 id="s3d-yml"><a class="anchor" href="#s3d-yml" aria-hidden="true">#</a>s3d.yml</h3>
<pre class="code" data-lang="yaml"><button class="copy" type="button" aria-label="Copy">Copy</button><code>apiAddress: 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 }</code></pre>
<h3 id="admin-api"><a class="anchor" href="#admin-api" aria-hidden="true">#</a>Admin API</h3>
<p>HTTP Basic auth with an empty user name and <code>adminPassword</code>:</p>
<div class="table"><table><thead><tr><th>Request</th><th>Result</th></tr></thead><tbody><tr><td><code>GET /stats/uploads</code></td><td>Pending, uploaded, unpinned, failed, orphaned objects and multipart uploads (JSON).</td></tr><tr><td><code>POST /objects/flush</code></td><td>Upload everything waiting, now.</td></tr><tr><td><code>POST /snapshots</code></td><td>Back up s3d's database to Sia as a snapshot.</td></tr></tbody></table></div>
<pre class="code" data-lang="bash"><button class="copy" type="button" aria-label="Copy">Copy</button><code>curl -u :change-me http://127.0.0.1:8001/stats/uploads</code></pre>
<h2 id="using-drives-from-other-apps"><a class="anchor" href="#using-drives-from-other-apps" aria-hidden="true">#</a>Using drives from other apps</h2>
<p>Any S3 app works. Use the endpoint <code>http://127.0.0.1:8000</code>, region <code>us-east-1</code>, <strong>path-style</strong> addressing, and an access key from Users &amp; keys.</p>
<p><strong>AWS CLI</strong> (<code>~/.aws/config</code>):</p>
<pre class="code" data-lang="ini"><button class="copy" type="button" aria-label="Copy">Copy</button><code>[profile s3d]
region = us-east-1
endpoint_url = http://127.0.0.1:8000
s3 =
addressing_style = path</code></pre>
<pre class="code" data-lang="bash"><button class="copy" type="button" aria-label="Copy">Copy</button><code>aws --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</code></pre>
<p><strong>rclone</strong> (<code>rclone config</code>, or <code>~/.config/rclone/rclone.conf</code>):</p>
<pre class="code" data-lang="ini"><button class="copy" type="button" aria-label="Copy">Copy</button><code>[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</code></pre>
<pre class="code" data-lang="bash"><button class="copy" type="button" aria-label="Copy">Copy</button><code>rclone ls s3d:my-drive
rclone copy ./photos s3d:my-drive/photos --progress</code></pre>
<p><strong>Environment variables</strong> for SDKs and tools: <code>AWS_ACCESS_KEY_ID</code>, <code>AWS_SECRET_ACCESS_KEY</code>, <code>AWS_DEFAULT_REGION=us-east-1</code>, <code>AWS_ENDPOINT_URL=http://127.0.0.1:8000</code>.</p>
<h2 id="common-tasks"><a class="anchor" href="#common-tasks" aria-hidden="true">#</a>Common tasks</h2>
<ul><li><strong>Give an app its own key.</strong> Users &amp; keys › create a user for the app (or use yours) › Create key. Revoke it later without touching your other keys.</li><li><strong>Share one file or folder with anyone.</strong> ⋯ › Share… › Create public link. The link reads only that file from your Sia account; nothing else in the account is exposed.</li><li><strong>Make a whole drive public.</strong> Keep the files in a drive of their own and set Access › Public read. Files are then at <code>http://&lt;s3d address&gt;/&lt;drive&gt;/&lt;path&gt;</code>. 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).</li><li><strong>Rename or move.</strong> ⋯ › Rename… on a file, folder or drive. Renaming a drive changes its name for S3 apps too.</li><li><strong>Back up.</strong> Keep the recovery phrase offline (or use the vault-derived phrase and back up the Theseus vault). Optionally <code>POST /snapshots</code> to keep a copy of s3d's database on Sia.</li><li><strong>Move to another computer.</strong> Install s3d, run <code>s3d login</code> with the same indexer login and the same phrase, then restore the database snapshot or recreate users and keys.</li></ul>
<h2 id="troubleshooting"><a class="anchor" href="#troubleshooting" aria-hidden="true">#</a>Troubleshooting</h2>
<div class="table"><table><thead><tr><th>What you see</th><th>What it means / what to do</th></tr></thead><tbody><tr><td>"N files waiting to upload", or "0 B on Sia"</td><td>Files are still in the local buffer. Click <strong>Upload now</strong> (or <code>s3d flush</code>); automatic upload does it after 10 quiet minutes.</td></tr><tr><td>s3d "stopped" or "crashed"</td><td>Overview › Start; read Logs for the reason. "Not registered" means <code>s3d login</code> has not been done for this config.</td></tr><tr><td>A link with <code>127.0.0.1</code> does not open elsewhere</td><td>Expected: it points to the computer running s3d.</td></tr><tr><td><code>SignatureDoesNotMatch</code> in an S3 app</td><td>Wrong secret, or the app uses virtual-host style; switch to path-style and region <code>us-east-1</code>.</td></tr><tr><td>"address already in use"</td><td>Another program (or another s3d) uses port 8000/8001; change <code>apiAddress</code>/<code>adminAddress</code> or stop the other one.</td></tr><tr><td>Pithos shows "external"</td><td>Another s3d is already running for this config; Pithos reads its stats but leaves it alone.</td></tr><tr><td>Pithos is locked</td><td>Your Theseus vault is locked; Unlock asks for the PIN.</td></tr><tr><td>A different account than expected</td><td>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.</td></tr></tbody></table></div>
<h2 id="limits"><a class="anchor" href="#limits" aria-hidden="true">#</a>Limits</h2>
<ul><li>Public access is per drive, read-only for others; s3d has no folder-level rules or write rights for other people.</li><li>Single uploads are capped at 5 GiB (multipart uploads from S3 tools work for larger files).</li><li>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.</li><li>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.</li><li>Folder-level sharing and rights for other people need drives on Silent Mode (see that section); a plain s3d cannot do them.</li></ul>
<h2 id="for-ai-assistants"><a class="anchor" href="#for-ai-assistants" aria-hidden="true">#</a>For AI assistants</h2>
<p>You are helping someone run <strong>s3d</strong> (the Sia S3 gateway), optionally through <strong>Pithos</strong>. Facts to rely on:</p>
<ul><li>s3d v0.2.0+, S3 API on <code>127.0.0.1:8000</code>, admin API on <code>127.0.0.1:8001</code> (Basic auth, empty user, <code>adminPassword</code>), region <code>us-east-1</code>, path-style addressing.</li><li>Setup order: <code>s3d config</code> → <code>s3d login</code> (indexer URL + 12-word phrase, approve the "S3d" app at the indexer) → run <code>s3d</code> → <code>s3d users create</code> → <code>s3d keys create</code> → use any S3 client.</li><li>Small files wait locally until a ~40 MB block fills; <code>s3d flush</code> or <code>POST /objects/flush</code> uploads them now.</li><li>Buckets ("drives") can be private, public read, or public read + list; nothing finer.</li><li>Config lookup: <code>S3D_CONFIG_FILE</code>, else the OS default path listed above.</li></ul>
<p>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 (<code>s3d status</code>, <code>s3d users list</code>, <code>aws s3 ls</code>) before changing anything, and confirm before deleting users, keys, drives or files.</p>
<footer>Pithos is open source: <a href="https://code.silentmode.st/silentmode/pithos">code.silentmode.st/silentmode/pithos</a>. s3d is by the Sia Foundation: <a href="https://github.com/SiaFoundation/s3d">github.com/SiaFoundation/s3d</a>.</footer>
</article>
</div>
<script>
// With the <base> above, '#section' links would reload the page; scroll instead.
document.addEventListener('click', (e) => { const a = e.target.closest('a[href^="#"]'); if (!a) return; const t = document.getElementById(a.getAttribute('href').slice(1)); if (!t) return; e.preventDefault(); t.scrollIntoView({ behavior: 'smooth' }); history.replaceState(null, '', location.pathname + a.getAttribute('href')); });
document.querySelectorAll('pre.code .copy').forEach((b) => b.addEventListener('click', async () => {
try { await navigator.clipboard.writeText(b.nextElementSibling.textContent); b.textContent = 'Copied'; setTimeout(() => { b.textContent = 'Copy'; }, 1500); } catch {}
}));
</script>
</body>
</html>