> 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/reference/remote-api.md).

# Remote

Telys can run as a server and be driven from another process or host. The client (`connect`, `RemoteTelys`) lives in `telys.client`; the server (`serve`) lives in `telys.server`. The transport is length-prefixed JSON over a socket — no HTTP, no outbound network.

```python
from telys.client import connect, RemoteTelys
from telys.server import serve
```

## connect

```python
connect(address, token=None) -> RemoteTelys
```

Constructs and returns a `RemoteTelys`. With a `token`, an auth handshake is sent before the first request.

## RemoteTelys

```python
RemoteTelys(address, token=None, *, connect_timeout=30.0)
```

The remote analogue of the `Telys` facade. It is a context manager; close it when done.

### Address forms

| Form                   | Transport                           |
| ---------------------- | ----------------------------------- |
| `unix:///path/to.sock` | Unix domain socket.                 |
| `/abs/path.sock`       | Unix domain socket (absolute path). |
| `./rel.sock`           | Unix domain socket (relative path). |
| `tcp://host:port`      | TCP.                                |
| `host:port`            | TCP.                                |

### Methods

| Signature                                                                                      | Returns            | Description                                                                         |
| ---------------------------------------------------------------------------------------------- | ------------------ | ----------------------------------------------------------------------------------- |
| `ping()`                                                                                       | —                  | Round-trip liveness check.                                                          |
| `create_collection(name, dim, partition_by, *, filter_columns=(), dtype="f32", embedder=None)` | `RemoteCollection` | Create a collection. `embedder` is a **string** name; there is no `tuner` argument. |
| `open_collection(name)`                                                                        | `RemoteCollection` | Open an existing collection.                                                        |
| `collections()`                                                                                | `list[str]`        | List collections on the server.                                                     |
| `__getitem__(name)`                                                                            | `RemoteCollection` | `client[name]`.                                                                     |
| `close()`                                                                                      | —                  | Close the connection.                                                               |

```python
from telys.client import connect

with connect("unix:///tmp/telys.sock", token="$TELYS_ACCESS_TOKEN") as client:
    client.ping()
    col = client.open_collection("notes")
    hits = col.search_text("release checklist", top_k=5)
    print(hits["ids"])
```

{% hint style="info" %}
Over the wire, `create_collection` takes the embedder as a **string** name (e.g. `"bigram"`), resolved by the server's registry. You cannot pass an embedder instance or a tuner remotely.
{% endhint %}

## RemoteCollection

A strict **subset** of the local `Collection` — the methods that make sense over the wire:

| Available                   | Notes                                     |
| --------------------------- | ----------------------------------------- |
| `add`, `upsert`             | Raw vectors.                              |
| `add_texts`, `upsert_texts` | Server-side embedding.                    |
| `search`, `search_text`     | See the reduced `search` signature below. |
| `ids`                       | Live external ids, optional `where`.      |
| `delete`                    | Delete present ids.                       |
| `compact`                   | Reclaim space.                            |
| `save`                      | Commit to disk on the server.             |
| `stats`                     | Collection stats.                         |

Reduced search signature (note: **no** `target_recall`):

```python
RemoteCollection.search(vector, top_k=10, where=None, explain=False, with_metadata=False)
```

Missing versus the local `Collection`:

| Not available remotely        |
| ----------------------------- |
| `update_texts`                |
| `build_ivf`                   |
| `snapshot`                    |
| `tune`                        |
| `apply_tuning`                |
| `__len__` (`len(col)`)        |
| `__contains__` (`ext in col`) |

## serve

```python
serve(path, socket_path=None, *, host=None, port=None,
      license_token=None, require_license=False, access_token=None,
      embedder_factory=None, save_interval_s=0.0) -> TelysServer
```

Starts a blocking `TelysServer` rooted at `path`. Choose exactly one transport: a Unix socket (`socket_path`) or TCP (`host` and `port`).

| Parameter          | Default    | Meaning                                                           |
| ------------------ | ---------- | ----------------------------------------------------------------- |
| `path`             | (required) | Engine directory to serve.                                        |
| `socket_path`      | `None`     | Unix socket path (mode `0o600`, trusted, no token required).      |
| `host` / `port`    | `None`     | TCP bind; **requires** `access_token` (anonymous TCP is refused). |
| `license_token`    | `None`     | License to verify when `require_license=True`.                    |
| `require_license`  | `False`    | Verify a `products.telys` ver:2 license offline on boot.          |
| `access_token`     | `None`     | Bearer token for TCP; compared in constant time.                  |
| `embedder_factory` | `None`     | Factory to build server-side embedders.                           |
| `save_interval_s`  | `0.0`      | Autosave interval in seconds (`0.0` disables).                    |

The server pre-registers `AlgentaBigramEmbedder` as `model_id` `"bigram"` (best-effort) and makes no outbound network connections.

{% hint style="warning" %}
A Unix socket is trusted and needs no token. TCP is different: `serve` refuses to bind without an `access_token`. Over the CLI, `telys serve` exits `2` if you provide neither `--socket` nor both `--host` and `--port`.
{% endhint %}

```bash
# Unix socket (trusted, local)
telys serve --path ./memory --socket /tmp/telys.sock

# TCP (requires a token)
telys serve --path ./memory --host 0.0.0.0 --port 8899 \
  --access-token "$TELYS_ACCESS_TOKEN"
```

## Wire protocol

| Property  | Value                                                                      |
| --------- | -------------------------------------------------------------------------- |
| Framing   | 4-byte length prefix + JSON body.                                          |
| Max frame | 256 MiB.                                                                   |
| Auth      | Optional bearer handshake before the first request; constant-time compare. |
| Network   | Loopback/Unix by default; no outbound connections.                         |

## See also

<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 serve over a socket or TCP.</td><td><a href="/pages/m2J97eu4yShN3lKTM7aN">/pages/m2J97eu4yShN3lKTM7aN</a></td></tr><tr><td><strong>Connect with RemoteTelys</strong></td><td>Drive a server from a client.</td><td><a href="/pages/eM9bdGEBcTduuJ0KXZ1Y">/pages/eM9bdGEBcTduuJ0KXZ1Y</a></td></tr><tr><td><strong>Auth &#x26; network model</strong></td><td>Tokens, sockets, and trust.</td><td><a href="/pages/N6BRLlIY4N7N32k9EspF">/pages/N6BRLlIY4N7N32k9EspF</a></td></tr><tr><td><strong>Local vs remote execution</strong></td><td>When to serve versus run in-process.</td><td><a href="/pages/pDAqCOdYa0pJZlwE3c5A">/pages/pDAqCOdYa0pJZlwE3c5A</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/reference/remote-api.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.