Skip to content
mash

Search across your machines

A shared index lets your laptop find chats indexed on your desktop, and vice versa. Each machine keeps its own local history and search service, then publishes to one authenticated Mash server. Machines in the same group can search each other’s published history.

For one machine, skip this setup: local search already works offline.

What you need

Section titled “What you need”
  • Mash installed and initialized on each publishing machine.
  • A local Qdrant instance on each machine.
  • A server running the same Mash release, with Qdrant 1.20+ and persistent storage.
  • An HTTPS endpoint for the Mash API, or a trusted private network.

Run Qdrant directly on each host. The official Docker image is another option; an existing Qdrant service also works.

Run the API on the host with mash-server, as shown below. It ships with mash at the same release version; mash remains the local CLI and MCP executable. Connecting to an already-running shared API does not require another server or Docker just for that connection; each publishing machine still needs its own local search service.

Configure a new server

Section titled “Configure a new server”

This minimal example uses lexical search so no model download is needed. Save it as server.toml on the API host:

version = 1
listen = "127.0.0.1:8787"
qdrant_url_env = "MASH_QDRANT_URL"
qdrant_grpc_url_env = "MASH_QDRANT_GRPC_URL"


[views.build]
representations = "lexical-only"


[[nodes]]
group_id = "personal"
node_id = "laptop"
token_env = "MASH_LAPTOP_TOKEN"


[[nodes]]
group_id = "personal"
node_id = "desktop"
token_env = "MASH_DESKTOP_TOKEN"

Set the two Qdrant URL variables to the HTTP and gRPC addresses of the same server-side Qdrant instance. Set each node-token variable to a different random secret of at least 32 printable ASCII bytes. Keep tokens out of Git.

Start the API:

Terminal window
mash-server --server-config /absolute/path/to/server.toml

The example listens only on loopback. Put an HTTPS reverse proxy in front of it for other machines to reach it, or change listen to the host’s private-network IP and use that private URL. Keep Qdrant’s own ports private to the API host.

These settings are for a new service. Back up an existing installation before changing it.

Connect each machine

Section titled “Connect each machine”

In a terminal, run mash init and choose Connect to an existing shared server. For an existing configuration, first choose Review and edit settings. Enter the server URL, group ID, this machine’s unique ID, and the name of the environment variable containing its token. Set that variable before running the wizard and make it available to your agent clients too; the wizard does not store token values. It checks authentication before offering to index and upload. If you are not ready to host a server, choose Set up sharing later to finish local setup and return to this guide afterward.

For manual configuration:

Edit the node configuration created by mash init. Preserve its providers and local Qdrant settings. Change the existing [index] table and add:

[index]
destination = "both"
since_days = 90


[shared]
group_id = "personal"
node_id = "laptop"
api_url = "https://mash.example.net"
token_env = "MASH_NODE_TOKEN"

Replace the URL with your reachable API endpoint. On the other machine, use node_id = "desktop". Set MASH_NODE_TOKEN to that machine’s matching server token. Make the variable available to the CLI, watcher, and agent’s MCP process.

For the lexical server above, use [views.build] representations = "lexical-only" and [views.query] intent = "exact-mention" on each node. These are the normal model-free init settings. For semantic search, ask the server administrator for matching model settings.

Section titled “Publish and search”

On each machine:

Terminal window
mash index
mash status --shared

For older history, use mash index --all-history. Check each node’s publication and search readiness before expecting its chats to appear elsewhere.

Terminal window
mash search 'authentication'
mash search 'authentication' --shared
mash search 'authentication' --local

The first combines local history and other nodes. The second searches published history only, including this node. The third stays local. Use --node desktop to narrow by publishing identity, not to connect to a host.

Run a watcher on each publishing machine for ongoing updates. If publication fails, local history is retained; inspect the reported shared error and retry indexing once the connection is fixed.

Remove a machine, or let a rebuilt one publish again

Section titled “Remove a machine, or let a rebuilt one publish again”

The server ties each machine’s name to the local index that first published under it, so another machine cannot overwrite its history by using its name. That also stops the same machine after its index is deleted and rebuilt: publishing fails with “shared node ownership or revision changed”. Restoring the index from a backup keeps the name. Otherwise, retire the name on the server:

Terminal window
# On the API host, with the mash-server service stopped.
mash-server --server-config /absolute/path/to/server.toml --retire-node personal/laptop

This permanently deletes everything that machine published: its chats and records on the server, their search data, and its shared attachments. It prints how many chats and messages it removed and exits without serving. Start the service again, then run mash index on the machine to publish from its current index. Other machines are not affected, and the machine’s own local history is untouched.

To remove a machine for good, retire it and then delete its [[nodes]] entry from the server configuration.

For schema changes, follow upgrades and backups.