Introduction
Sticky notes, three different phone apps, a half-abandoned spreadsheet — if that's how you're tracking what needs doing, you're not alone, and it's not really your fault. Most "simple" to-do apps either get abandoned after two weeks or start charging you $8 a month once you have more than one project. Vikunja skips both problems by living on hardware you already own.
This tutorial walks you through installing Vikunja in an LXC container on Proxmox VE 9.2, using the community-maintained install script most homelab users reach for. You don't need to know Go, or anything about the app's internals. You need a Proxmox host, about ten minutes, and a spare 4 GB of disk space.
What You'll Learn
- What Vikunja is and how it's different from a plain checklist app
- How to deploy a Vikunja LXC container using the Proxmox VE community script
- How to create your first account and lock down registration afterward
- Where the config file lives and which settings actually matter
- What to do when the container won't start or the web page won't load
What Is Vikunja?
Vikunja is an open-source task and project manager you run yourself. Think Todoist or Microsoft To Do, but the data sits on your own server instead of someone else's cloud. It's written in Go for the backend and Vue for the web interface, and it's released under the MIT license, so there's no subscription tier hiding behind a paywall.
Under the hood, Vikunja organizes work into projects (older versions called them "namespaces"), and each project holds tasks. Tasks can have due dates, priorities, labels, checklists, and file attachments. You can view a project as a flat list, a Kanban board, a table, or a Gantt-style timeline — whichever matches how your brain actually works.
It also speaks CalDAV, which is the same protocol calendar apps use to sync. That means your Vikunja tasks with due dates can show up in Apple Calendar, Thunderbird, or any CalDAV-aware calendar app, right alongside your actual appointments.
Why Would You Use It?
The honest answer: because you're tired of your task list living inside a company that might shut down, get acquired, or decide the free tier needs to shrink. Self-hosting removes that risk entirely — Vikunja keeps working exactly the same way whether or not the company behind it exists in five years, because you're the one running it.
There's a practical side too. A 1 vCPU, 1 GB RAM LXC container is more than enough to run Vikunja for a household or a small team, and it barely registers on a Proxmox host that's already running a handful of other containers. You're not carving out serious resources for this.
If you're only tracking a personal grocery list, Vikunja is honestly overkill — a notes app will do. Where it earns its keep is shared project tracking: a home renovation, a small dev team's sprint board, or a household running four or five ongoing projects at once with different people responsible for different pieces.
Prerequisites
- A working Proxmox VE host — this guide was written and tested against Proxmox VE 9.2, built on Debian 13.5 "Trixie"
- Root access to the Proxmox host shell (via the web UI's Shell button on the node, or SSH)
- At least 4 GB of free space on the storage you'll install to, plus a bit of headroom if you plan to attach files to tasks
- Internet access from the Proxmox host and from the container's network, since the install script pulls packages and the Vikunja binary from GitHub
- A rough idea of your network's IP range, so you can find the container afterward
You don't need to know Go, Vue, or anything about databases. The install script handles all of that for you.
Step-by-Step Tutorial
Step 1: Open the Proxmox Host Shell
Log in to the Proxmox VE web interface, click your node in the left-hand tree, then click >_ Shell in the top right. This drops you into a root shell on the Proxmox host itself — not inside any container yet.
Step 2: Run the Community Script
Paste this command and press Enter:
bash -c "$(curl -fsSL https://raw.githubusercontent.com/community-scripts/ProxmoxVE/main/ct/vikunja.sh)"This is the same community-scripts project (community-scripts.org, formerly tteck's scripts) that maintains install scripts for a few hundred self-hosted apps. It downloads the script and runs it immediately, no separate download-then-run step needed.
Step 3: Walk Through the Setup Prompts
A blue whiptail menu appears asking whether to use Default Settings or Advanced. For a first install, Default Settings is fine — it creates an unprivileged Debian 13 container with 1 vCPU, 1024 MB of RAM, and a 4 GB disk. That's genuinely enough for Vikunja; it's a lightweight app.
If you already know you want more disk (say you're planning to attach a lot of files to tasks) or a static IP instead of DHCP, pick Advanced and set that up now — it's easier than resizing later.
Step 4: Let the Script Finish
The script creates the container, installs Debian 13, downloads the Vikunja binary from its GitHub releases, and sets it up as a systemd service. This takes somewhere between two and five minutes depending on your internet connection. When it's done, you'll see a summary with the container's ID and IP address printed in green text — write that IP down.
One thing worth knowing up front: Vikunja's v2.4.0 release has a startup bug where systemd's SystemCallFilter setting kills the process immediately after launch. Because of that, the script currently installs v2.3.0 instead, which doesn't have the problem. If you check the version later and it looks "behind," that's why — it's intentional, not a mistake.
Step 5: Open Vikunja in Your Browser
Go to http://<container-ip>:3456. Port 3456 is the default port the Vikunja binary listens on — there's no separate nginx or Apache step here, since the Vikunja binary serves its own web interface directly.
Step 6: Create Your Account
Unlike some of the other self-hosted apps in this series, Vikunja doesn't ship a default admin username and password. The first time you load the page, click Register and create your own account with your email, a username, and a password. That account becomes a normal user — there's no separate "admin" role to worry about at this stage.
Step 7: Lock Down Registration
By default, anyone who can reach port 3456 can register their own account. That's fine on an isolated homelab VLAN, but not something you want if the container is reachable from a wider network. Once your account (and anyone else's you want) is created, turn registration off.
From the Proxmox host, enter the container and edit the config file:
pct enter <vmid>
nano /etc/vikunja/config.ymlFind or add the service section and set:
service:
enableregistration: falseSave the file, then restart the service so the change takes effect:
systemctl restart vikunjaThe registration link disappears from the login page immediately. If you need to add another user later without turning registration back on, you can create one from the command line instead — covered in Commands Explained below.
Step 8: Create Your First Project
Log in, click the plus icon next to Projects in the sidebar, and give it a name. From there, add a task, set a due date if it needs one, and try switching the view between List, Kanban, and Table using the tabs at the top. Nothing about this step is Proxmox-specific — at this point you're just using Vikunja like you would any hosted alternative, except the data never leaves your network.
Commands Explained
| Command | What It Does |
|---|---|
curl -fsSL <url> | Downloads the install script quietly (-s), fails loudly on a bad response (-f), and follows redirects (-L). |
pct enter <vmid> | Run from the Proxmox host shell to get a root prompt inside the container, replacing your ID with the container's actual number. |
pct exec <vmid> -- <command> | Runs a single command inside the container without opening a full session — handy for quick checks from the host. |
systemctl status vikunja | Shows whether the Vikunja service is running, and the last few log lines if it isn't. |
systemctl restart vikunja | Restarts the service — needed after any change to config.yml, since Vikunja doesn't reload config on the fly. |
journalctl -u vikunja -e | Jumps straight to the end of Vikunja's service logs, which is where the actual error usually is. |
vikunja user create --email <email> --user <username> --password <password> | Creates a new user from the command line, run from inside the container — the workaround for adding accounts once registration is disabled. |
pct resize <vmid> rootfs +4G | Grows the container's disk by 4 GB if the default 4 GB fills up, without touching anything already stored there. |
You don't need to memorize any of this before installing. It's here for when something breaks and you need to go digging.
Common Errors
The web page never loads, browser just times out. Nine times out of ten this is a container still finishing its first boot, or a typo in the IP address. Give it another 30 seconds, then double-check the IP with pct list on the Proxmox host.
Service fails immediately after start, or after a manual update. This is almost always the v2.4.0 SystemCallFilter issue mentioned above. If you manually updated the binary outside the script and it crash-loops, check journalctl -u vikunja -e for a systemd filter-related message and roll back to v2.3.0.
"Connection refused" on port 3456. Either the service isn't running yet, or something else on the container is already bound to that port. Run systemctl status vikunja first — that tells you which of the two you're dealing with.
Registration link is gone and you're locked out. That's expected once enableregistration: false is set. Use the CLI command from the table above to add a new user instead of re-enabling public registration.
Troubleshooting
Start with the basics: is the container actually running? From the Proxmox host, pct status <vmid> tells you in one line. If it shows "stopped," start it with pct start <vmid> and try again.
If the container is running but Vikunja still won't respond, get inside it and check the service directly:
pct enter <vmid>
systemctl status vikunja
journalctl -u vikunja -eA healthy service shows "active (running)" in green. If it shows "failed," the journal output right above the status line almost always names the actual problem — a missing config value, a bad file permission, or the systemd filter bug from earlier.
If the app loads but you can't log in and you're sure the password is right, check whether enableregistration got set to false before you ever created an account — that's a mistake people make when copying config snippets from someone else's setup before registering themselves first. Re-enable it temporarily, register, then disable it again.
Network problems are worth ruling out separately from app problems. If pct exec <vmid> -- ping -c3 1.1.1.1 fails, nothing about Vikunja itself matters yet — fix the container's network access first.
Best Practices
Turn off public registration as soon as your accounts exist. It takes thirty seconds and closes off a real, if minor, attack surface.
Back up the container regularly using Proxmox's built-in vzdump tool or Proxmox Backup Server if you have it. Vikunja's default SQLite database lives inside the container's filesystem, so a normal container backup captures everything — tasks, projects, and attachments — in one shot.
Resize the disk before you need to, not after. The default 4 GB is fine for text-only task tracking, but if your team attaches screenshots or PDFs to tasks regularly, bump it to 8 or 16 GB up front with pct resize.
If you're exposing Vikunja outside your home network, put it behind a reverse proxy with HTTPS rather than forwarding port 3456 directly. Task data isn't usually sensitive, but login credentials traveling in plain HTTP are never a good idea.
Keep an eye on the project's GitHub releases before updating past whatever version the script currently pins. The v2.4.0 startup issue is a good reminder that "latest" isn't automatically "best" for a self-hosted service you depend on daily.
Frequently Asked Questions
Does Vikunja require a separate database server? No. It uses SQLite by default, which is a single file and needs no setup. MySQL and PostgreSQL are supported if you outgrow SQLite, but most homelab and small-team use never gets there.
Can I sync Vikunja with my phone's calendar? Yes, through CalDAV. Add your Vikunja server as a CalDAV account in your phone or desktop calendar app and tasks with due dates appear alongside your regular events.
Is there a mobile app? There are unofficial Android and iOS apps in progress, plus a browser-based Progressive Web App you can add to your home screen, which covers most people's day-to-day needs.
How do I update Vikunja later? Run the exact same one-liner from Step 2 again on the Proxmox host. The script detects the existing container and offers to update it in place instead of creating a new one.
Can more than one person use the same Vikunja instance? Yes — that's most of the point. Create a user account per person and share projects between them from inside the app.
What happens if I lose the container? Whatever your last backup captured is what you get back. There's no cloud copy sitting somewhere else, which is the tradeoff for owning your own data — back it up like you mean it.
Conclusion
You've now got a task manager running on hardware you control, reachable only by the people you choose to give access to. It took one command, a few whiptail prompts, and about ten minutes end to end.
From here, the natural next steps are locking registration down, setting up a real backup schedule, and maybe putting it behind a reverse proxy if you want to reach it while you're away from home. None of that is required to start using it today — open a project, add a task, and see if it sticks better than the sticky notes did.