Control panel

Where you manage everything. It holds the library and runs every site.

Library

Every title, with its links, is kept once in the control panel.

Sites

Each has its own domain, theme and content rules that choose which titles it shows.

Local site

Runs on the same server as the control panel. Point its domain here.

Remote site

Runs on another host from one index.php file. It fetches pages from the control panel and caches them.

Media stays remote. Posters and videos are linked, never downloaded to your server.

Back end

PHP 8.3, Laravel 13

Control panel

Vue 3 with Inertia, Tailwind CSS 4, built with Vite

Sites

Twig themes in a sandbox, with Alpine.js

Database

MySQL or MariaDB

PHP

8.3 or newer

Database

MySQL 5.7+ or MariaDB 10.3+

PHP extensions

pdo_mysql, curl, mbstring, fileinfo, zip and dom

PHP functions

symlink or exec, for the storage link

Writable

storage, bootstrap/cache, themes, public/themes and the project folder, so the installer can write .env

1. Upload and unzip BlackKitt on your server, for example in /home/you/blackkitt.
2. Point your control panel’s domain at its public folder. On cPanel: Domains › set the document root to blackkitt/public.
3. Open https://your-panel.com/install.
4. Follow the steps:
   LicenceServerDatabasePanelInstall
5. Add the cron job the last screen shows. See After installing.

The installer locks itself when it finishes. You can then delete public/install.

For servers where the installer can’t run. From the project folder:

composer install --no-dev --optimize-autoloader
cp .env.example .env
php artisan key:generate
# set APP_URL, APP_ENV=production and DB_* in .env
php artisan migrate --force --seed
php artisan storage:link
php artisan themes:sync
php artisan optimize

Set BLACKKITT_ADMIN_EMAIL and BLACKKITT_ADMIN_PASSWORD in .env before seeding. They become your owner account. Remove them afterwards.

One cron entry, every minute. It runs imports, bots, link checks and background jobs.

* * * * * cd /path/to/blackkitt && php artisan schedule:run >> /dev/null 2>&1

Automation › Jobs and queue shows the exact line for your server.

Movies and series are imported from TMDB. Get a free key at themoviedb.org › Settings › API, then paste the API read access token into System › Integrations. AniList and TVmaze need no key.

Import a few titles from Content › Explore and import, or many at once from Automation › Bulk import. See Adding titles.

• Create it: Sites › All sites › Add site
• Point its domain: the site’s Domains and install
• Logo, colours and layout: Site settings, Theme settings and Design and blocks

See Sites.

1. Close the control panel and local sites: php artisan down
2. Upload the new files over the old ones. Keep .env and storage, then delete public/install.
3. Update the database, themes and caches:

   php artisan migrate --force
   php artisan themes:sync
   php artisan optimize

4. Reopen it, and restart the worker if you run one:

   php artisan up
   php artisan queue:restart

Themes you uploaded are kept. Only the built-in ones are replaced.

When a newer edge file is out, the site’s Domains and install says so. Click Update edge, or for older edges, download the installer again and replace index.php.

* * * * * cd /path/to/blackkitt && php artisan schedule:run >> /dev/null 2>&1

Keep the cron job with a worker too. Bots, health checks and clean-up still need it.

Save as /etc/supervisor/conf.d/blackkitt-worker.conf:

[program:blackkitt-worker]
command=php /path/to/blackkitt/artisan queue:work --sleep=3 --tries=3 --max-time=3600
user=www-data
autostart=true
autorestart=true
stopwaitsecs=3600
stdout_logfile=/path/to/blackkitt/storage/logs/worker.log

sudo supervisorctl reread && sudo supervisorctl update

• Failed jobs are listed in Automation › Jobs and queue, to retry or clear.
• Run pending jobs now works the queue from your browser, for when cron is slow or not set up yet.
• A job fails after 3 tries. Failed jobs are kept for 30 days.
• With a worker, after every upgrade: php artisan queue:restart

Cache full pages

On by default. Pages are kept for 600 seconds.

Block cache

Each block on a page is kept for 1800 seconds.

Editing a title, its links or a site’s design clears what it touches. You rarely need to purge by hand.

On a remote site the purge reaches its own cache too. If it doesn’t answer, it purges at its next check-in.

Posters load from their source. To resize and convert them on the way, add an image proxy in System › Media, for example:

https://wsrv.nl/?url={url_encoded}&w={width}&output=webp

Details

Name, overview, genres, artwork, release, external ids and fields for its type.

Episodes, Chapters

Seasons and episodes, or chapters with one image address per line.

Cast and crew

People, in the order you set.

Trailers and images

Trailers and extra artwork.

Links

Where it plays. See Links and players.

SEO

Its own search title and description.

Sites

Per site: shown by the rules, always shown or hidden, with its own SEO text.

Draft

Hidden from every site.

Published

On every site whose rules match it.

Scheduled

Published by itself when its publish date passes.

Archived

Kept, but off the sites.

Move to trash can be undone. Titles in the trash can be restored or deleted permanently.

• Refresh pulls the latest details from the source. Your own edits to text are kept.
• Collections, Genres, Tags and People organise the library. Tags drive site content rules.
• Links and media › Media library holds your own uploads, such as logos. Title artwork is never downloaded.

Search by name, or paste a TMDB, AniList or TVmaze link or an IMDb id. Choose the status and tags, and whether to bring seasons, episodes and cast. For a video, paste its link or embed code.

Or choose Create by hand and fill it in yourself.

Browse TMDB, AniList and TVmaze lists, such as popular or trending, tick what you want and click Import selected, or Import whole list for several pages at once.

Paste ids or links

One per line, up to 2,000. Links, IMDb ids, or bare ids for the chosen provider.

CSV file

Columns provider,id,media, or one link per line. Up to 2 MB.

Provider list

1 to 20 pages of a list, about 20 titles a page.

https://www.themoviedb.org/movie/27205
tt0903747
anilist,21

Imports run in the background. Each batch has a report, and Retry for the ones that failed.

A bot does one job on a schedule, from every 15 minutes to weekly:

Import a provider list

Such as TMDB trending or this anime season.

Refresh ongoing titles

New episodes and dates for shows still airing.

Check links

Re-checks links and marks dead ones.

Build sitemaps

Keeps every site’s sitemap fresh.

Five bots come ready. Link checker and Sitemaps are on; turn the others on when you’re ready. Bots need the cron job.

Set the import language, region and whether adult titles are skipped in System › General and System › Integrations.

Open a title › Links › Add links and paste one address or embed code per line. For a series, spread them across episodes. Each link has:

Edit the Audio languages and Format choices in System › Links and players.

Embed

Plays in a frame, such as a video host’s player.

Direct file

Plays an MP4 or HLS stream in the built-in player.

Auto

Builds a link for every title from a template, such as https://host/embed/{tmdb_id}. No pasting needed.

Manual

Only plays the links you add.

Priority sets the order. Each site can offer all of them or its own list.

Link checker

Re-checks active links every 72 hours. After 3 failed checks a link is marked dead.

Dead page phrases

Words such as “File not found” that mark a link dead even when the page loads.

Link hosts

Every host found in your links. Allow or block each one; blocked hosts never play.

Reports

Visitors report broken links. Mark the link dead, disable it, or dismiss the report.

Upload or link .vtt, .srt or .ass files, up to 2 MB, and set a default track. SRT is converted for you.

• Pages never hold a link’s address, only a signed token that expires after 6 hours.
• At play time the link, its host, the title and the player are all checked again.
• For the strictest setup, turn on Only play links from allowed hosts in System › Links and players.

1. Click Add site and choose where it runs: On this server or On another host.
2. Enter the Site name, a tagline and the domain. A local site can get its domain later.
3. Pick a theme. Its content types fill in for you.
4. Leave Content empty to show the whole library, or narrow it now. Then Create site.

A local site goes live at once. A remote site waits until you install it. See Domains and remote sites.

Which titles the site shows. Open the site › Content rules.

Content types

Movies, series, anime and so on. None chosen shows every type.

Tags

Only titles tagged, with any or all of the tags, and titles never to show.

Filters

Genres, countries, original language, minimum rating, release dates and adult titles.

The side panel counts what your rules match as you change them. Save and rebuild applies them; big libraries rebuild in the background.

Status

Online, Maintenance or Draft. Maintenance and Draft show visitors an “unavailable” page.

Branding

Logo, logo on dark and favicon.

Footer

Footer text, a notice and social links.

Custom code

Your own tags inside <head> and before </body>, such as analytics.

Add each domain the site answers on and tick HTTPS where it has a certificate. The primary one is used in links, sitemaps and canonical addresses.

1. At your registrar, add an A record for the domain, pointing at the Server address the page shows. Cloudflare-proxied records work too.
2. Add the domain to the same hosting account as the control panel: an alias in cPanel or Plesk, or a server_name in your nginx or Apache config.

1. Click Download index.php. The file already holds the site’s key.
2. Upload it to the domain’s empty web root, such as public_html. The host needs PHP 7.4 or newer with cURL.
3. Open the site. It connects on the first visit.

The control panel must be reachable from the internet. Remote sites fetch their pages from its APP_URL.

• Pages come from the control panel and are cached in bk-cache, next to index.php.
• If the control panel is down, visitors still get cached pages.
• It checks in every few minutes while it has visitors, and picks up purges then.
• Revoke access gives the site a new key. The old file stops working until you upload a new download.

Kitt Movie

Movies and TV shows: big hero, landscape trending cards.

Kitt Anime

Dark first: airing this season, latest episodes, weekly schedule.

Kitt Drama

Asian dramas: ranked trending rows, country chips, airing schedule.

Kitt Manga

Reading first: chapter updates, top charts and a vertical or paged reader.

Kitt Tube

A video portal: category chips, 16:9 grids and an up-next list.

Kitt Embed

An embed provider: a link builder and a player other websites frame.

Kitt Core

The shared base the others build on.

Switch in the site’s Theme settings › Change theme. Each theme keeps its own layouts and settings, so switching back restores them.

1. Open the site › Design and blocks and pick a page, such as Home or Title.
2. Add, drag, hide or duplicate blocks. Each block has its own Settings, and Visibility for devices and dates.
3. Preview on desktop, tablet and mobile. Changes save as a draft.
4. Click Publish to make them live.

History keeps the last 15 published versions. Restore one, or start again from the theme’s layout, as a draft.

Theme settings

Colours, fonts and defaults, grouped by the theme.

Menus

Header, footer and mobile. An empty mobile menu uses the header’s.

Pages

Your own pages. Starters for About, DMCA, Privacy and Contact.

Upload theme takes a .zip with theme.json at the top, up to 20 MB. It’s checked before anything is replaced, and problems are listed by file and line.

Uploads keep the last 3 versions for 30 days, to Restore from the theme’s page. Theme authors: see docs/THEMES.md.

Title separator, default search engine setting, Google and Bing verification, X handle and a default share image.

Set the title, description and robots for each kind of page. Click a field to see its placeholders and a search preview:

Choose the address pattern for each page type, such as /genre/{slug}.

Changing a pattern on a live site breaks links people and search engines already have.

/sitemap.xml is built for you. Leave robots.txt empty to use the automatic one, which points to the sitemap.

By default a site offers every player. Drag to set the order and switch players off to make a custom list. The first one on is what visitors see first.

Set Allow embedding to Any website or Only these domains. Other sites then frame your player:

/embed/movie/27205
/embed/series/1399/1/1

The id can be a TMDB or IMDb id, tmdb-27205, or id-123 for your own. The page lists the formats for every content type.

Turn on Publish JSON feeds and pick which ones:

/feeds/movie.json
/feeds/episodes.json?since=2026-01-01

Feeds page with ?page= or an ?after= cursor, up to 100 items a page.

The Kitt Embed theme turns on embedding and feeds for you.

Sites, themes and system settings are for owners and admins only. The last active owner can’t be removed.

Every change made in the control panel, with who made it and when. System › Activity log

• Move the control panel off /admin with BLACKKITT_ADMIN_PATH, or onto its own domain. See .env settings.
• Switch off users who no longer need access. Inactive users can’t sign in.

The settings are cached. Refresh them:

php artisan config:clear
php artisan optimize

API keys, caching, the queue mode and link rules are in System. Change them there, not in .env.

• Check the domain points at the public folder, not the project folder.
• Read the latest error in storage/logs/laravel.log.
• After an upgrade, clear and rebuild the caches:

  php artisan optimize:clear
  php artisan optimize

Check the domain is listed in the site’s Domains and install, and that its DNS points at this server. A domain that belongs to no site shows a “not found” page.

• Open the site. Its setup page lists what failed: PHP version, cURL, a writable cache folder, or the connection.
• The host must allow outgoing HTTPS, and APP_URL must be a public address.
• If you downloaded the installer again or revoked access, upload the newest index.php.

Design changes need Publish. Otherwise purge the site in its Cache page. New titles only appear on sites whose content rules match them.

The cron job isn’t running. Check Automation › Jobs and queue, which says when the scheduler last ran. See Queue and scheduler.

php artisan storage:link --force

If it says the link already exists, delete the public/storage folder and run it again. Your uploads are safe in storage/app/public.

It locks itself after installing. To start over, delete storage/app/installed.lock and set APP_ENV to local.

Installing again erases every table.

Email

support@kittapps.com for install help, questions and requests

Telegram

t.me/kittapps for quick questions

Stuck installing? We’ll help for free. Send your server details, or screenshots of the step that fails.

• Note your BlackKitt and PHP versions.
• Copy the latest error from storage/logs/laravel.log.
• Try the fixes in Troubleshooting.