Installation

Five ways to run Karpa: desktop installers, dev setup, Docker Compose, Docker pull, and custom build.

Pick whatever fits your workflow. All options run the same app; the desktop installers are the simplest for everyday use.

Option 1: Desktop App (recommended)

Download the latest installer from Releases.

Platform	Package
Windows	`.exe` (NSIS installer) or `.msi`
macOS	`.dmg` (Intel and Apple Silicon)
Linux	`.deb`, `.AppImage`, or `.rpm`

Build from source

git clone https://github.com/sudoeren/karpa.git
cd karpa
npm install
npm run desktop:build

For development with hot reload:

npm run desktop:dev

Option 2: Development

Clone and go:

git clone https://github.com/sudoeren/karpa.git
cd karpa
npm install
npm run dev

Open http://localhost:7250 and start translating.

Option 3: Docker Compose

Karpa ships with a docker-compose.yml for one-command deployment:

git clone https://github.com/sudoeren/karpa.git
cd karpa
docker compose up -d

The compose file includes a healthcheck on http://localhost:7250 and maps the container to your host so local providers are reachable.

The --add-host flag lets the container reach LM Studio or Ollama running on your host machine. Point Karpa at http://host.docker.internal:1234 (LM Studio) or http://host.docker.internal:11434 (Ollama) in Settings.

Option 5: Custom Docker Build

Build your own image:

docker build -t karpa .
docker run -p 7250:7250 --add-host=host.docker.internal:host-gateway karpa

Project structure

karpa/
├── src/
│   ├── app/               # Next.js App Router
│   │   ├── page.tsx      # Main translator
│   │   ├── history/      # Translation history
│   │   ├── favorites/    # Saved translations
│   │   ├── settings/     # App settings
│   │   └── about/        # About page
│   ├── components/       # React components
│   ├── contexts/         # React contexts (language, onboarding)
│   ├── hooks/            # Custom hooks (use-mobile, use-tts)
│   └── lib/              # Utilities, providers, translations
├── public/               # Static assets (logo, icons)
├── src-tauri/            # Tauri desktop app (Rust)
│   ├── src/              # Rust source
│   ├── icons/            # App icons
│   ├── Cargo.toml
│   └── tauri.conf.json
├── Dockerfile            # Docker config
└── docker-compose.yml    # Docker Compose

Once installed, configure your provider in the in-app Settings or follow the provider guides.

Uninstall

Desktop App

Windows: Settings → Apps & features, or re-run the installer.
macOS: drag the app from Applications to Trash.
Linux: remove the package (sudo dpkg -r karpa for .deb) or delete the AppImage file.

Docker installs

Run the uninstall script from inside the cloned karpa folder:

./uninstall.sh        # macOS / Linux
uninstall.bat         # Windows

This stops the container, removes the image and volumes, and deletes the project folder.

To wipe app data (history, favorites, settings), clear it first from Settings → Data, or see Data & Storage.