Getting started

What is kvellman?

kvellman is a self-hosted, winget-compatible package repository. You register it as an additional winget source — the winget CLI queries it exactly like the official Microsoft source. The origin is the server you run: the admin UI, the winget Source API, and installer delivery. Clients are unmodified winget installations — nothing installs on the Windows side beyond a source registration.

What you need

A host that can run a container, a DNS name pointing at it, and trusted HTTPS. winget refuses REST sources that aren't served over HTTPS with a certificate the client trusts — including localhost on recent winget versions.

1. Run the origin (Docker)

The Community edition runs from a single docker compose stack (app + PostgreSQL). With a domain pointing at your host and ports 80/443 open:

git clone <open-core-repo> kvellman && cd kvellman
cp .env.deploy.example .env.deploy   # set DOMAIN, NUXT_SESSION_PASSWORD, POSTGRES_PASSWORD
docker compose --env-file .env.deploy up -d

Database migrations run automatically on start. Open https://your-domain — the first visit creates the admin account.

2. Create a site token

In the web UI: Admin → Site tokens → create one. The token becomes part of the URL clients use to reach this source. See Sites for what a site token actually controls.

3. Add a package

Two ways to get a package into the catalogue:

• Import it from the upstream winget catalogue (Packages → Import), or
• Author it yourself: create the package and upload a manifest.

Either way, a new version isn't visible to clients until it's approved — open the version and approve it (Packages → your package → the pending version). This is the step people most often miss: an imported package that shows up in the dashboard but returns nothing from winget search almost always just needs approval.

4. Add the source on a client

winget requires HTTPS for a REST source. On a Windows client (PowerShell):

winget source add --name kvellman --type Microsoft.Rest --arg "https://your-domain/api/<site-token>"
winget search --source kvellman <term>
winget install --source kvellman <Package.Identifier>

That's it — clients now install internal software through your own winget source.

Next steps

• Concepts — the vocabulary the rest of the docs use.
• Packages & manifests — importing, overlays, approval, installer storage.
• Sites — site tokens, URL placeholders, onboarding more clients.
• Users & roles — accounts, the audit log, SSO/MFA.
• Edge nodes — serving remote locations from a local cache.
• Deployment — the reverse-proxy requirement, configuration, operations.