> 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

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](/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](/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](/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](/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, save, stats. Index building, snapshots, and tuning stay in-process on the owner. See [Connect with RemoteTelys](/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="/pages/m2J97eu4yShN3lKTM7aN">/pages/m2J97eu4yShN3lKTM7aN</a></td></tr><tr><td><strong>Connect with RemoteTelys</strong></td><td>Drive a running server from client code.</td><td><a href="/pages/eM9bdGEBcTduuJ0KXZ1Y">/pages/eM9bdGEBcTduuJ0KXZ1Y</a></td></tr><tr><td><strong>Auth &#x26; network model</strong></td><td>Trust, tokens, and the wire protocol.</td><td><a href="/pages/N6BRLlIY4N7N32k9EspF">/pages/N6BRLlIY4N7N32k9EspF</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/self-hosting/overview.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.