# Capka full documentation > Capka is an open-source, self-hosted AI workspace with persistent files and a separate Linux sandbox for every chat. Canonical index: https://capka.app/llms.txt Repository: https://github.com/LyoSU/capka --- # Capka Documentation Source: https://capka.app/docs/ Capka is an open-source, self-hosted AI workspace for completing file-based work. Each chat gets a persistent workspace and an isolated Linux sandbox where the agent can use Python, Node.js, LibreOffice, FFmpeg, Playwright and OCR. ## What Capka is Capka is designed for work that should end in a file, not only a chat reply. Attach spreadsheets, documents, archives or code, describe the outcome, and the agent can return a report, a cleaned dataset, a converted document or a patch. You run Capka on your own Linux server and connect model providers you choose. That can include Anthropic, OpenRouter, an OpenAI-compatible API, or local models through Ollama. Capka itself has no hosted cloud and adds no per-seat fee. ## How the system is organized - A separate, unprivileged Linux sandbox for every chat. - Persistent files that remain available between agent steps and browser sessions. - Private chats and files for each user on a shared team instance. - Administrative controls for roles, model access, policies, audit events and token spend. - Skills, MCP connectors and marketplace bundles for reusable workflows and external services. ## Start here - [Install Capka](/docs/installation/) on a Linux server with Docker. - [Connect cloud or local models](/docs/models/). - Understand [sandbox isolation](/docs/sandbox/) and the [security model](/docs/security/) before opening an instance to untrusted users. - Review how [files persist](/docs/files/) and how team [administration](/docs/admin/) works. --- # Install and Self-Host Capka Source: https://capka.app/docs/installation/ Capka runs on a Linux server with Docker. A small VPS is enough for an initial deployment; no Kubernetes cluster or external managed service is required. ## System requirements - Linux on x86_64 or arm64. - Docker; the installer can install it when it is missing. - At least 2 GB RAM and 20 GB of disk; 4 GB RAM is recommended. - A model API key, an OpenAI-compatible endpoint, or a reachable Ollama instance. ## Run the installer Inspect the [installer source on GitHub](https://github.com/LyoSU/capka/blob/master/install.sh), then run: ```bash curl -fsSL https://raw.githubusercontent.com/LyoSU/capka/master/install.sh | sh ``` The installer checks Docker, pulls the prebuilt stack, creates secrets and starts Capka. Without a domain it can offer a free HTTPS address at `.sslip.io`; with a domain, Caddy provisions HTTPS automatically. Installation details can change between releases, so the repository installer is the source of truth. ## First run - Open the URL printed by the installer. - Create the first administrator account. - Connect a model provider or a local model endpoint. - Create a chat, attach a small file and confirm that the result can be downloaded. > Keep registration closed until model access, sandbox networking and administrator policies match the trust level of your users. ## Updates and support Use the instructions attached to the current [Capka release](https://github.com/LyoSU/capka/releases). Production pull-only deployments should track the `stable` branch or pin `CAPKA_VERSION`; `master` is the development tip. Back up first because database migrations are forward-only. Report reproducible problems in [GitHub Issues](https://github.com/LyoSU/capka/issues). --- # Configure a Capka Instance Source: https://capka.app/docs/configuration/ Configuration starts with five decisions: who can join, which models they can use, where files live, what sandboxes may reach, and which agent actions require approval. ## Recommended configuration order - Create and secure the administrator account. - Add one model provider and test it before adding more. - Confirm persistent storage and your backup policy. - Set allow, ask or deny rules for sensitive agent actions. - Choose whether sandbox workloads may reach the public internet or internal services. - Invite users only after the isolation and access settings have been reviewed. ## Secrets and model keys Capka can use a shared provider key for the instance or separate keys per user. Keep provider credentials in the instance configuration rather than in chat messages or workspace files. Users should receive only the providers and capabilities they need. When a model is hosted outside your infrastructure, task content needed by that model can leave the server. Use a local model when the full workflow must remain inside your network. ## Policies and connectors Skills and MCP connectors can extend Capka with internal procedures and external services. Review the hosts, commands and requested secrets shown before installing a marketplace bundle. An update that broadens access should receive the same review as a new integration. > The exact configuration surface evolves with releases. Check the current release notes and repository before automating deployment-specific settings. --- # Capka Environment Variables Source: https://capka.app/docs/environment/ Use environment variables for deployment-level settings that should not live in the admin interface: root secrets, host routing, hard security ceilings, resource budgets, retention and observability. ## Before editing .env The supported self-host path is `npm run up` or `scripts/up.sh`. On first run it creates strong values for the required secrets and never overwrites values already present in `.env`. Local development through `npm run docker:dev` supplies loopback-only defaults and does not require copying the production file. For a direct production `docker compose up`, Coolify or another orchestrator, set the required secrets yourself. Keep `.env` outside version control and store the same values in a password manager or secret store before the server becomes important. ## Applying changes safely - Back up the database and persistent data before changing storage, retention or version settings. - Run `docker compose up -d` after editing `.env`; use `docker compose ps` and service logs to confirm a healthy restart. - Change one risk-sensitive group at a time: secrets, routing, sandbox security, then resource tuning. - Never rotate `CAPKA_MASTER_KEY` casually: it is the root key for encrypted provider credentials. > The list below covers operator-facing variables from the current `.env.example`, plus `OTEL_EXPORTER_OTLP_HEADERS` and the explicit insecure master-key fallback referenced by it. Internal service-to-service variables are intentionally not deployment knobs. --- # Cloud and Local Models in Capka Source: https://capka.app/docs/models/ Capka is model-provider independent: use a provider you already pay for, an OpenAI-compatible endpoint, or local models served through Ollama. ## Supported connection patterns - Anthropic models with your own API key. - OpenRouter with your own account and billing. - OpenAI-compatible endpoints, including compatible self-hosted gateways. - Local models exposed through Ollama. ## Choose a model for the work File-heavy jobs may need long context, reliable tool use and enough output capacity to plan multi-step work. A smaller local model can be a good fit for private or routine tasks, while more complex document analysis or code changes may benefit from a stronger cloud model. Validate the complete workflow rather than a single chat response: attach a representative file, let the agent use its tools, and inspect the returned artifact. ## Privacy and cost Uploads and result files stay on the Capka instance. Content required for inference is sent to the model provider you configure. With a local model, inference can stay entirely inside your infrastructure. Capka adds no model markup or per-seat subscription. Provider usage and server resources are billed directly to you, and administrators can see token spend by user without reading private conversations. --- # Linux Sandbox Isolation in Capka Source: https://capka.app/docs/sandbox/ Every Capka chat gets its own Linux sandbox. The agent can run code and use installed tools without sharing a working directory or execution context with another chat. ## How sandbox isolation works A sandbox contains the chat workspace, tools and code execution environment. Containers are never privileged, use `no-new-privileges`, drop Linux capabilities, and run agent commands as UID `1000:1000`. They cannot access the host filesystem. Separate users receive separate workspace mounts, and a session only mounts the requesting user's paths. Workspace files persist between steps and sessions, while task execution continues on the server if the browser tab is closed. This lets long-running file jobs finish without keeping a client connection open. ## What can run inside a sandbox - Python, Node.js and Java programs. - Document and spreadsheet work through LibreOffice. - Audio and video processing through FFmpeg. - Browser automation through Playwright. - OCR, ImageMagick, Pandoc, Graphviz and other packages required by a task. ## Hardening for untrusted users An unprivileged runc container is the default boundary for trusted users. Public or multi-tenant deployments should add gVisor for a user-space kernel and rootless Docker so a container escape does not equal host root. Sandboxes also have memory, CPU, PID and file-size limits. Network egress is off in a fresh instance until an administrator enables it; deployments can hard-disable it or restrict it to an explicit host allowlist. Read the [security documentation](/docs/security/) and the repository [SECURITY.md](https://github.com/LyoSU/capka/blob/master/SECURITY.md) before exposing an instance publicly. > Permission previews for skills and connectors provide informed consent; they do not replace sandbox isolation. --- # Persistent Files and Agent Tools Source: https://capka.app/docs/files/ Capka treats files as both the input and the finished result. A chat keeps its own persistent working directory so the agent can inspect, transform and return artifacts across multiple steps. ## File-oriented workflows - Turn a ZIP of source material into a PDF report and an Excel workbook. - Clean, join or analyze CSV and spreadsheet data. - Convert or edit office documents with LibreOffice. - Inspect a codebase and return a patch. - Process media with FFmpeg or extract text with OCR. ## Persistence and separation Files remain in the chat workspace between agent steps and browser sessions. Closing the tab does not cancel server-side work. When the task finishes, its output remains available in the same chat. Each chat has separate storage. A job cannot read another chat's working files, and one user's files do not appear in another user's account. ## Tools and package installation The sandbox provides a real Linux environment rather than a simulated code interpreter. The agent can run Python and Node.js, use browser automation, and install packages needed for a task within the sandbox boundary. > Treat downloaded packages, documents and websites as untrusted input. Use sandbox network policy and approval rules appropriate to your deployment. --- # Capka Security Model Source: https://capka.app/docs/security/ Capka separates the execution boundary, the user privacy boundary and the permission layer. They solve different risks and should be configured together. ## Execution boundary Every chat runs in a separate unprivileged Linux sandbox that cannot access the host filesystem. Linux capabilities are dropped, agent commands run as UID `1000:1000`, and memory, CPU, PID, file-size and workspace quotas limit resource use. Workspaces are separated by container and bind mount. For higher-risk deployments, combine gVisor with rootless Docker and restrict network egress. ## User and administrator privacy Files and conversations are private per user. Administrators manage access, roles and token spending, but other people's conversations and files do not appear in the administration panel. Registration is closed by default. Open it only when the deployment is intended for public access and the sandbox has been hardened for untrusted users. ## Permissions, integrations and auditability Before a marketplace bundle is installed, Capka shows which hosts its connectors contact, which commands run in the sandbox and which secrets it requests. Updates that widen access remain blocked until accepted. Administrators can use allow, ask or deny policies for agent actions and review the audit log afterwards. These controls reduce accidental access; the sandbox remains the primary technical boundary for executed code. ## Report a vulnerability Follow the private reporting instructions in the repository [security policy](https://github.com/LyoSU/capka/blob/master/SECURITY.md). Do not publish an unpatched vulnerability in a public issue. --- # Teams and Administration Source: https://capka.app/docs/admin/ One Capka instance can serve a team while keeping each person's files and chats private. Administration focuses on access and operations, not reading user conversations. ## What administrators manage - User access and roles. - Shared or per-user model credentials and available providers. - Token spending by person. - Allow, ask or deny rules for agent capabilities. - Sandbox network access and installed integrations. - Audit events for operational review. ## What stays private User workspaces, uploaded files and conversation histories remain separate. The administration panel exposes operational information such as roles and spend, not the contents of another person's work. ## A safe rollout sequence - Start with a small group and one approved model provider. - Test representative file workflows and confirm result downloads. - Review connector permissions and sandbox network access. - Set usage expectations and monitor token spend. - Back up persistent instance data before expanding access or updating. --- # Capka Troubleshooting Source: https://capka.app/docs/troubleshooting/ Diagnose Capka from the outside in: server and containers first, then the model connection, then the individual sandbox and task. ## The instance does not open - Confirm the server is running and has free disk space and memory. - Confirm Docker is active and the Capka containers are healthy. - Check the reverse proxy, DNS and TLS configuration used for the instance URL. - Review the installation or update output for the first failing step. ## A model does not respond - Verify the provider key, endpoint URL and selected model name. - For an OpenAI-compatible endpoint, test that it is reachable from the Capka server. - For Ollama, confirm the model is loaded and the Ollama endpoint is reachable from the application network. - Try a small text request before testing a long file workflow. ## A sandbox task fails - Check whether the task exceeded available memory or disk space. - Confirm sandbox network policy allows any host the task must reach. - Retry with a small representative file to separate input problems from infrastructure problems. - Record the release version, reproduction steps and relevant logs before opening a GitHub issue. ## Get help Search existing [GitHub Issues](https://github.com/LyoSU/capka/issues) before filing a new report. Include the Capka release, server architecture, expected result, actual result and the smallest safe reproduction. Never post API keys, private files or other secrets.