# Kutt — Modern Self-Hosted URL Shortener

> A free, open-source URL shortener with custom domains, analytics, and API access that you can self-host or use as a service.

## Install

Save in your project root:

# Kutt — Modern Self-Hosted URL Shortener

## Quick Use
```bash
git clone https://github.com/thedevs-network/kutt.git && cd kutt
cp .env.example .env   # edit DB, Redis, mail settings
docker compose up -d
# Open http://localhost:3000
```

## Introduction
Kutt is a modern, open-source URL shortener that supports custom domains, link expiration, password protection, and click analytics. It offers a clean REST API and can be self-hosted as an alternative to Bitly or TinyURL.

## What Kutt Does
- Shortens URLs with optional custom slugs and custom domains
- Tracks clicks with geographic, browser, and referrer analytics
- Supports link expiration, password protection, and ban lists
- Provides a REST API for programmatic link creation and management
- Offers a browser extension for quick shortening from any page

## Architecture Overview
Kutt is a Node.js application built with Express and Next.js for the frontend. It uses PostgreSQL for storing links and analytics data, and Redis for rate limiting and caching. The app runs as a single service behind a reverse proxy. Authentication is handled via JWT with email-based registration or SMTP-less local accounts.

## Self-Hosting & Configuration
- Requires Node.js 18+, PostgreSQL, and Redis
- Configure via `.env` file: set `DB_HOST`, `REDIS_HOST`, `MAIL_*`, and `DEFAULT_DOMAIN`
- Run with Docker Compose for the simplest setup
- Add custom domains by pointing DNS to your Kutt instance and setting `CUSTOM_DOMAIN_USE_HTTPS`
- Enable or disable registration, link analytics, and email verification via environment variables

## Key Features
- Custom domain support for branded short links
- Detailed click analytics with charts and geographic data
- Link management dashboard with search, edit, and bulk delete
- REST API with API key authentication for automation
- Rate limiting and spam protection with configurable thresholds

## Comparison with Similar Tools
- **YOURLS** — PHP-based, plugin ecosystem, no built-in analytics dashboard
- **Shlink** — PHP with CLI and REST API, supports QR codes and multi-domain natively
- **Dub** — Modern SaaS-first shortener with analytics; self-hosting requires more setup
- **Polr** — PHP-based, lightweight, but less actively maintained
- **Lnk** — Minimal shortener without analytics or custom domains

## FAQ
**Q: Can I use multiple custom domains?**
A: Kutt supports one custom domain per instance in the open-source version. For multiple domains, run separate instances or use a fork with multi-domain patches.

**Q: Does Kutt support SSO or OAuth?**
A: Not natively. Authentication is email/password with JWT. You can add SSO via a reverse proxy like Authelia.

**Q: How do I migrate from another shortener?**
A: Import links via the REST API by scripting POST requests to `/api/v2/links` with your existing slugs and targets.

**Q: Is there a click analytics retention policy?**
A: Kutt stores all clicks indefinitely by default. You can set up a cron job to prune old analytics data from PostgreSQL.

## Sources
- https://github.com/thedevs-network/kutt
- https://kutt.it

---
Source: https://tokrepo.com/en/workflows/asset-9f78c663
Author: AI Open Source