> 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/self-hosting/overview.md).

# Overview

Run Telys as a local server so several processes or hosts share one memory store over a Unix socket or an access-token-protected TCP port.

Telys runs in-process by default: construct `Telys(path)`, open a collection, and read and write vectors inside your own program. That fits a single application that owns its store.

Serve instead when several processes — a web worker pool, a batch job, an interactive shell — must read and write the *same* collections, or when a store lives on one host and is reached from another over a trusted private network.

`telys serve` (and the `serve()` function behind it) runs a long-lived process that owns a store directory and answers requests over a socket. Clients connect with `connect()` / `RemoteTelys` and drive collections almost as they would locally. The server is the single writer to disk; clients never touch collection files directly.

Serving is the **`telys_team`** self-host tier. See [Plans & licensing](https://docs.telys.ai/licensing/tiers-and-pricing.md).

## When to serve vs. run in-process

{% hint style="info" %}
Serving adds a socket hop and a single-owner process. If one program uses the store, skip it — the in-process facade is simpler and faster. Serve only for *shared* access. See [Local vs remote execution](https://docs.telys.ai/understand-telys/local-vs-remote.md).
{% endhint %}

| Situation                                                 | Use                                               |
| --------------------------------------------------------- | ------------------------------------------------- |
| One application owns the store                            | In-process `Telys(path)`                          |
| Several processes on one host share collections           | A server on a Unix socket                         |
| A store on one host, clients on another (private network) | A server on a TCP port with an access token       |
| A quick script against an existing store                  | Either — connect if a server already owns the dir |

## How the pieces fit

```
        your processes                         one owner process
  +-----------------------+             +---------------------------+
  | connect("unix://...")  |  length-   | telys serve --path ./mem  |
  |  -> RemoteTelys        |  prefixed  |   - owns ./mem on disk     |
  |  -> RemoteCollection   |<--JSON---> |   - single writer          |
  |     add / search / ... |  socket    |   - no outbound network    |
  +-----------------------+             +---------------------------+
```

The client speaks a length-prefixed JSON protocol; the server runs every operation against the on-disk store and returns results. The wire format and its limits are in [Auth & network model](https://docs.telys.ai/self-hosting/auth-and-network.md).

## Two ways to be reached

A server listens on one of two transports, chosen at start.

{% tabs %}
{% tab title="Unix socket" icon="plug" %}
Created with `0600` permissions and treated as **trusted**: any local user who can open the socket file is authorized, so no token is required. Best for several processes sharing a store on one host.

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

```python
from telys.client import connect

with connect("unix:///tmp/telys.sock") as client:
    col = client.open_collection("notes")
    print(col.stats())
```

{% endtab %}

{% tab title="TCP" icon="network-wired" %}
Reachable from other hosts, so it **requires** an access token — the server refuses anonymous connections. Bind to a private interface only.

```bash
export TELYS_ACCESS_TOKEN="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
telys serve --path ./memory --host 0.0.0.0 --port 9099 --access-token "$TELYS_ACCESS_TOKEN"
```

```python
from telys.client import connect

with connect("tcp://memory.internal:9099", token="$TELYS_ACCESS_TOKEN") as client:
    print(client.ping())
```

{% endtab %}
{% endtabs %}

## What the server does and does not do

{% hint style="success" %}
The server makes **no outbound network calls**. It listens on the socket you give it, verifies licenses offline, and reads and writes the store directory. See [What leaves the machine](https://docs.telys.ai/security/what-leaves-the-machine.md).
{% endhint %}

* **Single owner of the store.** Point one server at a given `--path`. Clients never open the collection files.
* **Pre-registers the `bigram` embedder.** On boot the server best-effort registers `AlgentaBigramEmbedder` as `"bigram"`, so clients can create a collection with `embedder="bigram"` and use `add_texts` / `search_text` immediately.
* **A remote surface, not the whole API.** `RemoteCollection` is a subset of local `Collection` — ingest, query, delete, compact, index building (`build_ivf`), snapshots, save, stats. Tuning (`tune` / `apply_tuning`) and `update_texts` stay in-process on the owner. See [Connect with RemoteTelys](https://docs.telys.ai/self-hosting/connecting-remote.md).
* **Optional license gate.** Start with `--require-license` to verify a `products.telys` license offline before accepting any connection.

## 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>Run a Telys server</strong></td><td>Start a server on a Unix socket or a TCP port.</td><td><a href="https://docs.telys.ai/self-hosting/running-a-server.md">Run a server</a></td></tr><tr><td><strong>Connect with RemoteTelys</strong></td><td>Drive a running server from client code.</td><td><a href="https://docs.telys.ai/self-hosting/connecting-remote.md">Connect remotely</a></td></tr><tr><td><strong>Auth &#x26; network model</strong></td><td>Trust, tokens, and the wire protocol.</td><td><a href="https://docs.telys.ai/self-hosting/auth-and-network.md">Auth &amp; network</a></td></tr></tbody></table>
