> 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

Reference for the remote surface — connect and RemoteTelys, the RemoteCollection subset, serve and TelysServer, address forms, and the wire protocol.

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.                                                                  |
| `drop_collection(name)`                                                                        | —                  | Delete a collection (and its on-disk data) from the shared server. No-op if it doesn't exist. |
| `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.                                                                                      |
| `build_ivf`                 | Build per-partition IVF for oversized partitions (`min_rows=20000`, `target_recall=0.98` defaults). |
| `snapshot`                  | Snapshot the collection on the server.                                                              |
| `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`                |
| `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="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 server from a client.</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>Tokens, sockets, and trust.</td><td><a href="https://docs.telys.ai/self-hosting/auth-and-network.md">Auth &amp; network</a></td></tr><tr><td><strong>Local vs remote execution</strong></td><td>When to serve versus run in-process.</td><td><a href="https://docs.telys.ai/understand-telys/local-vs-remote.md">Local vs remote</a></td></tr></tbody></table>
