> For the complete documentation index, see [llms.txt](https://docs.telys.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.telys.ai/understand-telys/local-vs-remote.md).

# Local vs remote

Telys runs the same engine two ways. **Local** execution embeds the runtime in your process: construct `Telys(path)` and every call runs in-process against a directory on disk — the default, and the fastest. **Remote** execution puts one store behind a server (`telys serve`) that many processes or hosts share over a socket, reached with `connect()` / `RemoteTelys`. This page covers when to pick each and how the remote surface is a strict *subset* of the local one.

## Two execution models

{% tabs %}
{% tab title="Local (in-process)" icon="microchip" %}
The engine loads inside your Python process; there is no server, no socket, no auth. Best for a single application, notebooks, batch jobs, and the full API surface (tuning, IVF, snapshots).

```python
from telys import Telys
from telys.embedding import AlgentaMultigramEmbedder

emb = AlgentaMultigramEmbedder()
db = Telys("./memory")
col = db.create_collection("notes", dim=emb.profile.dimension, partition_by="scope", embedder=emb)
col.add_texts(["on-device memory"], ids=["m1"], metadata=[{"scope": "acme"}])
```

{% endtab %}

{% tab title="Remote (shared server)" icon="network-wired" %}
One process owns the store and serves it; others connect. Best when several processes or hosts must share **one** store, or you want a single writer. Start the server, then connect a client:

```bash
telys serve --path ./memory --socket /tmp/telys.sock
```

```python
from telys.client import connect

with connect("/tmp/telys.sock") as db:
    col = db.open_collection("notes")
    hits = col.search_text("on-device memory", top_k=5)
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
`connect` and `RemoteTelys` live in `telys.client` (not the top-level namespace). A client is a context manager, so `with connect(...) as db:` closes the connection cleanly. Address forms: `unix:///path`, `/abs/path.sock`, `./rel.sock`, `tcp://host:port`, or `host:port`.
{% endhint %}

## RemoteCollection is a strict subset

A remote client speaks to a `RemoteCollection`, which exposes the **common** operations only. Anything inherently single-process — index building, snapshots, tuning — is not on the wire. Design for the remote surface if you might ever serve the store.

| Capability                                   | Local `Collection` | `RemoteCollection`     |
| -------------------------------------------- | ------------------ | ---------------------- |
| `add`, `upsert`, `add_texts`, `upsert_texts` | yes                | yes                    |
| `search`, `search_text`                      | yes                | yes                    |
| `ids`, `delete`, `compact`, `save`, `stats`  | yes                | yes                    |
| `update_texts`                               | yes                | **no**                 |
| `build_ivf`                                  | yes                | **no**                 |
| `snapshot`                                   | yes                | **no**                 |
| `tune`, `apply_tuning`                       | yes                | **no**                 |
| `len(col)` / `ext in col`                    | yes                | **no**                 |
| `search(..., target_recall=...)`             | yes                | **no `target_recall`** |

Two differences bite most often:

* **No `target_recall` on remote search.** `RemoteCollection.search(vector, top_k=10, where=None, explain=False, with_metadata=False)` has no `target_recall` argument. Recall is governed server-side by whatever tuning the server owner applied; a client cannot request a per-query recall target.
* **Remote `create_collection` takes a string embedder and no tuner.** Over the wire you cannot pass a Python embedder object or a `Tuner`:

```python
from telys.client import connect

with connect("/tmp/telys.sock") as db:
    col = db.create_collection(
        "notes",
        dim=384,
        partition_by="scope",
        filter_columns=(),
        dtype="f32",
        embedder="bigram",   # a STRING naming a server-registered embedder; no tuner arg
    )
```

The server pre-registers `AlgentaBigramEmbedder` under the name `"bigram"`, so text methods work out of the box; register additional embedders with `serve(..., embedder_factory=...)`.

## Auth and the network model

How you serve determines what a client must present:

{% tabs %}
{% tab title="Unix socket" icon="plug" %}
A Unix-domain socket is created `0o600` and treated as **trusted** — filesystem permissions are the boundary, so no token is required. Ideal for co-located processes on one host.

```bash
telys serve --path ./memory --socket /tmp/telys.sock
```

{% endtab %}

{% tab title="TCP" icon="lock" %}
TCP **requires** an access token — the server refuses anonymous TCP connections. The client sends an auth handshake first, compared in constant time.

```bash
telys serve --path ./memory --host 127.0.0.1 --port 8760 \
  --access-token "$TELYS_ACCESS_TOKEN"
```

```python
import os
from telys.client import connect

db = connect("tcp://127.0.0.1:8760", token=os.environ["TELYS_ACCESS_TOKEN"])
```

{% endtab %}
{% endtabs %}

{% hint style="warning" %}
The server makes no outbound network calls, but it does open a listening socket — so treat TCP mode like any exposed service: bind to a trusted interface and always set `--access-token` (or `$TELYS_ACCESS_TOKEN`). Serving is the `telys_team` tier; see [Plans & licensing](/licensing/tiers-and-pricing.md).
{% endhint %}

## Which should you use?

| Use local when…                     | Use remote when…                           |
| ----------------------------------- | ------------------------------------------ |
| One application owns the store      | Several processes or hosts share one store |
| You need tuning, IVF, or snapshots  | The common CRUD + search surface is enough |
| You want the lowest latency         | You want a single writer / central store   |
| Notebooks, batch jobs, embedded use | A long-running service fronts the memory   |

A good rule: **build against the local API; if you later serve the same store, keep to the subset above.** A remote client cannot tune, build indexes, or snapshot, so run those maintenance steps locally against the same directory before (or between) serving it.

## Next steps

<table data-view="cards"><thead><tr><th></th><th></th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td><strong>Serving overview</strong></td><td>The self-hosting model, transports, and when to serve.</td><td><a href="/pages/GRqsH5DPQpYEB3ISZf53">/pages/GRqsH5DPQpYEB3ISZf53</a></td></tr><tr><td><strong>Connect with RemoteTelys</strong></td><td>The hands-on recipe for connecting a client to a server.</td><td><a href="/pages/eM9bdGEBcTduuJ0KXZ1Y">/pages/eM9bdGEBcTduuJ0KXZ1Y</a></td></tr><tr><td><strong>Remote API (connect / RemoteTelys)</strong></td><td>Full reference for the remote client and its subset.</td><td><a href="/pages/UJxEHqp7LiaWT1dNSCDZ">/pages/UJxEHqp7LiaWT1dNSCDZ</a></td></tr></tbody></table>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.telys.ai/understand-telys/local-vs-remote.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.