Frequently asked questions

Type to filter the questions, or pick a category. Each question is a file in website/src/content/faq/.

AllGeneralHardwareInstallationStorageFiles and sharingUsers and permissionsNetworkAppsUpdatesSecurity and privacyDevelopment

66 of 66 questions

Is Pithyx free?

Yes. The system is free software under the AGPL-3.0, and the npm packages for app developers (@pithyx/sdk, @pithyx/ui, @pithyx/cli) are MIT. There is no paid edition and no feature behind an account.

Details: License.

May I fork Pithyx or ship it under another name?

Yes, under the GNU AGPL-3.0, with the terms in NOTICE. A fork or redistribution keeps the attribution “Based on Pithyx (https://github.com/pithyx/pithyx), originally created by Schecher1 (https://github.com/Schecher1), licensed under the GNU AGPL-3.0.” in NOTICE, wherever it appears in the source and docs, and on its About page. A modified version must use a product name of its own (not Pithyx) and not the Pithyx logo, and must not present itself as Pithyx. Apps built with the MIT-licensed npm packages are not affected.

Details: License.

Can I put my important data on Pithyx yet?

Yes, with a backup. Pithyx 1.0 is marked beta: we consider it stable, but it has not yet proven itself on real boxes in everyday use. Treat it as beta and keep a copy of everything important on another device. Pools are not encrypted yet.

Details: What is Pithyx.

Does Pithyx need an internet connection?

No. The installer, the desktop, storage and file sharing work without internet. Only the Store fetches its catalogs and the container images of catalog apps from the internet, and the clock uses public time servers unless you set your own.

Details: What leaves the box.

Is there an app for my phone?

There is no separate mobile app. The web desktop adapts to the screen: on a phone each app fills the screen, on a tablet windows are maximized. For files, any app that speaks SMB 3, SFTP, WebDAV or FTP with TLS can connect.

Details: Phones and tablets.

Can an AI assistant read these docs?

Yes. /llms.txt lists every page, /llms/<area>.txt bundles one area and /llms-full.txt holds everything, all as plain Markdown. Every page also exists as Markdown with .md added to its address.

Details: Docs overview.

How do you pronounce Pithyx, and where does the name come from?

/ˈpɪθɪks/, “PITH-iks”. Pandora never opened a box: she opened a pithos (πίθος), a great storage jar of ancient Greece, which Erasmus of Rotterdam later mistranslated as pyxis, a box. What stayed inside was hope. Pithyx keeps what matters, on your hardware. The stem is pithos; the ending -yx is a stylization after Greek models such as onyx and Styx.

Which hardware do I need?

A 64-bit x86 computer (x86-64-v2 or newer) with UEFI, at least 2 GB of memory (4 GB or more recommended) and an internal system disk of at least 32 GB. The installer checks all of this before it starts. The reference machine is an Intel N100 or N305 with 8 GB of memory.

Details: Hardware requirements.

Do I need more than one disk?

Yes, for your data. The system goes on one disk, or on two as a mirror, and Pithyx never puts a pool on the system disk. Your files live on pools that you create on further disks in the Storage app.

Details: Disks and pools.

Does Pithyx run on a Raspberry Pi or another ARM board?

No. The image and the installer are for 64-bit x86 only. There is no arm64 image and no 32-bit version.

Details: Hardware requirements.

Can I install the system on a USB stick or SD card?

Yes, if it has at least 32 GB, but the installer warns you, and you decide. The system writes logs and its database to the system disk all the time, and a cheap USB stick or memory card wears out within months. If you use one, take a USB SSD or a fast USB 3 stick of a known brand (for a card, one made for continuous use), best two as a mirror, and keep a configuration backup. Built-in eMMC, as in many small computers, counts as an internal disk and gets no warning. A hard disk works too; the installer hints that an SSD is faster, quieter and uses less power.

Details: Disks and pools.

Does Wi-Fi work?

No. Pithyx supports wired network cards only. Connect the box with a network cable.

Details: Network requirements.

Can I run Pithyx in a virtual machine?

The installer is tested in virtual machines with QEMU and KVM and UEFI firmware, with the image attached as a USB stick. Other hypervisors, starting the image as a virtual CD and a range of real hardware have not been tested. The VM needs UEFI with Secure Boot off and its own virtual disks for pools.

Details: Hardware requirements.

Where do I download Pithyx?

From the releases on GitHub. The installer comes as one image file, pithyx-<version>-amd64.iso, with a .sha256 checksum file next to it, which you write to a USB stick as a whole disk image. The image carries no signature, so the checksum only shows that the download is complete.

Details: Write the USB stick.

Does Pithyx work with Secure Boot or legacy BIOS?

No. Pithyx starts only in UEFI mode, and Secure Boot must be off because the ZFS module is not signed. The first page of the installer checks both and tells you what to change in the firmware settings.

Details: Firmware and boot.

How do I find the address of my box?

The console of the box shows its address, for example https://192.168.1.50:7484 (http:// while the installer runs, with a QR code). The box does not announce a name on the network, so without a screen look up its address in your router’s list of DHCP clients. If the console says it is waiting for a network address, check the network cable.

Details: Booting from the stick.

Why does the installer say "Installation in use"?

The first browser that opens the installer owns the installation; every other browser sees Installation in use, and the console names the address that owns it. Continue in that browser. To start over, restart the computer from the stick.

Details: Opening the installer.

Does the USB stick have to stay in after the installation?

No. The installed system writes its boot loader to every system disk and adds a boot entry for it, so the box starts from its disk even with the stick still in. The installer still asks you to remove the stick before the restart.

Details: UEFI settings.

Can I move my existing NAS system over?

Pithyx installs fresh only; it does not import the configuration of other systems. Existing ZFS pools can be imported in the Storage app after the installation, first read-only so you can check them.

Details: Importing and exporting.

Does reinstalling Pithyx delete my data?

Not if you choose only the system disks: the installer erases the disks you select and nothing else. Afterwards import your pools in Storage with Import a pool… (a forced import is normal after a reinstall) and restore a configuration backup in Settings > Backup and restore. The installer does neither for you.

Details: Recovery and reinstall.

My pool is missing after a restart. What now?

A pool you created or imported for use comes back at every boot, as long as its disks are there. If it is missing or shows missing disks, check cables and power of the disks and restart; shared folders and apps on it stay unavailable until it is back. A pool you only imported read-only as a preview is not kept, and after a reinstall the box does not know your pools: import them with Import a pool… in Storage.

Details: Importing and exporting.

Why is my disk "Not available" or asks for its serial number?

A disk is Not available when it holds the system, is already in a pool, is read-only or in use, shares its serial number with another disk, or holds data but has no serial number; the Storage app shows the reason. A disk with partitions or data Needs confirmation: type its serial number to use it, and everything on it is erased.

Details: Disk verdicts.

Can I encrypt a pool?

Not in this version. The pool wizard refuses Encrypt with a key, so choose No encryption. A pool cannot be encrypted afterwards.

Details: Encryption.

Can I add disks to a pool later?

Yes, in two ways: Add disks… adds a new group of disks to the pool, and Expand with a disk… widens a RAID-Z group by one disk. Both are irreversible. The Storage app has no button to turn a single disk into a mirror later.

Details: Growing a pool.

A disk in my pool failed. What do I do?

Administrators get a notification, and a pool with redundancy keeps working in the state Degraded. Replace the disk with Replace… in Storage and confirm the new disk’s serial number; ZFS then rebuilds the data (resilver). A disk that comes back by itself is rebuilt on its own.

Details: Storage and pools.

Does Pithyx wake my sleeping disks?

Pithyx avoids it: SMART values are read only from awake disks, and the Resource Monitor uses the kernel’s counters. Some actions do wake disks: a scrub, Scan disks when importing, and the optional log archive about once a day. Pithyx has no setting that sends disks to sleep.

Details: Health and warnings.

Are snapshots and restore points a backup?

No. Restore points and snapshots live on the same disks as your files, so they help against accidental deletion and ransomware but not against a lost pool. The configuration backup in Settings holds settings and users, not your files. Keep a copy of your files on another device.

Details: Restore points.

How do I reach my files from my computer?

Over SMB, SFTP, WebDAV or FTP, signing in with your Pithyx user name and password. SMB is on in a fresh installation and new users may use it; the other services an administrator switches on and grants. On Windows type \\<box-address>\ in File Explorer, on macOS use smb://<box-address>/.

Details: Access files from other devices.

Do users have a private folder of their own?

Yes. Every user has a home folder that only they and the administrators can open. It is home in Files and over SMB, SFTP, WebDAV and FTP; administrators also see every user’s home below homes. It has its own recycle bin. Administrators choose its pool and quota in Settings > Home folders.

Details: Home folders.

Where did my deleted file go?

Into the recycle bin of its shared folder, if you deleted it in Files, over SMB or over WebDAV. Open Recycle bin in the sidebar of Files and choose Restore. Items stay there for 30 days by default. Delete permanently (Shift+Del) skips the bin, and deleting over SFTP or FTP may skip it too.

Details: The recycle bin.

Can I get an older version of a file back?

Yes, if an administrator switched on restore points for the shared folder (they are on for new folders). Right-click the file in Files and choose Previous versions; there is one point per day for 7 days. Windows shows the same points as Previous versions over SMB.

Details: Previous versions.

Why do my videos or HEIC photos have no thumbnail?

Files draws thumbnails only for JPEG, PNG, WebP and GIF images up to 256 MiB and 50 million pixels; other types show an icon. The Viewer opens more formats, including PDF, text, and audio and video your browser can play.

Details: Thumbnails and the viewer.

Why does the box not show up under Network in Windows or in Finder?

Pithyx does not announce itself on the network, so it does not appear in network browsing lists. Type its address instead: \\<box-address>\ in Windows File Explorer, or smb://<box-address>/ in Connect to Server on macOS.

Details: Access files from other devices.

Why is my password refused over SMB or SFTP?

Usually one of three things: your account lacks the right for that service, the account is deactivated, or the service does not know your password yet. For the last one, sign in once on the web desktop, or ask an administrator to set a new password. After five wrong attempts within five minutes, further attempts pause for a short time.

Details: Signing in.

Does Pithyx support NFS or older SMB versions?

No. Pithyx offers SMB 3, SFTP, WebDAV and FTP, with no NFS and no guest access, and older clients that only speak SMB 1 or 2 cannot connect. For devices such as scanners, use FTP (with TLS, or plain FTP if an administrator allows it).

Details: File services.

I forgot my password. What now?

Ask an administrator to set a new one; there is no reset by email. An administrator who forgot their own password chooses Forgot password? on the sign-in page and enters the recovery key from the installation. Without the key and without another administrator, only a reinstall helps.

Details: Forgotten password.

How do I change my password?

Users cannot change their own password in this version: an administrator sets a new one in Settings > Users with New password, which signs you out everywhere. A password needs at least 8 characters and must not be on the list of widely used passwords; there are no rules about capitals or symbols.

Details: Changing the password.

I lost the recovery key. What now?

As long as an administrator can still sign in, nothing is lost, but the key cannot be shown again: the box stores only a hash. Using the key replaces it with a new one, and the configuration backup contains it. If you lose both the key and every administrator password, the system has to be reinstalled.

Details: The recovery key.

I lost my phone with the authenticator app. How do I sign in?

Choose Use a recovery code instead at sign-in and enter one of the 10 recovery codes you stored when you turned two-factor sign-in on; each works once. An administrator without codes can reset with the recovery key, which turns two-factor sign-in off. For other users the interface has no way yet to turn it off for them.

Details: Two-factor sign-in.

Why can a new user not see a shared folder or an app?

A new user can sign in to the desktop, use SMB and open Files and Viewer, and nothing else. Give access to each shared folder, the other file services and the apps in the user’s Rights dialog, or to a group the user is in. A shared folder without access is hidden, not refused.

Details: Permissions.

Does deleting a user delete their files?

Only if you choose so. When you delete a user, Pithyx asks what happens to their home folder: keep it (the default), move its files into a shared folder, or delete it after you typed the user name. Files the user created in shared folders always stay, and the user id is never given to anyone else. To lock someone out without deleting anything, Deactivate the account: it loses every right and is signed out.

Details: Home folders.

How long do I stay signed in?

Up to 7 days without using the desktop and at most 30 days in total. Sign out ends the session of this browser only; there is no list of sessions and no way to sign out other devices yourself. A new password set by an administrator ends all your sessions.

Details: Sessions and devices.

I set a wrong network address and lost the connection. What now?

Wait 60 seconds: every network change goes back on its own unless you confirm it with Keep. If you are still locked out, use the console menu on the box’s own screen: [r] resets every card to DHCP and [s] sets a static address, without a password.

Details: The confirmation timer.

Can I use several network cards, bonding or VLANs?

Yes. In Settings > Network each card gets its own settings, Add bond combines cards (active-backup, LACP or adaptive load balancing), and Add VLAN adds a tagged VLAN on a card or bond. IPv4 and IPv6 can each be automatic, static or off. Wi-Fi and bridges have no settings.

Details: Network.

Which ports does Pithyx use?

The web desktop and WebDAV use port 7484 (HTTPS); ports 80 and 443 redirect there, except for domains of the built-in reverse proxy. SMB uses 445, SFTP 22, and FTP 21 with passive data ports 50000 to 50099. The box’s firewall lets in only the web ports, the file services that are switched on and the ports of reverse proxy streams, and Settings > File services can limit the file services to private networks. Pithyx offers no remote access of its own; reach the box from outside over a VPN rather than forwarding these ports from your router.

Details: File services.

Can I put the box behind a reverse proxy?

Yes. Point the proxy at https://<box-address>:7484, let it trust the box’s root (Settings > Certificates) or skip the certificate check for this backend, and pass WebSocket upgrades through. The box speaks only HTTPS; the connection from the proxy costs next to nothing on a local network.

Details: Certificates.

Can the box make my other services reachable under their own domains?

Yes. Settings > Reverse proxy forwards domains on ports 443 and 80 to services in your network or on the box, with a certificate from the box’s authority or one you upload, optionally behind Basic Auth or the Pithyx sign-in. Point the domains at the box in your DNS or router first. Streams forward a TCP or UDP port for services that do not speak HTTP. The box itself stays on port 7484.

Details: Reverse proxy.

Where do apps come from?

Administrators install them in the Store, from the official or community catalog, from catalogs they add, or from a package file (.pithyxapp). The official and community catalogs are signed and checked by the box; own catalogs and package files are not verified. Each app runs in a sandbox, and its backend, if it has one, runs in containers.

Details: Apps and the Store.

Is the community catalog on, and can I switch it off?

Yes, it is on by default, next to the official catalog. Its apps come from developers outside the Pithyx project; the project reviews, builds and signs them, but cannot vouch for them as for its own apps. To see only official apps, open the Store’s gear and switch the community catalog off under Catalogs; switching it on again asks once more.

Details: Catalogs and trust.

Why does my app not start?

The most common causes: the app’s pool is offline or locked (“Pool not available”), its backend is still starting (a request waits up to 30 seconds), or an administrator disabled the app or took away your right to use it. An administrator finds the backend’s messages in the Log Center under the source app/<id>. If the app’s access expired, close the window and open the app again.

Details: When an app does not start.

Can normal users install apps?

No. Only administrators open the Store and install apps. For each app they choose Who may use it: everybody, administrators only, or selected groups and users. Ask an administrator if you miss an app.

Details: App access.

Where do apps keep their data?

On the app pool an administrator picks at the first app install, in a dataset per app; Docker’s data lives on the same pool, never on the system disk. The pool cannot change while an app is installed. Uninstalling asks whether to keep the data, so a later install finds it again.

Details: The app pool.

What can an app see of my files and data?

Only what its permissions allow, and never more than your own account may do. Without file permissions an app sees no files; with them it reads files you open with it or pick in a dialog, or browses the shared folders you may use. Without the permission Internet it cannot leave the box. An administrator sees the permissions before installing and can switch them off.

Details: What an app may access.

Do I have to set up Docker, and can I run my own containers?

No setup is needed: Pithyx runs Debian’s Docker itself, and only while an app with a backend is installed. Containers run only as part of an app, from a checked Compose subset with images pinned by digest, on an internal network without host ports. Pithyx has no general container manager, and version 0.1 refuses the Docker socket and host-wide rights.

Details: Backends and Docker.

How do I update Pithyx?

In Settings > Updates. The box checks its channel once a day and notifies the administrators; it never installs by itself. Install {version} takes a snapshot of the system, installs the update and restarts, and goes back to the snapshot by itself if the new version fails its check. Without internet, upload a .pithyxupdate file instead. Pools and their files are not touched.

Details: System updates.

Are apps updated automatically, and can I go back?

That depends on the policy in the Store settings: Install it, Tell administrators (the default) or Do nothing, checked daily at 03:00 by default. An update that asks for new permissions never installs on its own. Before every update Pithyx takes a snapshot, and Back to with the version number returns to the previous version with its data as it was.

Details: Updates and rollback.

Does Pithyx send data anywhere?

No. Pithyx has no telemetry, no phone-home and no cloud account, and logs stay on the box. The only connections it makes on its own fetch the enabled app catalogs and their images, reach public time servers unless you set your own, and those of apps you allow the permission Internet.

Details: Privacy.

Why does my browser say the connection is not secure?

The box makes its own certificate, and your browser does not know who signed it yet. The connection is encrypted all the same. Continue to the page, then download the box’s root in Settings > Certificates and install it on the device; after that the warning is gone.

Details: Certificates.

Is the traffic to my box encrypted?

Yes, for every service but plain FTP. The web desktop and WebDAV use HTTPS, SFTP and FTP with TLS are encrypted, and SMB 3 is always signed, and encrypted when the client asks for it or an administrator requires it for a shared folder. Plain FTP is off unless an administrator allows it. Only the live system of the installer speaks plain HTTP.

Details: Security.

How do I enable SSH?

SSH is off by default and root stays locked. An administrator gives the user the right “Sign in over SSH with a shell” and switches on SSH logins in Settings > File services. SFTP for file transfer is a separate switch and gives no shell.

Details: SSH.

How do I report a security problem?

Privately, through a GitHub security advisory on pithyx/pithyx, not in a public issue. Include the version or commit, the steps to reproduce and the impact you expect.

Details: Reporting a vulnerability.

How do I write my own app?

Build a static web frontend with @pithyx/sdk, add a pithyx.json manifest and an icon.svg, and try it with pithyx dev, a mock desktop on your own computer. pithyx validate checks it and pithyx pack writes the .pithyxapp package that an administrator installs. There is no development mode on the box.

Details: Your first app.

Why does localStorage or a script from a CDN not work in my app?

Apps run in a sandboxed iframe without allow-same-origin, so localStorage and IndexedDB are of no use: store data with app.storage from the SDK. The Content Security Policy allows scripts only from the app itself, so bundle every script and skip inline <script>; inline styles are fine. pithyx dev serves the same policy, so you see a blocked request while developing.

Details: The sandbox.

Which app id should I use?

Your domain reversed plus the app name, three to five parts, for example com.mueller.chat or io.github.jan.chat. Parts use lowercase letters, digits and hyphens. org.pithyx.* is reserved for system apps and the official catalog, and the box refuses it from a package file.

Details: App ids.

How do I get my app into the Store?

Open a pull request with your app’s source to the community catalog pithyx/apps-community; the project reviews it, and CI builds, signs and publishes it. Or run your own catalog from the template pithyx/catalog-template, which administrators add in the Store as an unverified catalog. Every box can also install your .pithyxapp file directly.

Details: Publishing to a catalog.

Can I use the API from a script?

Yes, but there are no personal access tokens: a script signs in like the desktop with POST /api/auth/login, keeps the pithyx_session cookie and sends the header X-Pithyx-Request: 1 on every request that is not a GET, the login included. The daemon serves its OpenAPI document at /api/openapi.json.

Details: API.