lnkify-app

🔗 Lnkify

Quick start   •   Demo   •   Docs   •   Blog   •   Twitter   •   Discord

lnkify is a free-to-use URL shortener that can be easily self-hosted, with features like:

• 🔗 Shorten URLs with or without an account
• 🖌️ Custom slugs (back-halfs) on every lnkify
• 📊 Dashboard UI — full CRUD management for all your links
• 🚀 GraphQL API with queries and mutations for all operations
• 🤖 MCP server — AI agents can manage your links via natural language
• 🔐 API key authentication for programmatic and server-to-server access
• 📦 Bulk operations — create, update, and delete up to 100 links per call
• 🛡️ Rate limiting with configurable windows per endpoint
• 🕵️‍♂️ IP geolocation tracking on every click:
  • 🌐 IP address (spoof-resistant)
  • 🕸️ ISP name
  • 🗺️ IP location (city, coordinates)
  • 💻 Device details (OS, model)
  • 🪟 Browser name and version
• 🏃‍♂️ Fast redirections (~150ms)
• 🔌 Deploy to custom domain and infrastructure
• 💿 Compatible with PostgreSQL and many more
• ✨ Built on a modern tech stack

This project was created to be the most powerful URL shortener for the public, so no wonder it's so feature-rich

📸 Screenshots

Here is a sneak peek of the application and it's visuals 😍:

🤔 Why does Lnkify exist?

After looking at all the aka.ms links out there which flood windows, along with the numerous time saving been prompted to buy premium plans from bit.ly while shortening my URLs, the decision of having a reliable, personal URL shortener hosted on a custom domain for free caught wind.

🧮 Comparison

How lnkify compares to typical hosted URL shorteners (specifics vary by provider):

	lnkify	Typical hosted SaaS
Open source	✅	❌
Self-host on your own domain & infra	✅	❌
Custom domains	✅	💲 paid tier
Click analytics (geo, device, referrer)	✅	✅
Smart routing rules (country / device / time)	✅	⚠️ varies
GraphQL API + API keys	✅	⚠️ limited / paid
Native MCP server for AI agents	✅	❌
Bulk import / export	✅	⚠️ varies
No per-seat pricing	✅	❌

😲 Built With (Tech Stack)

The following technologies were involved in the making of this project.

• ⚛️ React 18 + Vite — dashboard (app/)
• 🔮 Apollo Client — GraphQL client + cache (dashboard)
• 🚀 Apollo GraphQL Server v5 - Server API
• 🤖 MCP (Model Context Protocol) - AI agent integration
• 💿 Prisma - ORM
• 😨 PostgreSQL — primary database
• 🧰 Redis — optional: cross-replica rate limits, MCP sessions, JWT logout
• 🌐 IP Registry - Geolocation lookups
• 🧭 Caddy — reverse proxy + automatic TLS
• 📚 VitePress — documentation site (docs/)

🤯 Quick Start Guide

To get started with having your own instance of Lnkify, follow the steps described in the following section

🚦 Get an API Key first

Lnkify uses IP Registry for Geo-location look-ups to track hits (free for 100,000 lookups)

Obtain an API key from the ipregistry.co website

💾 Installation

Requirements: Node.js >= 22 and pnpm (corepack enable will provision the pinned version).

Docker Compose (recommended)

cp .env.example .env          # then set JWT_SECRET (and optionally IPREGISTRY_API_KEY)
docker compose up --build

Caddy serves the dashboard and docs (with automatic TLS), and the API runs on port 4000.

From source (local development)

# Server (GraphQL API)
cd server
cp .env.example .env          # set DATABASE_URL, DIRECT_URL, JWT_SECRET, APIKEY_PEPPER
pnpm install
pnpm run db-init              # apply Prisma migrations to your database
pnpm run dev                  # starts the GraphQL API on :4000

# Dashboard (in a second terminal)
cd app
pnpm install
pnpm run dev                  # starts the Vite dev server

To build the dashboard for production: cd app && pnpm run build. The docs (docs/) follow the same pnpm run build pattern.

Tip: pnpm run seed:test (in server/) creates a fully-populated test account with ~2 weeks of realistic data for local testing.

Backup & restore (PostgreSQL)

The database is the only stateful service (Docker volume db-data). Back it up with pg_dump and restore with pg_restore/psql.

# Backup (compose stack)
docker compose exec -T db pg_dump -U postgres -d lnkify -Fc > lnkify-$(date +%F).dump

# Restore into a fresh database
docker compose exec -T db pg_restore -U postgres -d lnkify --clean --if-exists < lnkify-YYYY-MM-DD.dump

Run backups on a schedule (cron / a sidecar) and store them off-host. For an external/managed Postgres, point pg_dump / pg_restore at that database's host directly. After restoring, pnpm run db-init (or container startup) reconciles any pending migrations.

🛣 Roadmap

This project is far from perfect, and we'll reach there one day, or at least get close.

• ✅ Link-in-bio (shipped)
• Admin Panel Support
• Multiple Subdomain Support
• Email Notifications for hits (when enabled)
• Custom OG Preview for social sharing
• One-Click Deploys
• Password-protected links

Have a look at the issues for the full list of proposed features and enhancements, and open one to suggest your own.

📐 Architecture

lnkify runs as a small set of containers behind Caddy, which terminates TLS and routes each hostname to the right service:

Browser
  │
  ▼
Caddy (:443, automatic TLS)
  ├── app.lnkify.io   /graphql*        ──►  server  (Express + Apollo :4000)
  ├── app.lnkify.io   /*               ──►  app     (dashboard SPA, nginx)
  ├── lnkify.io       /graphql*, /llms* ─►  server
  ├── lnkify.io       /<slug>          ──►  server  (302 redirect)
  ├── mcp.lnkify.io                    ──►  server  (MCP endpoint /mcp)
  └── docs.lnkify.io                   ──►  docs    (VitePress static site)

server ──► PostgreSQL (state)  +  Redis (optional: rate limits, MCP sessions, idempotency)

See the Architecture guide for the full breakdown.

⭐ Contributing

Contributions are what make the open-source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Also, refer to CONTRIBUTING.md

🙏 Acknowledgements

lnkify began as a fork of Pckd, the open-source URL shortener created by Mohit Yadav. Huge thanks to Mohit and the original Pckd contributors for the foundation this project is built on. lnkify has since grown into its own standalone project, but the original work made it possible.

🛡 License

Distributed under the MIT License. See LICENSE.md for more information.

🌟 Star this project

If you believe this project has potential, feel free to star this repo.

API Documentation

Authentication

lnkify supports two authentication methods for the GraphQL API:

1. JWT Bearer Token — Used by the dashboard. Obtained via signup/login mutations.
   Authorization: Bearer <jwt>

2. API Key — For programmatic/server-to-server access.
   x-api-key: <key> or Authorization: Bearer lf_live_<key>

API keys can be created and managed from the API Keys screen in the dashboard. Keys are scoped to the full account of the creating user.

Rate Limiting

Endpoint	Default Limit	Window
POST /graphql	120 requests	1 minute
Redirect path	600 requests	1 minute
Bulk operations	10 calls	1 minute

Rate limit headers are returned on every response:

• RateLimit-Limit
• RateLimit-Remaining
• RateLimit-Reset

Exceeded requests receive HTTP 429 with a Retry-After header.

Bulk Operations

Three mutations accept arrays and return per-item results:

• createLnkifies(inputs: [CreateLnkifyInput!]!): [BulkLnkifyResult!]!
• updateLnkifies(inputs: [UpdateLnkifyInput!]!): [BulkLnkifyResult!]!
• deleteLnkifies(ids: [ID!]!): [BulkDeleteResult!]!

Maximum batch size: 100 items (configurable via BULK_MAX_ITEMS). Partial success — one failed item does not abort the rest.