> 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

When to run Telys in-process versus behind a shared server — and how RemoteCollection differs as a strict subset of the local Collection API.

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 (including tuning and in-place `update_texts`, which remote omits).

```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 mirrors the local text surface. Only a few operations — `update_texts` and tuning — are 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                    |
| `build_ivf`, `snapshot`                      | yes                | yes                    |
| `update_texts`                               | 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](https://docs.telys.ai/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 or in-place `update_texts` | 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 or run `update_texts`, so run those steps locally against the same directory before (or between) serving it — index builds (`build_ivf`) and snapshots work over the wire.

## 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="https://docs.telys.ai/self-hosting/overview.md">Overview</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="https://docs.telys.ai/self-hosting/connecting-remote.md">Connect remotely</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="https://docs.telys.ai/reference/remote-api.md">Remote</a></td></tr></tbody></table>
