lakuna

The Lakuna local agent. A small daemon you run on your own machine or server, co-located with your own local model (Ollama, llama.cpp, vLLM, LM Studio, Jan.ai, or anything that speaks the OpenAI-compatible chat completions API). It answers requests from your local model first and only calls the hosted Lakuna cloud API when it has to.

This is a separate Node package from the Lakuna web app. It installs and runs on your infrastructure; the web app is the hosted cloud tier it talks to.

How it fits together

your backend  --POST /route-->  lakuna  --localhost-->  your local model
                                     |
                                     | (only on escalation / usage report)
                                     v
                             Lakuna cloud API (hosted)

Your backend calls the agent instead of calling an LLM provider directly. For each request the agent:

1. Asks the cloud API for strategies from similar past cases (best-effort) and injects any it gets into the local model's system prompt.
2. Calls your local model.
3. Runs a fast, deterministic quality gate on the output.
4. If it passes, returns a local result and reports the success to the dashboard (counts and latency only, never your text). If it fails or the local model is unreachable, it escalates to the cloud API and returns that cloud result.

Text only leaves your machine on a cloud escalation, or as the query sent to the strategies endpoint in step 1. A request your local model answers on its own never has its answer leave your infrastructure.

Install

Quickstart (recommended)

The install script detects your OS and Node.js version, builds the agent, and puts the lakuna binary on your PATH.

TODAY (pre-publish, real): lakuna is not on the public npm registry yet, so you install from a clone of this repo. From the repo root:

sh agent/scripts/install.sh

You can also pipe it, as long as you run it from inside a clone (it looks for the agent folder), or point it at the folder with LAKUNA_AGENT_DIR:

cat agent/scripts/install.sh | sh
# or from anywhere:
LAKUNA_AGENT_DIR=/path/to/lakuna/agent sh agent/scripts/install.sh

EVENTUAL (once published, not yet live): the whole thing becomes a single line, with no clone needed, and the curl one-liner in the script header starts to work:

npm install -g lakuna
# or:  curl -fsSL https://your-host/install.sh | sh

The script is safe to re-run. When it finishes it points you at lakuna --setup to configure the agent interactively.

Manual install

If you would rather do it by hand, from this directory:

npm install
npm run build
npm install -g .   # puts the lakuna binary on your PATH

Configuration

All configuration is via environment variables.

| Variable | Required | Default | Description | | --------------------- | -------- | -------------------------------- | -------------------------------------------------------- | | LAKUNA_API_KEY | yes | - | Your Lakuna API key. The agent refuses to start without it. | | LOCAL_MODEL_BASE_URL| no | http://localhost:11434/v1 | OpenAI-compatible base URL of your local model server. | | LOCAL_MODEL_NAME | no | llama3.1 | Model name to request from that server. | | LAKUNA_API_URL | no | https://lakuna.example.com/api | Base URL of the hosted Lakuna cloud API. Set this to your deployment. | | AGENT_PORT | no | 8787 | Port the agent's HTTP server listens on. | | AGENT_HOST | no | 127.0.0.1 | Host/interface to bind. |

Get an API key by signing in to your Lakuna deployment's dashboard (/dashboard). It mints one per account on first visit and lets you copy or regenerate it; there is no anonymous, unauthenticated way to mint a key, since a key is tied to your signed-in Clerk account.

Run

Development (no build step, runs the TypeScript directly):

LAKUNA_API_KEY=sk-lakuna-... \
LAKUNA_API_URL=https://your-lakuna-deployment/api \
LOCAL_MODEL_BASE_URL=http://localhost:11434/v1 \
LOCAL_MODEL_NAME=llama3.1 \
npm run dev

Production (after npm run build):

LAKUNA_API_KEY=sk-lakuna-... \
LAKUNA_API_URL=https://your-lakuna-deployment/api \
npm start
# or, if installed globally:
LAKUNA_API_KEY=sk-lakuna-... lakuna

On start it prints the configured local model target and the port it is listening on. If LAKUNA_API_KEY is missing it prints a single clear line and exits with code 1 rather than crashing.

Example request

Once it is running:

curl -X POST http://localhost:8787/route \
  -H "Content-Type: application/json" \
  -d '{"text":"Met with the design team. We agreed to ship the new onboarding flow by Friday and Sam will draft the copy."}'

Response (RouteResult):

{
  "summary": "...",
  "tier": "local",
  "localSource": "browser",
  "escalated": false,
  "costEstimateUsd": 0,
  "latencyMs": 812
}

tier is local when your model handled it, cloud when it was escalated (in which case escalated is true and escalationReason explains why).

There is also a GET /health endpoint that returns { "ok": true, "localModel": ... } for readiness probes.

Wiring it into your backend

Point your application at the agent instead of at an LLM provider. Wherever you would have called, say, an OpenAI or Anthropic endpoint to summarize text, call the agent:

const res = await fetch("http://localhost:8787/route", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ text: notes }),
});
const result = await res.json(); // RouteResult
console.log(result.summary, "served by", result.tier);

Run the agent as a long-lived process next to your app (systemd, a container sidecar, pm2, etc.) so the local model call stays on localhost with no network hop.