# Pithyx > Pithyx is a free, self-hosted NAS and server OS with a web desktop: Debian 13, a C# daemon, a React desktop and apps as containers. It runs 100 percent locally, without telemetry or cloud accounts. Every page below is plain Markdown. Fetch only the page you need; for a whole area take its bundle, and for everything at once https://pithyx.org/llms-full.txt. Pages marked "Status: placeholder" or "Status: draft" are not checked against the code yet. ## Bundles - [llms-full.txt](https://pithyx.org/llms-full.txt): All pages of every area and the FAQ in one file. - [Getting started](https://pithyx.org/llms/getting-started.txt): What Pithyx is, the hardware it needs and the quickest way to a running box. - [Using Pithyx](https://pithyx.org/llms/user.txt): The web desktop for everyday users: windows, files, apps and the own account. - [Administration](https://pithyx.org/llms/admin.txt): Running a box: users and groups, permissions, storage, shared folders, file services, network, apps and backups. - [Install and update](https://pithyx.org/llms/install.txt): The USB stick, firmware and boot, the web installer, the first setup and system updates. - [Developers](https://pithyx.org/llms/developers.txt): How Pithyx is built: the daemon, the desktop and writing apps. - [Daemon](https://pithyx.org/llms/developers-daemon.txt): The C# daemon: architecture, API, errors, logging and tests. - [Desktop](https://pithyx.org/llms/developers-desktop.txt): The React web desktop: structure, translations, theming, window manager and budgets. - [App development](https://pithyx.org/llms/developers-apps.txt): Writing, building and publishing apps: pithyx dev, the manifest, backends and catalogs. - [SDK and CLI](https://pithyx.org/llms/sdk.txt): The npm packages @pithyx/sdk, @pithyx/ui and @pithyx/cli. - [Reference](https://pithyx.org/llms/reference.txt): Every error code, the REST API, the manifest and Compose rules, and a glossary. - [Project](https://pithyx.org/llms/project.txt): License, privacy, contributing, reporting security issues and the changelog. - [FAQ](https://pithyx.org/llms/faq.txt): Every frequently asked question with its answer. ## Pithyx - [Pithyx documentation](https://pithyx.org/docs.md): Everything about Pithyx, from installing a box to writing apps for it. - [Frequently asked questions](https://pithyx.org/docs/faq.md): Short answers to the questions people ask most about Pithyx, with a quick search. ## Getting started - [What is Pithyx](https://pithyx.org/docs/getting-started/what-is-pithyx.md): Pithyx in a few minutes: a NAS and server OS with a web desktop, running only on your own hardware. - [Hardware requirements](https://pithyx.org/docs/getting-started/requirements.md): The hardware Pithyx needs, the reference machine and what is not supported. - [Quick start](https://pithyx.org/docs/getting-started/quick-start.md): From the image to the first signed-in desktop in the fewest steps, with links to the details. ## Using Pithyx - [The desktop](https://pithyx.org/docs/user/desktop.md): Windows, the taskbar, desktop items, snapping, shortcuts and the layout each device remembers. - [Files](https://pithyx.org/docs/user/files.md): The Files app: browsing, uploading, copying and moving, the recycle bin, thumbnails and the viewer. - [Access files from other devices](https://pithyx.org/docs/user/file-access.md): Connecting to your shared folders from Windows, macOS, Linux and phones over SMB, SFTP, WebDAV and FTP. - [Using apps](https://pithyx.org/docs/user/apps.md): Opening apps, windows of the same app, and what an app may see of your data. - [Your account](https://pithyx.org/docs/user/account.md): Password, two-factor sign-in, how long you stay signed in, and personal settings such as language, theme and accent. ## Administration - [Storage and pools](https://pithyx.org/docs/admin/storage.md): Disks, ZFS pools, datasets, importing and growing a pool, and why some disks are refused. - [Shared folders](https://pithyx.org/docs/admin/shared-folders.md): Create, edit and delete shared folders, set who may use them, and how the recycle bin and restore points protect their files. - [Home folders](https://pithyx.org/docs/admin/home-folders.md): Every user gets a private home folder on the home pool; administrators pick the pool, set quotas and decide what happens to the home of a deleted user. - [Users and groups](https://pithyx.org/docs/admin/users-and-groups.md): Create users and groups, give them rights, deactivate or delete accounts, and what happens to their home folders. - [Permissions](https://pithyx.org/docs/admin/permissions.md): How rights are given to users and groups, how shared folder, protocol and app access combine, and when a change takes effect. - [File services](https://pithyx.org/docs/admin/file-services.md): Switch SMB, SFTP, WebDAV and FTP on or off, with their ports, defaults and limits. - [Network](https://pithyx.org/docs/admin/network.md): Network cards, static addresses, bonds, VLANs, DNS and the 60 second confirmation that protects you from locking yourself out. - [Security](https://pithyx.org/docs/admin/security.md): Transport, open ports, physical access, SSH, two-factor sign-in, the recovery key and what leaves the box. - [Apps and the Store](https://pithyx.org/docs/admin/apps-and-store.md): Install apps from catalogs or a file, choose the app pool, set update rules, and how backends run in Docker. - [Certificates](https://pithyx.org/docs/admin/certificates.md): HTTPS on 7484, the box as its own certificate authority, trusting it on your devices, certificates for other devices and a certificate of your own. - [Reverse proxy](https://pithyx.org/docs/admin/reverse-proxy.md): Proxy hosts and redirect hosts on ports 443 and 80 by domain, with certificates, access rules and the Pithyx sign-in, and TCP and UDP streams. - [Backup and restore](https://pithyx.org/docs/admin/backup.md): Save the configuration of the box in an encrypted file and restore it, and what the backup does not cover. - [Logs and monitoring](https://pithyx.org/docs/admin/logs-and-monitoring.md): The Log Center, the Resource Monitor and notifications: what they show, how long data is kept and what they cost. ## Install and update - [Write the USB stick](https://pithyx.org/docs/install/usb-stick.md): The image file, how to check it and how to write it to a USB stick on Windows, macOS and Linux. - [Firmware and boot](https://pithyx.org/docs/install/firmware-and-boot.md): UEFI settings, why Secure Boot must be off, and the boot menu of the stick and the installed system. - [The web installer](https://pithyx.org/docs/install/installer.md): Each step of the installer in the browser: checks, name and region, network, system disk or mirror, administrator account and the restart. - [First setup](https://pithyx.org/docs/install/first-setup.md): The owner account, the recovery key, the first pool and adding more users after the installation. - [System updates](https://pithyx.org/docs/install/updates.md): Update channels, how an update is checked and applied, and what happens when one fails. - [Switching the update source (forks)](https://pithyx.org/docs/install/update-source.md): How a box follows the updates of a fork instead of the Pithyx project, what that means, the way back, and what a fork has to publish. - [Recovery and reinstall](https://pithyx.org/docs/install/recovery.md): Forgotten passwords, a failed system disk and reinstalling Pithyx while keeping the data on the pools. ## Daemon - [Daemon architecture](https://pithyx.org/docs/developers/daemon/architecture.md): The only privileged process: its modules, the command runner, storage backends and paths. - [API](https://pithyx.org/docs/developers/daemon/api.md): The REST and WebSocket API, authentication, topics and the generated client. - [Errors, tracing and logging](https://pithyx.org/docs/developers/daemon/errors-and-logging.md): Error codes and problem details, request ids, structured logs and masking secrets. - [Developing the daemon](https://pithyx.org/docs/developers/daemon/development.md): Building, running in simulation, tests and the integration suites that need root. ## Desktop - [Desktop architecture](https://pithyx.org/docs/developers/desktop/architecture.md): The React web desktop: shell, window manager, core apps and how it talks to the daemon. - [Translations](https://pithyx.org/docs/developers/desktop/i18n.md): Keys, ICU messages, adding a language and the rules for German. - [Theming and design tokens](https://pithyx.org/docs/developers/desktop/theming.md): The token file, light and dark, accent presets and fonts. - [Performance and budgets](https://pithyx.org/docs/developers/desktop/performance.md): Bundle and timing budgets, the perf gate and how to stay inside them. ## App development - [Apps overview](https://pithyx.org/docs/developers/apps/overview.md): What a Pithyx app is: a static frontend, an optional backend, a manifest and a package. - [Your first app](https://pithyx.org/docs/developers/apps/first-app.md): From a template to a running app with pithyx dev, then a package to install. - [The manifest](https://pithyx.org/docs/developers/apps/manifest.md): Every field of pithyx.json: identity, windows, permissions, backend and lifecycle. - [Backends](https://pithyx.org/docs/developers/apps/backend.md): Containers behind the proxy: the Compose subset, endpoints, users, storage and network. - [Publishing to a catalog](https://pithyx.org/docs/developers/apps/publishing.md): Getting an app into the official or community catalog, or running an own catalog. ## SDK and CLI - [Files and app storage](https://pithyx.org/docs/sdk/guides/files-and-storage.md): Keep small values per user with app.storage, and read and write files in storage requests and shared folders. - [SDK overview](https://pithyx.org/docs/sdk/overview.md): The three npm packages, their versions and how they fit together. - [@pithyx/sdk](https://pithyx.org/docs/sdk/sdk.md): The app API: identity, files, storage, the backend, events, logs and permissions. - [Calling the backend](https://pithyx.org/docs/sdk/guides/backend.md): Reach the app backend with app.backend: fetch, token URLs, WebSockets with tickets, and the X-Pithyx-User headers on the backend side. - [@pithyx/ui](https://pithyx.org/docs/sdk/ui.md): The desktop's React components and tokens, so third-party apps look native. - [Events, window context and launch arguments](https://pithyx.org/docs/sdk/guides/events-and-context.md): Read app.context, follow the desktop events, handle launch arguments and notification clicks, and save window state. - [@pithyx/cli](https://pithyx.org/docs/sdk/cli.md): The pithyx command: validate, lock, build, pack, dev and the catalog commands. - [Permissions and permissionsChange](https://pithyx.org/docs/sdk/guides/permissions.md): Declare permissions, check context.permissions, handle app.permission.denied and follow permissionsChange when an administrator changes them. - [Languages and theming in an app](https://pithyx.org/docs/sdk/guides/i18n-and-theming.md): Show texts in the user language with @pithyx/sdk/i18n, format dates and sizes with app.format, and follow the desktop theme with CSS properties. - [Logging and errors](https://pithyx.org/docs/sdk/guides/logging-and-errors.md): Write to the Log Center with app.log, handle PithyxError codes, retry what may pass and show errors in the user language. - [Testing with pithyx dev and the mock desktop](https://pithyx.org/docs/sdk/guides/testing.md): Run an app in the mock desktop of pithyx dev, change user, theme, permissions and events from its panel, and unit-test app code against a fake desktop. ## Reference - [pithyx command](https://pithyx.org/docs/reference/cli.md): Reference of the pithyx command of @pithyx/cli: usage, commands, global options, exit codes, environment variables and output. - [Error codes](https://pithyx.org/docs/reference/errors.md): Every error code the daemon and the SDK return, with its message, generated from the product's translations. - [pithyx validate](https://pithyx.org/docs/reference/cli/validate.md): pithyx validate checks an app project as the box checks the package built from it, and writes nothing. - [REST API reference](https://pithyx.org/docs/reference/api.md): Every endpoint of the daemon's REST API, one page per area, generated from its OpenAPI document. - [pithyx lock](https://pithyx.org/docs/reference/cli/lock.md): pithyx lock resolves the images of the backend Compose file from their registries and writes backend/images.lock.json. - [REST API: App API](https://pithyx.org/docs/reference/api/app-api.md): The 27 operations of the area App API, with parameters, bodies and responses. - [Compose rules](https://pithyx.org/docs/reference/compose-rules.md): The Compose subset an app backend may use, generated from compose.v1.rules.json: allowed keys, value types, limits, patterns and refused keys. - [Manifest schema](https://pithyx.org/docs/reference/manifest-schema.md): Every field of pithyx.json with its type, whether it is required, its default, its allowed values and its description, generated from the JSON Schema. - [pithyx build](https://pithyx.org/docs/reference/cli/build.md): pithyx build builds the backend services of compose.dev.yaml with Docker and pins compose.yaml and the images lock to them. - [REST API: Apps](https://pithyx.org/docs/reference/api/apps.md): The 17 operations of the area Apps, with parameters, bodies and responses. - [Glossary](https://pithyx.org/docs/reference/glossary.md): The words Pithyx uses and what each one means. - [pithyx pack](https://pithyx.org/docs/reference/cli/pack.md): pithyx pack validates an app project and writes its deterministic package -.pithyxapp. - [REST API: Auth](https://pithyx.org/docs/reference/api/auth.md): The 8 operations of the area Auth, with parameters, bodies and responses. - [pithyx dev](https://pithyx.org/docs/reference/cli/dev.md): pithyx dev runs the mock desktop with the app in the box sandbox and a proxy to its backend, for development without a box. - [REST API: Desktop](https://pithyx.org/docs/reference/api/desktop.md): The 10 operations of the area Desktop, with parameters, bodies and responses. - [pithyx catalog check](https://pithyx.org/docs/reference/cli/catalog-check.md): pithyx catalog check runs the pull request rules of a catalog repository on the changes since a base commit. - [REST API: Files](https://pithyx.org/docs/reference/api/files.md): The 15 operations of the area Files, with parameters, bodies and responses. - [pithyx catalog pending](https://pithyx.org/docs/reference/cli/catalog-pending.md): pithyx catalog pending prints, as JSON, the app versions of a catalog repository that catalog-next does not list yet. - [REST API: FileServices](https://pithyx.org/docs/reference/api/fileservices.md): The 2 operations of the area FileServices, with parameters, bodies and responses. - [pithyx catalog index](https://pithyx.org/docs/reference/cli/catalog-index.md): pithyx catalog index adds built packages, or promotes the versions of another branch, and writes index.json with the next sequence. - [REST API: Installer](https://pithyx.org/docs/reference/api/installer.md): The 8 operations of the area Installer, with parameters, bodies and responses. - [pithyx catalog sign](https://pithyx.org/docs/reference/cli/catalog-sign.md): pithyx catalog sign signs index.json of a catalog branch with the Ed25519 key in PITHYX_SIGNING_KEY. - [REST API: Jobs](https://pithyx.org/docs/reference/api/jobs.md): The 3 operations of the area Jobs, with parameters, bodies and responses. - [pithyx catalog verify](https://pithyx.org/docs/reference/cli/catalog-verify.md): pithyx catalog verify checks a catalog branch as a box does: the signature against given keys, the index and every file. - [REST API: Logs](https://pithyx.org/docs/reference/api/logs.md): The 6 operations of the area Logs, with parameters, bodies and responses. - [SDK and UI API reference](https://pithyx.org/docs/reference/sdk.md): The generated API reference of @pithyx/sdk and @pithyx/ui, one page per module and per component. - [Findings](https://pithyx.org/docs/reference/cli/findings.md): Every finding the pithyx command can report, with its level and message, generated from the CLI and the box translations. - [REST API: Notifications](https://pithyx.org/docs/reference/api/notifications.md): The 5 operations of the area Notifications, with parameters, bodies and responses. - [SDK: app and connection](https://pithyx.org/docs/reference/sdk/app.md): connect(), the PithyxApp object with every method, the formatters, the transports and the manifest types. - [REST API: Permissions](https://pithyx.org/docs/reference/api/permissions.md): The 5 operations of the area Permissions, with parameters, bodies and responses. - [SDK: files and storage](https://pithyx.org/docs/reference/sdk/files.md): The types of the file API: handed-over files, shares, folder pages, jobs, the recycle bin, versions and storage requests. - [REST API: Setup](https://pithyx.org/docs/reference/api/setup.md): The 2 operations of the area Setup, with parameters, bodies and responses. - [SDK: backend](https://pithyx.org/docs/reference/sdk/backend.md): The types around app.backend: status, tokens, tickets and the backend part of the manifest. - [REST API: Shares](https://pithyx.org/docs/reference/api/shares.md): The 9 operations of the area Shares, with parameters, bodies and responses. - [SDK: events and context](https://pithyx.org/docs/reference/sdk/events-context.md): app.context, every event of app.on and every question of app.answer, with their data. - [REST API: Storage](https://pithyx.org/docs/reference/api/storage.md): The 19 operations of the area Storage, with parameters, bodies and responses. - [SDK: i18n](https://pithyx.org/docs/reference/sdk/i18n.md): @pithyx/sdk/i18n: createI18n for texts as ICU MessageFormat JSON in the user language. - [REST API: Store](https://pithyx.org/docs/reference/api/store.md): The 12 operations of the area Store, with parameters, bodies and responses. - [SDK: theme](https://pithyx.org/docs/reference/sdk/theme.md): The public --pithyx-* CSS custom properties and how the SDK applies the desktop theme. - [REST API: System](https://pithyx.org/docs/reference/api/system.md): The 46 operations of the area System, with parameters, bodies and responses. - [SDK: host](https://pithyx.org/docs/reference/sdk/host.md): @pithyx/sdk/host: the desktop's side of the protocol, which serves an app window. - [REST API: Users](https://pithyx.org/docs/reference/api/users.md): The 15 operations of the area Users, with parameters, bodies and responses. - [SDK: errors](https://pithyx.org/docs/reference/sdk/errors.md): PithyxError, the problem shape and the SDK transport error codes. - [REST API: schemas](https://pithyx.org/docs/reference/api/schemas.md): Every request and response schema of the REST API with its fields. - [UI: Button](https://pithyx.org/docs/reference/sdk/ui/button.md): Button and IconButton, in the four variants of the desktop. - [UI: Checkbox](https://pithyx.org/docs/reference/sdk/ui/checkbox.md): A checkbox with its label. - [UI: Switch](https://pithyx.org/docs/reference/sdk/ui/switch.md): An on and off switch for settings that apply at once. - [UI: ProgressBar](https://pithyx.org/docs/reference/sdk/ui/progress-bar.md): A labelled progress bar with its value as text. - [UI: Badge](https://pithyx.org/docs/reference/sdk/ui/badge.md): A small count or status next to an item. - [UI: Dialog](https://pithyx.org/docs/reference/sdk/ui/dialog.md): A modal dialog with a title, content and a row of actions. - [UI: Menu](https://pithyx.org/docs/reference/sdk/ui/menu.md): Menu, its items, separators, popover and trigger, and useDeliberatePress for destructive items. - [UI: ContextMenuPopover](https://pithyx.org/docs/reference/sdk/ui/context-menu.md): The popover of a context menu, opened at a point of the viewport. - [UI: TextField](https://pithyx.org/docs/reference/sdk/ui/text-field.md): A labelled text input with an optional description and error message. - [UI: PasswordField](https://pithyx.org/docs/reference/sdk/ui/password-field.md): A password input with a button that shows or hides the password. - [UI: SearchField](https://pithyx.org/docs/reference/sdk/ui/search-field.md): A search input whose label is only announced. - [UI: OtpField](https://pithyx.org/docs/reference/sdk/ui/otp-field.md): An input for the six-digit code of an authenticator app. - [UI: Tooltip](https://pithyx.org/docs/reference/sdk/ui/tooltip.md): A short text next to its trigger, with TooltipTrigger. - [UI: UiProvider](https://pithyx.org/docs/reference/sdk/ui/ui-provider.md): Sets the locale of the components and their own texts. - [UI: Helpers](https://pithyx.org/docs/reference/sdk/ui/helpers.md): cx and the texts the components show on their own. - [UI: native](https://pithyx.org/docs/reference/sdk/ui/native.md): @pithyx/ui/native: the class names of the components for native HTML elements, without React Aria. - [UI: tokens](https://pithyx.org/docs/reference/sdk/ui/tokens.md): Every design token of @pithyx/ui/tokens.css with its value, the accent presets and the media overrides. ## Project - [License](https://pithyx.org/docs/project/license.md): AGPL-3.0 for the system with an attribution term for forks, MIT for the npm packages, and the third-party notices. - [Privacy](https://pithyx.org/docs/project/privacy.md): Pithyx and this website collect nothing: no telemetry, no accounts, no trackers. - [Contributing](https://pithyx.org/docs/project/contributing.md): How to report bugs, propose changes and send pull requests. - [Reporting a vulnerability](https://pithyx.org/docs/project/security.md): How to report a security issue privately and what happens next. - [Changelog](https://pithyx.org/docs/project/changelog.md): What changed in each release. - [Releasing](https://pithyx.org/docs/project/releasing.md): The release tool tools/release/pithyx-release: building the ISO and update files, signing them and publishing the npm packages. ## Optional - [Deutsch](https://pithyx.org/de/llms.txt): The same docs in German.