Chibisafe: A Self-Hosted File Uploader in TypeScript

The problem Chibisafe solves for people who already run servers

Sending a large file usually means handing it to someone else's service, accepting their retention rules, their file size caps and their idea of what a link should look like. Chibisafe takes the opposite position: you run the instance, you own the storage, and the link you hand out points at your domain. The README describes it as a file uploader service written in TypeScript that accepts files, photos, documents, anything you imagine and gives you back a shareable link.

The audience is narrow and specific. It is for someone with a VPS or a home server who wants a pomf-style upload endpoint for a small group: a team sharing screenshots and recordings, a community that needs an invite-only drop box, or an individual who wants ShareX pointed at their own domain instead of a public host. The three modes named in the README (public, user accounts, invite-only) map onto those cases. If you are an end user who just wants to upload a file without running anything, this project is not aimed at you.

How uploads, storage and the dashboard fit together

The repository is a Yarn workspace monorepo. The package.json lists two workspaces, packages/backend and packages/next, with Turbo orchestrating build, dev and lint across them. The backend owns uploads, storage and the API; the Next.js package is the browser UI. That split matters when you deploy, because the Docker configuration is what makes the two appear as a single port.

Large files are chunked, which the README gives as the reason: to minimize network failure on big uploads. The backend also exposes API keys so scripts and other tools can post files without a browser session, and the README points at a built-in URL shortener, albums and folders with shareable links, and snippets. Storage is pluggable. The repository carries an S3 document at docs/s3.md and a minio/ directory, and there is a separate guide for network storage.

The part that shapes day-to-day operation is the dashboard. Instance settings such as the site name, rate limit, maximum file size and accepted extensions are edited from the UI rather than through environment files. That is convenient for a single operator, and it is also the thing to think about before you hand admin access to anyone: configuration lives in the application's database, not in a file you can diff in git.

Install Chibisafe with Docker and make a first upload

The README states plainly that Docker is the recommended path and links to a running-with-docker guide on chibisafe.app. The repository ships docker-compose.example.yml and a docker/ directory, so the compose file is the starting point rather than something you write from scratch. Copy the example and adjust it before bringing anything up.

One detail from the README is worth reading twice: the installation process creates an account named admin with the same password, and you are told to change it after the first login. Do that before the instance is reachable from the internet.

cp docker-compose.example.yml docker-compose.yml
docker compose up -d

After the containers start, the service listens on port 24424. The README gives that number in the v5 to v6 migration note, where it says v6 exposes a single port (now 24424) for you to reverse proxy into nginx, caddy or apache. The repository includes a Caddyfile, so Caddy is a supported front end if you would rather not write the proxy config yourself.

# point your reverse proxy at the app, then browse to it
# http://localhost:24424

Log in as admin, change the password, then open the dashboard and set the values you care about: instance name, maximum file size, rate limit, accepted extensions. Those are the controls the README lists as editable from the UI. Once they are set, upload a file through the web interface and confirm you get a shareable link back.

For programmatic use, create an API key from the interface and post to the instance with it. The README only says that users can create an API key to use the service programmatically; it does not document the endpoint paths, so read the API surface from the running instance or the source before you build against it.

Where Chibisafe stops being the right tool

The migration boundary is the sharpest limitation in the README. Moving from v5 to v6 means copying the uploads/ and database/ folders into the new instance and letting migrations run on startup. Moving from anything older than v5 to v6 is not possible, and the README recommends setting up a new instance instead. If you are sitting on a v4 deployment with years of files, there is no documented upgrade path to v6, only a fresh start and whatever you can move by hand.

There is also a privacy caveat that is easy to miss in a project whose feature list ends with no ads and no tracking. The same line adds an exception: IP logging of requests. If your threat model includes not recording who uploaded what, that is a behaviour to plan around.

Operationally, the dashboard-driven configuration cuts both ways. Settings that live in the UI are settings that are not in your deployment repository, which makes reproducing an instance from scratch harder than restoring a config file. And because the README does not document rollback, you should assume that once a migration has run against your database, going back to the previous version is not a supported manoeuvre. Take a copy of the database/ and uploads/ directories before you upgrade.

Chibisafe against Filebrowser and PicoShare

Filebrowser and PicoShare come up in the same searches, and the difference is what each one treats as the primary object. Filebrowser is a file manager: you browse a directory tree, and sharing is a feature layered on top of that tree. Chibisafe inverts it. The upload is the event, the shareable link is the product, and albums, tags and snippets are built around that link. If your users think in folders and permissions on existing storage, Filebrowser is closer to that mental model; if they think in terms of dropping a file and pasting a URL, Chibisafe is.

PicoShare sits at the other end of the complexity scale. It is deliberately small, and the trade is that you get less: no chunked uploads, no S3 backend, no user quotas, no URL shortener. Chibisafe carries all of those, and the cost is a heavier deployment with a database, a storage backend decision and a dashboard whose settings you have to keep track of. Choosing between them is mostly a question of whether you want an upload service or a minimal share link.

One thing Chibisafe does that neither of those two is described as doing in this material is client integration. The README lists ShareX support out of the box, an iOS shortcut for the share menu, and a browser extension. For someone whose workflow is screenshot, upload, paste link, that integration is the actual reason to pick it.

Maintenance, upgrades and what the MIT licence means here

The last push to the default branch was on 2026-05-27, which is recent, and the most recent release listed is v6.5.5 from 2025-07-05. The repository is not archived. The gap between the last release and the last push suggests work continues on master between tagged versions, though the release notes for anything after v6.5.5 are not in this material.

Upgrade cost is dominated by migrations. The README says that once chibisafe starts it will apply the necessary migrations automatically, which means the upgrade procedure is mostly about sequencing: back up uploads/ and database/, deploy the new version, let it migrate. There is no documented rollback, so the backup is the rollback. If you use S3 for storage, the uploads/ directory is not where your data lives, and your backup plan needs to reflect that instead.

The project is MIT licensed, which permits commercial and private use and modification. The README asks that if you fork or deploy your own instance you keep the GitHub logo or a link to the repository. That is a request, not a licence term, and nothing in the MIT grant obliges you to honour it. For a legal reading of your own obligations, talk to a lawyer rather than a README.

Editorial conclusion

Adopt Chibisafe if you need a self-hosted upload endpoint with its own accounts, quotas and API keys, and you are willing to run Docker and a reverse proxy in front of port 24424. Skip it if you are on a version older than v5, since the README states migration to v6 is not possible and a new instance is the only route. Before committing, change the default admin credentials, confirm which storage backend you will use, and check that ShareX or the browser extension covers the clients you actually upload from.

Frequently asked questions

Official sources

1. chibisafe/chibisafe on GitHub
2. License: MIT
3. Project website
4. README
5. Releases