29 guides · synced daily from GitHub
Penombre docs
A self-hosted drive, in the browser, on your desktop and on your phone. SQLite by default: one container, one volume, no database server to babysit.
Introduction
A self-hosted drive. All the convenience of cloud storage, on hardware you own, with a bill of exactly zero.
Contributing
Unit tests preload test.setup.ts (see bunfig.toml), which mocks $app//#lib/server/ and the Drizzle db object; they need no database or Redis. bunfig.toml also sets rerunEach = 3 to catch flaky tests, and enforces coverage thresholds.
Getting started
Install, first boot, first look.
Getting Started
Spin up a Penombre instance in minutes with Docker Compose.
Showcase
Every screenshot below is generated by driving a real instance with Playwright (bun run screenshots, or mise run media for these and the feature graphics with the desktop and mobile apps) against a band's drive: real, freely licensed photos, footage and music (credited in tests/e2e/fixtures/CREDITS.md), a song in three takes, a document, a sheet and a deck written through the API, and one file of every other kind — a PDF, some code, a 3D model and an archive. There is no demo instance to keep alive, and no hand-retouched marketing shot: if a screen stops rendering, the run fails rather than publishing it.
Simple Mode
Run Penombre as a bare shared file browser instead of a multi-user drive.
Self-hosting
Configure, deploy and put it behind HTTPS.
Environment variables
Configure your Penombre instance with environment variables.
Deployment
Deploy Penombre to production with Docker.
Reverse Proxy
Expose Penombre behind a reverse proxy with HTTPS.
Storage
Where Penombre keeps your files.
Encryption
Penombre can seal file bytes at rest with a key you hold, but start with disk-level encryption on DATADIR: for a stolen or decommissioned drive it covers strictly more, because it also covers the database. Application-level encryption then adds one thing disk encryption cannot: file bytes that stay sealed when they are copied off the server.
Mounted volumes
A volume is a directory mounted alongside the main drive. It appears in the sidebar as its own entry, is browsable and searchable like any other folder, and is reconciled with what is actually on disk.
Worker
Penombre offloads CPU- and I/O-heavy byte work to a small Go process rather than doing it inline in the app's request handlers.
Troubleshooting
Solutions to common Penombre issues.
Using Penombre
Files, media, documents and sharing.
Uploads
Uploading is deliberately boring: pick files, they land in the folder you are browsing. Two things about it are worth knowing.
WebDAV and sync
Every Penombre tree is served over WebDAV, so the file manager you already use can mount it and rclone can keep a local folder in sync with it. Penombre Sync, the desktop tray app, sets that up for you and runs it in the background.
Desktop sync
Penombre Sync is a small tray app for macOS, Linux and Windows that keeps folders on your computer in two-way sync with Penombre. It is built on WebDAV and rclone: it does the setup that page describes for you, then runs the sync on its own.
AI assistants (MCP)
Penombre speaks the Model Context Protocol, so an AI assistant can browse, search, read and write your files, and move videos, photos and code in and out to work on them. The server is built in: there is nothing to install or turn on.
Mobile app
The Penombre app for Android and iOS is at an early stage: it signs in, browses your drive and shared drives, shows pictures, plays music and video, and opens the rest in the instance's own web interface. Google Play lists it for testers only for now; everyone else installs it from GitHub.
Media and notes
Images, video and audio get more than a download link.
Documents, sheets and presentations
Penombre creates and edits three kinds of document in the browser, from the New button in the sidebar.
Signatures
Ask people to sign a document, with or without an account on the instance. Each signer gets a personal link, signs on a page that works on a phone, and once everyone has signed, everybody gets the same signed PDF with a certificate and an audit trail.
File versioning
Keep the earlier bytes of a file instead of final-final-really.wav.
Sharing
Penombre shares a file or folder two ways, and the Share dialog has a tab for each:
Shared drives
A shared drive belongs to a group instead of a person. Everyone on it opens the same tree, uploads into the same folders, and sees the same trash — unlike sharing, where an item stays in its owner's drive and other people are given a door to it.
Notifications
The bell in the header tells you when someone else did something to your things. It is deliberately narrow: only events involving another person appear, so your own uploads, renames and deletions never ring it. Those are in your activity log instead.
FAQ
Settings → General on the web, or Settings → General → Language in the mobile app. Penombre speaks English, French, German, Spanish, Italian, Dutch, Swedish, Finnish, Polish, Russian, Japanese, Korean and Chinese, each listed in its own name.
Administration
Accounts, sign-in methods and instance settings.
Admin panel
Accounts with the admin role get an extra section at /admin, reachable from the user menu. It is hidden entirely when auth is bypassed — nobody signs in under bypass, so the shared owner being an admin is an accident of seeding rather than a person who should reach user management.
Authentication
Configure authentication methods for your Penombre instance. Penombre supports multiple authentication methods powered by Better Auth.
Internals
How the code fits together.