Installation

Four ways to run Karpa. Pick whatever fits your workflow.

Option 1: Development

The simplest way — 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 2: 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

Option 3: Docker Pull

Pull the latest image from GitHub Container Registry.

docker run -p 7250:7250 ghcr.io/sudoeren/karpa:latest

For local LLM providers (LM Studio, Ollama), add the host gateway:

docker run -p 7250:7250 --add-host=host.docker.internal:host-gateway ghcr.io/sudoeren/karpa:latest

Option 4: Custom Docker Build

Build your own image.

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

The --add-host flag lets the container reach your local LLM provider running on your host.

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
│   │   └── api/          # API routes (translate, models, test-connection)
│   ├── components/       # React components
│   ├── contexts/         # React contexts (language, onboarding)
│   ├── hooks/            # Custom hooks (use-mobile, use-tts)
│   └── lib/              # Utilities, providers, translations
├── public/               # Static assets (logo, icons)
├── Dockerfile            # Docker config
└── docker-compose.yml    # Docker Compose

Once installed, head over to configuration to wire up your provider, or use the in-app Settings.

Uninstall

Run the script inside the karpa folder:

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

This stops the container, removes the image and volumes, and deletes the project folder. Clear browser data (history, favorites, settings, API key) manually from Settings → Data.