playbooks

home / skills / openclaw / skills / konto

konto skill

/skills/angelstreet/konto

This skill helps you deploy and run Konto locally, guiding setup, troubleshooting, and initial usage for a smooth starter experience.

npx playbooks add skill openclaw/skills --skill konto

Review the files below or copy the command above to add this skill to your agents.

Files (2)
SKILL.md
4.3 KB
---
name: konto-deploy
description: "Deploy and run Konto (personal finance dashboard) locally. Use when setting up a new Konto instance, troubleshooting installation, or helping users get started with Konto."
metadata:
  openclaw:
    emoji: "🦎"
    requires:
      bins: ["node", "npm", "openssl"]
    install:
      - id: clone
        kind: git
        repo: https://github.com/angelstreet/konto
        branch: main
        label: "Clone Konto repository"
      - id: deps
        kind: script
        cwd: "konto"
        run: "npm install"
        label: "Install dependencies"
      - id: env
        kind: script
        cwd: "konto"
        run: |
          if [ ! -f backend/.env ]; then
            cp .env.example backend/.env
            KEY=$(openssl rand -hex 32)
            sed -i "s/^DB_ENCRYPTION_KEY=$/DB_ENCRYPTION_KEY=$KEY/" backend/.env
            echo "Created backend/.env with generated encryption key"
          else
            echo "backend/.env already exists, skipping"
          fi
        label: "Configure environment"
---

# Konto — Local Deployment

Personal & professional finance dashboard. Bank sync, crypto, investments, budget, tax tools.

## Prerequisites

- Node.js 18+ and npm 9+
- `openssl` (for encryption key generation)

## Installation (3 commands)

```bash
git clone https://github.com/angelstreet/konto.git
cd konto
npm install
```

## Configuration

```bash
# Create env from template
cp .env.example backend/.env

# Generate and set encryption key
KEY=$(openssl rand -hex 32)
sed -i "s/^DB_ENCRYPTION_KEY=$/DB_ENCRYPTION_KEY=$KEY/" backend/.env
```

### Minimal config (works immediately)
Only `DB_ENCRYPTION_KEY` is required. Everything else is optional.

### Optional integrations
| Feature | Env vars | Sign up |
|---------|----------|---------|
| Bank sync | `POWENS_CLIENT_ID`, `POWENS_CLIENT_SECRET`, `POWENS_DOMAIN` | [powens.com](https://powens.com) |
| Production auth | `CLERK_SECRET_KEY`, `VITE_CLERK_PUBLISHABLE_KEY` | [clerk.com](https://clerk.com) |
| Coinbase | `COINBASE_CLIENT_ID`, `COINBASE_CLIENT_SECRET` | [developers.coinbase.com](https://developers.coinbase.com) |
| Google Drive | `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET` | [console.cloud.google.com](https://console.cloud.google.com) |

## Running

```bash
# Start both frontend + backend
npm run dev
```

- Frontend: http://localhost:3004/konto/
- Backend API: http://localhost:5004/api/
- Login: `user` / `user` (local dev, no Clerk needed)

## Sandbox / Demo Mode

Konto auto-seeds demo data for the default user:
- Bank accounts (checking, savings, investment)
- Crypto wallets (BTC, ETH, XRP)
- Investment positions (PEA, Assurance Vie, PER)
- 14 months of transaction history
- Real estate and vehicle assets

Just log in and explore — no external API keys needed.

## Building for Production

```bash
npm run build
# Frontend: serve frontend/dist/ as static files
# Backend: node backend/dist/index.js
```

### Vercel deployment
```bash
cd frontend && vercel
cd backend && vercel
```

## Ports

| Service | Port | URL |
|---------|------|-----|
| Frontend (dev) | 3004 | http://localhost:3004/konto/ |
| Backend API | 5004 | http://localhost:5004/api/ |

## Troubleshooting

| Problem | Solution |
|---------|----------|
| `ENCRYPTION_KEY` error | Run `openssl rand -hex 32` and set in `backend/.env` |
| Port 3004 in use | `lsof -i :3004` to find process, kill or change `VITE_DEV_PORT` |
| Port 5004 in use | Change `PORT` in `backend/.env` |
| Clerk errors locally | Leave `CLERK_SECRET_KEY` empty — local dev bypasses Clerk |
| Empty dashboard | Log in as `user/user` — demo data seeds on first backend start |
| Bank sync not working | Requires Powens API keys (optional for demo) |

## Tech Stack

| Layer | Tech |
|-------|------|
| Frontend | React 18 + TypeScript + Vite + Tailwind CSS + Recharts |
| Backend | Hono + TypeScript + Node.js |
| Database | SQLite (local) or Turso (cloud) |
| Auth | Clerk (optional) |

## API Endpoints (key ones)

| Endpoint | Description |
|----------|-------------|
| `GET /api/bank/accounts` | Bank accounts |
| `GET /api/investments` | Investment positions |
| `GET /api/transactions` | Transaction history |
| `GET /api/companies` | Companies (pro) |
| `GET /api/patrimoine/summary` | Net worth summary |
| `GET /api/preferences` | User preferences |

Full API docs: `docs/API.md` in the repo.

Overview

This skill deploys and runs Konto, a personal finance dashboard, locally for development, testing, or demo purposes. It guides you through prerequisites, installation, environment configuration, running dev servers, and producing a production build. Use it to quickly get a seeded demo instance or to troubleshoot common local setup issues.

How this skill works

The skill clones the Konto project, installs Node dependencies, and configures a minimal environment including a DB encryption key. It starts both frontend and backend in development mode (dev servers on ports 3004 and 5004) and auto-seeds demo data for a local default user. Optional integrations (bank sync, Coinbase, Google, Clerk auth) can be enabled by setting corresponding environment variables.

When to use it

  • Setting up a new local Konto instance for development or evaluation.
  • Troubleshooting installation errors, port conflicts, or missing encryption keys.
  • Demonstrating features locally without external API keys using demo mode.
  • Building frontend and backend artifacts for a local production test.
  • Deploying frontend/backend to Vercel for quick staging deployments.

Best practices

  • Generate a secure DB_ENCRYPTION_KEY with openssl rand -hex 32 and add it to backend/.env before running.
  • Use the provided demo user (user/user) to verify demo data seeded correctly on first start.
  • Resolve port conflicts before starting by checking lsof -i :<port> or changing VITE_DEV_PORT / PORT in env files.
  • Keep optional integration keys out of public repos; store them in a secure environment for production.
  • Build frontend and backend separately for production and serve static frontend files from a proper web server.

Example use cases

  • Quickly spin up a local Konto demo to show finance features to a stakeholder without external API keys.
  • Reproduce and fix a reported bug by running the same dev servers and inspecting API endpoints.
  • Test a custom UI tweak in React/TypeScript and validate API interactions against the seeded demo data.
  • Prepare a staging deployment by building frontend and backend bundles and deploying to Vercel.
  • Validate third-party integrations (Coinbase, Powens, Google) by setting provider credentials in backend/.env

FAQ

What is the only required environment variable for minimal setup?

DB_ENCRYPTION_KEY is the only required variable; generate it with openssl rand -hex 32 and place it in backend/.env.

How do I access the app and API locally?

Frontend runs at http://localhost:3004/konto/ and the backend API at http://localhost:5004/api/ after npm run dev.

Why is my dashboard empty after starting?

Log in as user/user to access auto-seeded demo data; the demo dataset seeds on first backend start.