Skip to content
Get packs

Guide · Open source

How to use Kutt: install, configure and run your own shortener

Updated · written with AI from the project's own documentation and checked against our catalogue data

Kutt is a free, open-source URL shortener that turns long web addresses into short links and lets you manage them, including on your own custom domain. This guide is for people who want to run their own link shortener instead of using a hosted service. By the end you will know the prerequisites, how to install and start Kutt with npm or Docker, and which settings control the database, registration and custom domains.

Kuttthedevs-network/kutt · ★ 11.2k · MIT

Quick start

  1. 1Check prerequisites. Install Node.js version 20 or above. Docker is optional and only needed for the Docker setup.
  2. 2Clone the repository. Run git clone on the Kutt repository, or download the latest zip from the releases page.
  3. 3Install dependencies. Run npm install inside the project folder.
  4. 4Initialise the database. Run npm run migrate. The default database is SQLite.
  5. 5Start the app. Run npm start for production or npm run dev for development, then create your admin account in the browser.

What you need before you install Kutt

The only prerequisite listed for a standard install is Node.js, version 20 or above. The default database is SQLite. You can optionally use Postgres or MySQL/MariaDB for the database, and Redis for the cache.

Docker is optional and only needed if you want to use the Docker setup.

  • Node.js 20 or above (required for the npm setup)
  • Docker (optional, for the Docker setup)
  • Optional: Postgres, MySQL/MariaDB or Redis

Install and start Kutt with npm

Clone the repository, install the dependencies, then initialise the database. Start the app for production with npm start, or use npm run dev for development.

When you first start the app, you are prompted to create an admin account.

git clone https://github.com/thedevs-network/kutt.git npm install npm run migrate npm start

Run Kutt with Docker

Make sure Docker is installed, then start the app from the root directory of the project with docker compose up.

Several docker-compose files are available. Use the -f flag to choose the one you want. The default file uses SQLite. The others start Kutt with Redis, and with Postgres or MariaDB.

  • docker-compose.yml: default setup, uses SQLite
  • docker-compose.sqlite-redis.yml: SQLite and Redis, needs REDIS_ENABLED
  • docker-compose.postgres.yml: Postgres and Redis, needs REDIS_ENABLED, DB_PASSWORD, DB_NAME, DB_USER
  • docker-compose.mariadb.yml: MariaDB and Redis, needs REDIS_ENABLED, DB_PASSWORD, DB_NAME, DB_USER, DB_PORT
docker compose up docker compose -f <file_name> up

Configure Kutt with environment variables

Kutt is configured with environment variables. You can pass them directly or put them in a .env file. The project includes an .example.env file that lists all the options.

Almost all variables are optional. JWT_SECRET is the exception: it is required in production and is used to sign authentication tokens, so use a long, random string. You can also load any variable from a file by adding _FILE to its name.

  • DEFAULT_DOMAIN: the domain the app runs on (default localhost:3000)
  • PORT: the port to start the app on (default 3000)
  • DB_CLIENT: choose Postgres, MySQL/MariaDB or SQLite client
  • DISALLOW_REGISTRATION: disable sign-ups (default true)
  • DISALLOW_ANONYMOUS_LINKS: disable anonymous link creation (default true)
  • CUSTOM_DOMAIN_USE_HTTPS: use https for custom domain links (default false)
  • ENABLE_RATE_LIMIT: rate limiting for some API routes (default false)
JWT_SECRET=use-a-long-random-string

Use custom domains and the admin page

Kutt supports custom domains, so your short links can use your own address. The README says you must generate SSL certificates for custom domains yourself when CUSTOM_DOMAIN_USE_HTTPS is enabled. Kutt does not handle that for you in this version.

Once running, you can create, edit and delete links, set custom URLs, passwords, descriptions and expiration times, view private statistics, and manage users and links from the admin page.

  • Create, edit, view and delete links
  • Set custom URLs, password, description and expiration time
  • View private statistics for shortened URLs
  • Manage users and links from the admin page

Use the API

Kutt includes a RESTful API for developers who want to create and manage links from their own code. The full API documentation is hosted at docs.kutt.to, which is linked from the project README.

What people use it for

  • Running a private link shortener for your own website or organisation
  • Creating short links on a custom domain for a team
  • Managing links and their statistics from an admin page
  • Building tools that create short links through the RESTful API

Frequently asked questions

Is Kutt free to use?

Kutt is released under the MIT licence, which is an open-source licence. The project also accepts donations and sponsorship, but the source does not list any fees for using it.

What do I need to install Kutt?

The only prerequisite named in the README is Node.js version 20 or above. Docker is optional and only needed for the Docker setup.

Which database does Kutt use?

The default database is SQLite. Kutt also supports Postgres, and MySQL or MariaDB, which you can select with the DB_CLIENT variable.

Does Kutt create SSL certificates for custom domains automatically?

No. The README says you must generate SSL certificates for custom domains yourself. The CUSTOM_DOMAIN_USE_HTTPS variable tells Kutt to use https for those links.

Can I turn off sign-ups so only I can use my Kutt instance?

Yes. DISALLOW_REGISTRATION disables registration, and DISALLOW_ANONYMOUS_LINKS disables anonymous link creation. Both are set in environment variables.

What are the alternatives to Kutt?

Comparable self-hosted projects include YOURLS, Shlink and Polr. Pick based on which features and database options matter most to you.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Kutt suits people and teams who want to run their own URL shortener on a custom domain, and developers who want a RESTful API. It is less suitable if you only need a quick link shortener without hosting anything, or if you want HTTPS certificates handled automatically, since the README says you must generate them yourself.

Install options & downloads