Capka

You hand Capka a task and some files, and it hands back the finished thing: a report, a cleaned-up spreadsheet, a converted document, a patch. It runs on your own server, so the work happens in an isolated Linux sandbox there, not on the laptop of whoever asked.

I wanted something I could run myself, connect to my own models and API keys, and share with a small team. Not another hosted chat product locked to one vendor.

I have followed LLMs and agent tools since the start, and tried a lot of them in real work. A lot of them still feel like chat wrappers, are hard to self-host, or are unpleasant to use every day.

Capka is where I put the parts I actually wanted: files, tools, code execution, durable tasks, isolated workspaces, MCP, and a UI that does not fight you.

The workflow is intentionally simple:

1. You upload files, or the agent downloads or creates them during the chat
2. Each chat (or each project, for chats inside one) gets its own Linux sandbox and file storage
3. The agent works inside that workspace and returns files you can use.

Nothing depends on your browser staying open. Every turn is a queued job on the server, saved after each step, so a closed tab, a dropped connection, or a restart of Capka itself resumes where it left off instead of losing the reply.

This is a solo project, built seriously. I am trying to make the AI tool I actually want to use.

There is a longer walkthrough on the website, or you can try the live demo and hand it a real task right now.

At a glance

What you get back	Files: reports, spreadsheets, PDFs, converted documents, patches
Where the work happens	An isolated Linux sandbox on your server, one per chat or project
Runs on	Your Linux server with Docker
Files	What people upload, plus what the agent downloads or creates during the chat
Models	Cloud providers or local models through Ollama
Users	Multi-user, registration closed by default
Admin	Users, auth, providers, MCP, skills, policies, security, usage, updates

What People Use It For

The tasks where the useful output is not a message:

• reports and spreadsheet work
• PDFs and document conversion
• research over uploaded or downloaded files
• file organization and cleanup
• repetitive office jobs nobody wants to do by hand
• small coding and debugging work
• workflows through MCP tools and connectors

Is Capka for you?

Reach for Capka if:

• your files should not leave your own infrastructure
• the people using it are not developers, and should not have to think about providers or keys
• you would rather choose models and pay for tokens than pay a per-seat subscription
• you have a small Linux server, or do not mind renting one

Look elsewhere if:

• you just want to chat with a model and never touch files — a plain chat app is simpler
• nobody wants to run and maintain a server — hosted products exist for a reason
• you need vendor support with an SLA — Capka is open source, and support lives in GitHub issues

For teams

One person sets Capka up: connects a provider key, picks which models everyone may use, decides who gets in. After that nobody else has to know what a provider is. That split runs through the whole product, not just the setup screen.

Starting alone is the normal way in. Install it for yourself, use it on your own work, and invite people to the same server when you are ready.

Admins get one place to manage the instance:

Area	What admins control
Users	roles, pending approvals, registration mode
Models	provider keys, default models, local or cloud providers
Tools	MCP connectors, skills, marketplace plugins
Safety	allow, ask, deny policies, audit log, sandbox internet access
Ops	usage, billing status, updates, Telegram bot setup

Each chat, or each project for chats inside one, gets its own sandbox and file storage, so team members can work on separate tasks without sharing one messy workspace.

How It Runs

Service	Purpose
platform	Next.js app, APIs, agent loop, and worker
postgres	Database and task queue
sandbox-controller	Creates and removes per-chat and per-project containers
socket-proxy	Gives the controller restricted Docker API access
sandbox	Execution image used by agent sessions

Sandboxes include Python, Node, FFmpeg, ImageMagick, LibreOffice, pandoc (PDF via typst or weasyprint), Playwright with Chromium, OCR tooling, and other common utilities. There is no Java or LaTeX.

Run Locally

npm run docker:dev

Open http://localhost:3000. If no admin account exists, Capka redirects you to setup. After that, add a provider key in Settings -> Providers.

Deploy

On a fresh Linux server, one command installs Docker (if needed), fetches Capka, generates secrets, and brings the stack up:

curl -fsSL https://raw.githubusercontent.com/LyoSU/capka/master/install.sh | sh

It asks how people should reach Capka. No domain? Just press Enter — you get a free HTTPS address with a real certificate (https://<your-ip>.sslip.io). Have a domain? Type it and Caddy provisions HTTPS for it automatically. Either way the installer waits until the app answers and then prints the address to open.

Already own a domain and want to skip the prompt:

curl -fsSL https://raw.githubusercontent.com/LyoSU/capka/master/install.sh | DOMAIN=capka.example.com sh

Already cloned the repo? Run ./scripts/up.sh (or DOMAIN=… ./scripts/up.sh). To upgrade, run sudo ./scripts/backup.sh && sudo ./scripts/update.sh in the install directory (docs/UPGRADE.md). Re-running the installer also upgrades, but to the newest tag of any major, a prerelease included. Re-running up.sh keeps the installed version and reprints the address.

Running on a server that already hosts other sites? The installer notices an existing web server on ports 80/443, or a busy port 3000, stays out of their way, and prints how to front Capka with your own proxy. See docs/DEPLOY.md for Coolify, host nginx, and gotchas.

Requirements

Linux with Docker, on x86_64 or arm64.

Profile	CPU	RAM	Disk
Minimum	1-2 vCPU	2 GB	20 GB
Recommended	2 vCPU	4 GB	40 GB

Use more RAM for concurrent users, large document jobs, or gVisor. The installer checks memory and disk up front and refuses a box that's clearly too small (the sandbox image alone unpacks to ~7.5 GB).

First Run

1. Open the address the installer printed — your domain, the free sslip.io address, or http://<server-ip>:3000. Lost it? Re-run sudo ./scripts/up.sh in the install directory and it prints the address again.
2. Capka redirects to setup if no admin account exists
3. Add provider keys in Settings -> Providers
4. Choose default models
5. Open registration or use approval mode from the admin panel
6. Optional: add a Telegram bot token in Settings -> Agent

Registration is closed by default after setup. Admins can switch it to open or approval mode in Settings -> People -> Sign-in.

Troubleshooting

• Certificate warning right after install. Caddy is still fetching the certificate — wait ~30s and reload; first issuance can take a minute.
• Can't reach the address at all. Open the needed ports in your cloud provider's firewall / security group — 80 and 443 for HTTPS, or your app port for plain HTTP. This is the most common cause on a fresh VPS.
• It skipped HTTPS / "port 80 in use". Another web server is already on this box; Capka runs on http://127.0.0.1:<port>. Point your existing proxy at it and set PUBLIC_URL (see docs/DEPLOY.md).
• Reinstalling and the database won't start. A regenerated password is repaired automatically. Only if Postgres itself is corrupt: docker compose down -v wipes the database volume and starts clean — this deletes chats and settings.
• See what's happening. In the install directory: docker compose ps, and docker compose logs platform (or sandbox-controller).

Security Short Version

Sandboxes are unprivileged containers with dropped Linux capabilities. They see only their own workspace directory plus the owning user's own /shared store; host folders are mounted only if an admin turns on folder access (off by default, optionally limited to the roots in SANDBOX_MOUNT_ALLOW). The controller reaches Docker through socket-proxy, not the raw Docker socket.

Sandbox internet access is controlled in Settings -> Security -> Network ("Let code reach the internet"). When enabled, Capka blocks private ranges and cloud metadata endpoints.

For untrusted or multi-tenant use, read SECURITY.md. Turn on gVisor for kernel-level sandbox isolation:

sudo sh scripts/install-gvisor.sh   # installs runsc, enables userns-remap
# restart Docker, then set in .env:
SANDBOX_RUNTIME=runsc

On a host that already runs Capka, back up first (Backup & restore): with userns-remap on, Docker keeps containers, images and volumes in a separate storage root, so the database volume seems to vanish and Capka comes back as a fresh install, and files under ./data keep owners the remapped containers may not be allowed to write. Restore the backup after the switch.

The default runc is the right answer while you know who runs code; gVisor is the answer when you don't. It is a trade, not a free upgrade — a root install on the host, slower syscall-heavy work, and a share of the sandbox's PID budget: what gVisor costs.

For the strongest boundary, also run Docker rootless (a container escape then lands unprivileged); it needs one extra DOCKER_SOCKET setting — see SECURITY.md.

Useful Links

• docs/DEPLOY.md: production deploys and Coolify
• SECURITY.md: threat model and hardening
• docs/DEVELOPMENT.md: local development
• docs/UPGRADE.md: upgrade notes
• CONTRIBUTING.md: contributions and CLA

License

Capka is licensed under the GNU AGPL-3.0. If you run a modified version as a public network service, the AGPL source-availability terms apply.