Setup

If you’re reading this, you’re about to get Portuni running on your machine. This page walks you through the install, the environment variables, and starting the server – so that by the end, your AI agents have something to talk to.

Two install paths: the desktop app (recommended) or the standalone CLI server (for contributors and CI).

Install the desktop app (recommended)

Portuni.app is a Tauri-built macOS application that bundles the MCP server as an embedded sidecar. You install one thing; you get the UI, the server, and the integration glue.

1. Open the GitHub releases page.
2. Download the DMG for your CPU — aarch64 for Apple Silicon, x86_64 for Intel.
3. Open the DMG and drag Portuni.app to /Applications/.
4. Launch it. First run: see Desktop App for the Turso setup gate and the workspace-root prompt.

The app uses its own port (default 4011 for the sidecar, surfaced via localhost:4011 for any MCP client you want to point at it). You don’t need to clone the repo, install Node, or keep a tmux session running — the app handles all of that.

The app is currently macOS only. For Linux/Windows, use the CLI install below; native bundles for other platforms aren’t on the near roadmap.

Install the CLI / standalone server

Use this path if you want to contribute to Portuni, run it on Linux/Windows, run multiple instances side by side, or deploy it to a server.

Before you start

• Node.js 20 or newer
• Varlock for secrets management
• A Turso account if you’re setting up the team or production mode. Turso is the shared cloud database that lets multiple people and multiple agents work against the same graph – it’s where Portuni is designed to live long-term.
• No database account needed for a solo or testing setup: Portuni quietly falls back to a local SQLite file. Good for trying things out, or for working on the server itself. Plan to move to Turso as soon as more than one person needs the graph.

Install

git clone https://github.com/honzapav/portuni
cd portuni
npm install
npm run build

Environment

The CLI server uses Varlock for credentials. The authoritative list of variables lives in .env.schema; here’s the quick rundown:

Variable	When you need it	What it’s for
PORTUNI_WORKSPACE_ROOT	always	Root directory for your local mirror folders, e.g. ~/Workspaces/portuni
TURSO_URL	team setup	Turso database URL. Leave empty to fall back to local SQLite at ./portuni.db
TURSO_AUTH_TOKEN	team setup	Turso auth token. Set alongside TURSO_URL
PORTUNI_USER_EMAIL	optional	Solo-user email in single-user mode. Defaults to solo@localhost
PORTUNI_USER_NAME	optional	Solo-user display name. Defaults to Solo User
PORT	optional	HTTP port for the MCP server. Default 4011

The desktop app handles these via its in-app settings UI (Turso credentials, workspace root) — you do not edit .env.local for daily use of Portuni.app.

Two ways to run it

• Team / production (Turso). Set TURSO_URL and TURSO_AUTH_TOKEN. The database lives in Turso’s libsql cloud, so every teammate and every agent connects to the same graph. This is where Portuni delivers its core value – a shared, organization-wide knowledge graph. Move here as soon as more than one person is involved.
• Solo / testing (local SQLite). Leave both Turso variables empty. Portuni creates ./portuni.db in the project directory on first start. Good for trying things out or working on the server itself, but it doesn’t scale past one machine – treat it as a stepping stone, not a home.

Running the server

npx varlock run -- npm start       # production
npx varlock run -- npm run dev     # development

Portuni listens on http://localhost:4011 by default. Set PORT to change it.

If you’d like it to stay running in the background (so it survives closing the terminal), drop it into a tmux session:

tmux new-session -d -s portuni -c /path/to/portuni 'npx varlock run -- npm run dev'

Running multiple instances

Portuni instances are independent: each has its own database, its own workspace root, and its own port. To run more than one side by side:

1. Clone the repo in a second location (e.g. /path/to/portuni-alt). Each clone keeps its own local SQLite file.
2. Give each instance distinct values in its .env.local:
   • PORT – pick a different port, e.g. 3002
   • PORTUNI_WORKSPACE_ROOT – pick a different workspace root
   • optionally PORTUNI_USER_EMAIL / PORTUNI_USER_NAME
3. Start each in its own tmux session with a distinct session name, so you can find them again.

Each running instance is a separate MCP endpoint. See the MCP Clients section for how to register multiple endpoints with your AI CLI.

Check it’s alive

curl http://localhost:4011/health
# {"status":"ok"}

Running the test suite

npm test

Portuni uses Node.js’s built-in test runner (node:test). No external framework to install.

Connect a client

Portuni on its own is a passive server – nothing happens until an MCP client connects. Head to MCP Clients for per-client instructions, including how to give each client access to your mirror folders. The desktop app’s own UI counts as a client too — see Desktop App.