# Misskey: self-hosting an ActivityPub microblog platform from the Misskey repository

> Misskey is an AGPL-3.0 federated microblog server written in TypeScript and shipped as a pnpm monorepo. This is what the repository actually contains, how the install path works, and where self-hosting stops making sense.

**misskey-dev/misskey** — 🌎 A completely free and open interplanetary-microblogging platform 🚀

- Repository: https://github.com/misskey-dev/misskey
- Website: https://misskey-hub.net/
- Stars: 11,335 · Forks: 1,628
- Language: TypeScript
- License: AGPL-3.0
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/misskey-dev-misskey

## What Misskey solves, and for whom

Misskey is a server, not a client. The README describes it as "an open source, federated social media platform that's free forever" and links to two different audiences in its own badges: people who want to find an existing instance, and people who want to create one. Those are separate products in practice. The first group never touches this repository. The second group inherits an ActivityPub node, a database, a job queue and a web frontend to keep alive.

The people this repository is genuinely for are administrators who want a microblogging server they can extend, and developers who want to build against a documented HTTP API. Misskey's posts are not limited to short text: the repository ships packages for a Reversi game and a bubble game alongside the backend, which tells you the frontend is meant to host more than a timeline. If you want a plain, minimal ActivityPub server you can read in an afternoon, this is a large codebase and the monorepo layout makes that clear before you install anything.

## The pnpm workspace behind a Misskey instance

The root package.json declares the project private and lists its workspaces explicitly: packages/backend, packages/frontend, packages/frontend-shared, packages/frontend-embed, packages/frontend-builder, packages/i18n, packages/icons-subsetter, packages/sw, packages/misskey-js, packages/misskey-js/generator, packages/misskey-reversi and packages/misskey-bubble-game. The backend is the ActivityPub and API server; the frontend packages are the web client and its embeddable variant; misskey-js is the client library that other software consumes, generated from the backend's API description.

That generation step is the part worth understanding. The script build-misskey-js-with-types runs the backend build, then has the backend emit api.json, copies it into packages/misskey-js/generator/api.json, regenerates the client code, builds misskey-js, and finally builds the API documentation from the same source. The API surface is therefore derived from the server rather than maintained separately, which is why the repository keeps a generator workspace at all.

The package manager is pinned: packageManager is pnpm@11.25.0, and the Dockerfile reads that field out of package.json and installs the matching pnpm globally before running pnpm i --frozen-lockfile. The version is not a suggestion. The Docker build also installs build-essential in a Debian-based Node image (NODE_VERSION defaults to 26.4.0-trixie), which implies native compilation during install.

## Installing Misskey: build, migrate, start

The README does not carry install steps; it points to the admin install guides under misskey-hub.net/docs/for-admin/install/guides/. What the repository itself gives you is the script set. After cloning and installing dependencies with pnpm, the root scripts chain a pre-build step, a recursive workspace build, and an asset build. The frontend has to be compiled before the server can serve it.

```bash
pnpm install
pnpm build
```

The build script is defined as build-pre, then pnpm -r build across the workspaces, then build-assets. Expect this to be the slow part of a first install; it compiles the backend TypeScript and bundles the frontend.

Database setup is a separate step. The root package.json defines migrate as a pass-through into packages/backend, and init as an alias for it, so a fresh instance is initialised by running migrations rather than by importing a schema dump.

```bash
pnpm init
```

Starting the server means compiling the runtime config first, then executing the built entry point. The start script does both in one line.

```bash
pnpm start
```

That script runs pnpm compile-config inside packages/backend and then node ./built/entry.js. If the config has not been compiled, the entry point will not find it, so running node ./built/entry.js directly is not equivalent. For a container deployment, the repository ships compose_example.yml and a Dockerfile; the Dockerfile installs pnpm from the packageManager field and runs the frozen-lockfile install, so the image build follows the same pinning as a manual install.

## Where a self-hosted Misskey instance breaks down

The repository is honest about its operational shape without saying so directly. A Misskey instance is not a static site: it needs PostgreSQL for state, Redis for the queue and cache, and a reverse proxy in front of the Node process. None of that is optional in the architecture the scripts assume, and none of it is described in the README, which delegates the whole subject to the external documentation site.

Federation is the second constraint. An ActivityPub server has to accept inbound requests from arbitrary remote servers and deliver outbound ones, which means a public HTTPS endpoint, a domain you intend to keep, and a moderation posture. A Misskey instance that federates with the wider network receives content from servers you did not choose. The repository ships SECURITY.md and a CODE_OF_CONDUCT.md, but those govern the project, not your instance's moderation policy.

The third case is simpler: if you want to read and post on the fediverse, hosting is the wrong tool. The README's first badge points at the instance list for exactly that reason. Running this codebase to get an account is like running a mail server to get an email address.

## Misskey compared with Mastodon

The two are both ActivityPub microblog servers, so they interoperate, but the codebases make different bets. Mastodon is a Ruby on Rails application with a server-rendered web client. Misskey is a TypeScript monorepo with a separately built frontend, a generated API client, and a plugin-friendly client that also ships small games. The practical difference for an administrator is the runtime: Ruby and Sidekiq on one side, Node.js and a pnpm workspace build on the other.

The difference for a developer is the API. Misskey generates misskey-js from the backend's own API description, so the client library and the server cannot drift without the build noticing. That is a stronger guarantee than a hand-written client, and it is also more machinery: contributing to the API means running the generator, not editing a client file.

If your priority is the smallest possible moving-parts count, neither is minimal, but Mastodon's single-language stack is easier to reason about at 2 a.m. If your priority is a typed API and a frontend you can restyle, Misskey's layout is the more direct fit.

## Licence and the cost of staying current

Misskey is licensed AGPL-3.0, and the repository carries both LICENSE and COPYING at the top level. The practical consequence, stated as a fact about the licence rather than as advice: if you modify Misskey and let users interact with it over a network, the AGPL's source-disclosure condition applies to your modified version. Running an unmodified instance and theming it through configuration is a different situation from patching the backend. If you plan to fork the frontend, read the licence text in LICENSE before you start, and take legal advice if the boundary matters to your organisation.

Upgrade cost is driven by the release cadence. The most recent releases listed are 2026.9.0 on 2026-09-06, preceded by 2026.9.0-alpha.0 on 2026-09-04 and 2026.8.0-alpha.0 on 2026-08-15. Version numbers are calendar-based, and the repository maintains a CHANGELOG.md plus a ROADMAP.md. The last push to the default branch, develop, was on 2026-09-21. Upgrades are not drop-in: migrations run through pnpm migrate, and the backend compiles its config at start, so a configuration key that changed between releases surfaces at startup rather than at build time. The repository also carries a revert script, which the README does not document, so do not assume a rollback path is described anywhere in the install material.

## Conclusion

Adopt Misskey if you want a federated microblog server you control and you are prepared to run Node.js, PostgreSQL, Redis and a reverse proxy yourself, following the install guides at misskey-hub.net. Do not adopt it if you only want an account: the README points account seekers at the instance list, not at a download. Before committing, verify which Node.js and PostgreSQL versions the current release notes require, and confirm that the AGPL-3.0 source-disclosure obligation fits how you plan to modify the frontend.

## FAQ

### What is a Misskey?

Misskey is an open source, federated social media platform, described in the README as free forever. It is a server you host, not an app you download, and it speaks ActivityPub so it can exchange posts with other fediverse software.

### how to use misskey

The README does not contain install steps; it links to the admin install guides at misskey-hub.net/docs/for-admin/install/guides/. The repository provides the script path instead: install with pnpm, run pnpm build, initialise the database with pnpm init, then start with pnpm start.

### is misskey mastodon

No. Both are ActivityPub microblog servers and they federate with each other, but Misskey is a TypeScript pnpm monorepo with a separately built frontend and a generated API client, while Mastodon is a Ruby on Rails application with a server-rendered client.

### Is Misskey safe to use?

The repository ships a SECURITY.md and an AGPL-3.0 licence, but safety in practice depends on the instance you join rather than on the codebase. The README's instance list is the starting point for choosing one, and the project does not vouch for the operators listed there.

### is misskey japan only

Nothing in the repository restricts registration by region. The project ships a locales directory and uses Crowdin for translation, so the interface is available in many languages; instance-level policies are set by each operator, not by the code.

### What is the Misskey app?

The repository is the server and web client, not a mobile app: the README's badges point to finding an instance, creating one, contributing, the Discord community and Patreon. Anything presented as a Misskey app elsewhere is not distributed from this repository.

## Sources

- [License: AGPL-3.0](https://github.com/misskey-dev/misskey/blob/develop/LICENSE)
- [misskey-dev/misskey on GitHub](https://github.com/misskey-dev/misskey)
- [Project website](https://misskey-hub.net/)
- [README](https://github.com/misskey-dev/misskey/blob/develop/README.md)
- [Releases](https://github.com/misskey-dev/misskey/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/misskey-dev-misskey