# Nametag: a self-hosted personal relationship manager with a graph view

> Nametag is a self-hostable personal relationships manager that tracks people, birthdays, contact details and how people are connected, and draws the network as an interactive force directed graph, with CardDAV sync, a REST API, reminders and a journal. It suits someone who wants their contact data on their own server, and its AGPL-3.0 licence and active development notice are both things to weigh before you depend on it.

**mattogodoy/nametag** — A simple, yet effective Personal Relationship Manager

- Repository: https://github.com/mattogodoy/nametag
- Stars: 1,099 · Forks: 61
- Language: TypeScript
- License: AGPL-3.0
- Published: 2026-10-19 · Updated: 2026-10-19 · Language: en
- Canonical page: https://hysenlabs.com/projects/mattogodoy-nametag

## A contact book that draws its own connections

Nametag is a personal relationships manager, and the README is careful about what that means. It helps you remember the people in your life and how they are connected. The feature list is a complete inventory of the domain. People are tracked with flexible attributes, meaning name, birthday, important dates, photos and user defined custom fields. Relationships between people are mapped with custom relationship types, so the connection itself is a record with a type you choose rather than a hard coded spouse or colleague field. Contacts go into custom groups. There is an interactive map view with geocoded addresses and clustered markers, a journal for logging interactions and notes over time, reminders for important dates and for staying in touch, and a set of bulk operations for delete, group assignment and relationships.

The distinctive surface is the network view. The dashboard shows a force directed graph of your relationships, and the README calls it an interactive force directed graph, which is implemented with the d3 packages in the dependency list, d3-force for the layout, d3-drag, d3-zoom, d3-selection and d3-transition for the interaction. The map view uses maplibre-gl rather than a hosted map provider, and there is a global fuzzy search with accent insensitive matching, so a name typed without diacritics still matches.

The application pages are the dashboard, the people list, groups, the journal and relationships, each with a dark and a light theme, and the whole thing is mobile responsive and installable as a PWA. Nine languages are listed as supported: English, Spanish, Japanese, Norwegian, German, Chinese, Italian, Russian and Dutch, and the roadmap marks additional translations as needing help. The project is AGPL-3.0 licensed, and the repository carries a SECURITY.md, a CHANGELOG.md, a CODE_OF_CONDUCT.md, a CLAUDE.md and an.impeccable.md file, plus a docs/ directory and a tests/ directory with Playwright and Vitest configurations at the top level.

## Self-hosting with compose, Postgres and optional Redis

The self-hosted quick start is short, and the composition file does the work.

```bash
mkdir nametag && cd nametag
# add a docker-compose.yml and .env file (see the installation guide)
docker compose up -d
```

Then you visit http://localhost:3000. The compose file in the repository defines three services. The db service is postgres:16-alpine with a named volume for the data, credentials from the DB_USER, DB_PASSWORD and DB_NAME variables, a healthcheck running pg_isready, and the port published with a default of 5432. The redis service is redis:7-alpine, and the comment in the file marks it as optional with instructions to comment it out to disable it, and its command requires a REDIS_PASSWORD value so the container refuses to start without one. The app service pulls the published image ghcr.io/mattogodoy/nametag:latest, publishes port 3000, and carries a DataDog log label pointing at the nodejs service.

The proxy comment in the compose file is the part worth reading twice. The TRUSTED_PROXY_HEADER and TRUSTED_PROXY_COUNT settings only protect rate limiting if the port cannot be reached except through your reverse proxy, and publishing the port on all interfaces, as the file does, lets anyone who can reach the host bypass the proxy and the header it sets. The file recommends a reverse proxy for any instance reachable by others. The Docker image is a three stage build on node:20-alpine. The dependency stage installs everything including dev dependencies, the builder stage generates the Prisma client and builds the Next.js application, and the runner stage installs tzdata, sets the production environment, and creates a non-root user with uid 1001 before copying the built application. The build stage sets placeholder environment values including a dummy DATABASE_URL, with a comment explaining that the real values are supplied at runtime and that they exist so the environment validation in lib/env.ts does not fail during the build.

## Sync, import and export, and the API surface

The interop story is unusually broad for a personal tool. CardDAV sync is supported against Google Contacts, iCloud, Outlook and Nextcloud, and the README's done list records it as implemented through a specific pull request. There is vCard and JSON import and export, so you are not locked into one directory format. Duplicate detection and contact merging is implemented, which is the feature you need most after the first year of using any contact manager. The messaging app quick links cover WhatsApp, Signal, Telegram and more, which turns a stored phone number into a one click action.

There is a REST API with OpenAPI documentation and token authentication, and the done list records it as implemented for third party integrations. Alongside that there is OIDC and SSO authentication support, and a done item for implementing OIDC with a linked issue. Email is handled through nodemailer for SMTP and resend for a hosted provider, and the Dockerfile sets a RESEND_API_KEY placeholder, so both paths exist.

The internals behind the features are visible in the dependency list. Prisma 7 with the pg adapter and the pg driver is the data layer, next-auth 5 in beta is the session layer, bcryptjs handles password hashing, and minisearch provides the fuzzy search. For photos, sharp does the processing, heic-convert handles HEIC input, and react-easy-crop gives the cropping UI, with configurable photo compression listed as a completed item. Redis is reached through ioredis, pino handles logging, and isomorphic-dompurify sanitises markup. The image pipeline is worth noting because photo storage is where a self-hosted contacts app actually grows, and the project has already made a decision about compression and format support.

## The active development notice is the most important line in the README

The first thing in the README is a warning, and it should shape your evaluation. Nametag is under active development and may introduce breaking changes between releases, and the README asks you to read the release notes carefully before updating to ensure a smooth upgrade process. That is a project being honest about its own pace rather than hiding it, and the release cadence backs it up. v0.62.0 landed on 2026-09-01, v0.63.0 on 2026-09-21 and v0.64.0 on 2026-10-15, three releases in about six weeks, and the last push to master was on 2026-10-15, the same day as the newest tag.

The reason to keep that in mind is the data model. A personal relationships manager accumulates records you cannot recreate easily, birthdays, photos, the notes you wrote about someone, the journal entries, and a schema change that drops a column or changes how a custom attribute is stored is not a trivial inconvenience. The project does ship a CHANGELOG.md and a .auto-changelog configuration and a release-please configuration with a manifest, so the changes are recorded, but the responsibility for reading them before an upgrade is on the operator.

The version number being in the 0.x range is the second signal. A 0.x version carries no compatibility promise by convention, and the notice is the author telling you so in advance. The good news is that the project is not idle. The roadmap shows a long done list with pull request numbers, including CardDAV, the third party API, photos, custom template titles for important dates, journaling, OIDC, the map, full text fuzzy search, photo compression, HEIC support, messaging quick links and the installable PWA, and the to do list carries a HELP NEEDED tag on the mobile app and on more translations, with an Immich integration, notification support and multi-user groups still open as issues.

## Where Nametag is the wrong tool

Four cases argue against it. The first is a shared household address book. Multi-user groups is an open roadmap item, and until it lands, two people in one family cannot both maintain the same contacts with per user permissions, which is the normal expectation for a family tool. The second is a stable schema. If your requirement includes being able to restore a backup into a newer version without a migration script, the version cadence and the breaking change notice mean you are signing up for upgrade work, and the fact that the data holds your own photos, notes and journal means a failed upgrade is a personal loss rather than an inconvenience. The third is a hosted service. The project runs a hosted version at nametag.one with a generous free tier and paid plans that fund development, and while you can self-host for free with unlimited contacts, the two are not identical products, and anyone who wants the hosted experience should look at the hosted one rather than assuming the self-hosted build has the same feature set on the same schedule. The fourth is a lightweight address book. This is a substantial application, a Next.js 16 front end with a Postgres database, an optional Redis, a Docker image, a Prisma schema and a build pipeline, and if all you want is contacts that sync from Google, the CardDAV sync alone is not worth the deployment.

On the licence, AGPL-3.0 is the term to understand before you go further. It is a strong copyleft licence, and the obligations attach to conveying the software, which is a different question from running it yourself for your own contacts, and anyone who modifies it and offers the modified version over a network is in the territory the licence was written for. The hosted version exists partly to fund development, so a business that wants a supported path has one, and anyone planning to fork and host a modified version should read the licence text rather than take a summary. The repository is private at the package level, marked private true in package.json, so the code is published as source for self-hosting rather than as an npm library, and the AGPL is the licence that governs that.

## Conclusion

Nametag suits someone who wants a private record of the people in their life, hosted on their own server with full data ownership and no per contact limit, and who is comfortable with a Next.js and Postgres deployment. It does not suit a household that wants several people editing one address book, since multi-user groups are still on the roadmap, and it does not suit you if you need a stable data model, because the project warns that breaking changes can land between releases. Before you adopt it, read the release notes before each upgrade as the README asks, keep the Postgres and Redis credentials in your own .env rather than the example values, and note that the last push was on 2026-10-15 with v0.64.0 published the same day.

## FAQ

### How do I self-host Nametag?

Create a directory, add a docker-compose.yml and .env file as the installation guide describes, then run docker compose up -d and visit http://localhost:3000. The compose file defines Postgres, an optional Redis and the app service, and the docs cover environment variables, email, OIDC, Redis and reverse proxy setup.

### Does Nametag sync contacts from Google or iCloud?

Yes. CardDAV sync is supported with Google Contacts, iCloud, Outlook and Nextcloud, and there is also vCard and JSON import and export alongside duplicate detection and contact merging.

### Can I use Nametag with several people editing the same contacts?

Not yet. Support for multi-user groups is an open roadmap item, and the to do list also includes notification support and an Immich integration, so multi-user editing is not a feature you can rely on today.

### What licence does Nametag use and is it safe to update?

The project is licensed under AGPL-3.0. The README carries an active development notice stating that breaking changes may be introduced between releases, and asks you to read the release notes carefully before updating.

## Sources

- [Issues](https://github.com/mattogodoy/nametag/issues)
- [License: AGPL-3.0](https://github.com/mattogodoy/nametag/blob/master/LICENSE)
- [mattogodoy/nametag on GitHub](https://github.com/mattogodoy/nametag)
- [README](https://github.com/mattogodoy/nametag/blob/master/README.md)
- [Releases](https://github.com/mattogodoy/nametag/releases)

---

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