Install Topos

Install Topos

Topos runs on your machine. Installing it means putting a node — your Topos Engine and Topos Database — on your own hardware, then connecting it to your account so the web app can reach it.

There are two ways to install, and they end in the same place.

• Mac app — a menu-bar app that installs and manages the node for you. Recommended.
• Terminal — the same node, installed with uv. For developers, and for machines you administer over SSH.

Windows is not available yet.

---

Before you start

• macOS 13 Ventura or later for the Mac app.
• About 4 GB of free disk space. A first run downloads roughly 900 MB of engine and 2.9 GB of language models.
• A Topos account. Setup runs from the Create Topos screen in the web app.

A first install takes several minutes, most of it downloading. That is normal, and both paths show you progress while it happens.

---

Install with the Mac app

Start in the web app: open Create Topos and keep that page open — it is what finishes setup once your machine connects.

1. Download

Click Download on the Create Topos screen. You get a Topos.dmg, signed and notarized by Dialogues Technologies Incorporated.

2. Install

Open the .dmg, drag Topos into your Applications folder, then launch it from Applications. A Topos icon appears in your menu bar — that icon is the app; there is no window.

The first time you open it, macOS confirms you want to run an app downloaded from the internet. It will name Dialogues Technologies Incorporated. If it instead warns that the developer cannot be verified, you have an unsigned build — download again from the Create Topos screen.

3. Connect

Click Connect this Mac in the browser. Your browser asks permission to open Topos; allow it. The app receives a one-time pairing code, stores your key, and starts your node.

The code is single-use and expires after ten minutes. Your key never travels through the URL.

4. Prepare

Your node installs its engine and downloads its language models. Watch the menu-bar icon — it reports each phase and the megabytes as they land:

Installing the Topos engine — 340 MB of about 900 MB
Topos Node — downloading models, 1.2 GB so far

You can use other tabs while this runs, but leave the Create Topos page open. Your Topos is created the moment your node connects, and that page is what creates it.

When it finishes, the browser moves to your new Topos automatically. It is named after your machine.

---

Install from the terminal

Choose the Terminal tab on the Create Topos screen. It shows three commands with your key already filled in:

uv tool install topos-node
topos-node --set-topos-key "<your key>"
topos-node

No uv yet — macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

irm https://astral.sh/uv/install.ps1 | iex

The node prints its progress as it starts. Once it reaches the control plane, the Create Topos page finishes setup exactly as it does for the app.

Your key is written to ~/.topos/.env with owner-only permissions. Everything your node stores — the database, ingested files, logs — lives under ~/.topos.

---

What a first run does

1. Installs the engine, about 900 MB.
2. Starts your node and connects it to the control plane.
3. Downloads roughly 2.9 GB of language models used to sanitize data before anything is stored.

Step 3 runs in the background. Your node is connected and your Topos is usable before it finishes; ingestion waits for the models.

Later installs on the same machine are much faster — both downloads are cached.

---

Disconnecting or moving a Mac

One machine runs one Topos. To start over, or to point this Mac at a different Topos, use Disconnect this Mac… in the menu-bar icon.

It releases the pairing and stops the node. Nothing is deleted — your data stays in ~/.topos, and reconnecting to the same Topos picks up where you left off. Afterwards the menu offers Connect this Mac… to pair again.

Topos deliberately refuses to silently re-pair a machine that is already connected, so a second setup attempt tells you what is happening instead of quietly replacing your existing connection.

---

If something goes wrong

The menu bar says "starting…" for a long time. On a first run this is the engine install. Open the icon — it names the phase and the megabytes so far.

The browser never leaves "Connect this Mac". Your node has not reached the control plane yet. If you closed the Create Topos page before it connected, reopen Create Topos and connect again.

Clicking Connect does nothing. Your browser may have blocked the request to open Topos. Look for a permission prompt, allow it, and click again.

macOS will not open the app. Make sure you dragged Topos into Applications and are launching it from there, not from the mounted disk image.

You want to check on the node directly. Its log is at ~/.topos/logs/node.log, and Show Logs in the menu opens it.