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

# Connect remotely

Connect to a running Telys server with connect() / RemoteTelys, create and open collections remotely, and ingest and search over the length-prefixed socket protocol.

Once a server owns a store (see [Run a Telys server](https://docs.telys.ai/self-hosting/running-a-server.md)), reach it with `connect()` from `telys.client`, which returns a `RemoteTelys`. It behaves like the in-process `Telys` facade — create and open collections, then ingest and search — but every call is a request to the server, and the returned `RemoteCollection` is a subset of the local `Collection`.

## Connect

`connect(address, token=None)` returns a `RemoteTelys`. Match the address form to how the server listens; pass `token` only for TCP.

{% tabs %}
{% tab title="Unix socket" icon="plug" %}

```python
from telys.client import connect

client = connect("unix:///tmp/telys.sock")
print(client.ping())
client.close()
```

Bare paths work too: `connect("/tmp/telys.sock")` (absolute) and `connect("./telys.sock")` (relative) equal the `unix://` form. No token is needed — the socket is trusted.
{% endtab %}

{% tab title="TCP" icon="network-wired" %}

```python
from telys.client import connect

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

`host:port` without a scheme also works: `connect("memory.internal:9099", token="$TELYS_ACCESS_TOKEN")`. The token is required — the server refuses anonymous TCP connections.
{% endtab %}
{% endtabs %}

{% hint style="info" %}
Prefer the context-manager form so the connection always closes, even on error:

```python
with connect("unix:///tmp/telys.sock") as client:
    ...
```

{% endhint %}

## Create a collection remotely

`RemoteTelys.create_collection` mirrors the local call with one difference: **`embedder` is a string name**, resolved by the server, and there is **no `tuner` argument**. The server pre-registers `AlgentaBigramEmbedder` as `"bigram"`, so that name works out of the box.

```python
from telys.client import connect

with connect("unix:///tmp/telys.sock") as client:
    col = client.create_collection(
        "notes",
        64,              # dim — must match the named embedder's dimension
        "scope",         # partition_by (physical partition key)
        embedder="bigram",
    )
```

{% hint style="warning" %}
The `dim` you pass must equal the named embedder's dimension. The `bigram` embedder's dimension is read from the native kernel (a 64-d hint, not a guaranteed constant). If unsure, use the dimension the server reports for that embedder, or ingest via `add(vectors, ...)` with vectors of the dimension you declared.
{% endhint %}

The full signature is `create_collection(name, dim, partition_by, *, filter_columns=(), dtype="f32", embedder=None)`. `partition_by` names the single physical partition key; for a composite key, compose one string with `scope_key(...)` — a list/tuple uses only its first element. See [Partitions & scope keys](https://docs.telys.ai/understand-telys/partitions-scope-key.md).

## Ingest and search

`RemoteCollection` supports the everyday read/write surface. Filters use `Eq` (or a single-key dict), exactly as in-process.

```python
from telys import Eq
from telys.client import connect

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

    col.add_texts(
        texts=["deploy runbook for the api service", "oncall rotation for july"],
        ids=["doc-1", "doc-2"],
        metadata=[{"scope": "ops"}, {"scope": "ops"}],
    )
    col.save()

    hits = col.search_text(
        "who is oncall this month",
        top_k=3,
        where=Eq("scope", "ops"),
        with_metadata=True,
    )
    print(hits["ids"])
    print(hits["scores"])
    print(hits["metadata"])
```

`search` and `search_text` return `{"ids": [...], "scores": [...]}`, plus `"metadata"` when `with_metadata=True` and `"explain"` when `explain=True`.

## What RemoteCollection supports

{% hint style="info" %}
`RemoteCollection` mirrors the local text surface, with a few exceptions — `update_texts` and tuning stay in-process on the owner. Connect a local `Telys` to the store (while no server owns it) to run those.
{% endhint %}

| Available on `RemoteCollection`              | Not available remotely   |
| -------------------------------------------- | ------------------------ |
| `add`, `upsert`, `add_texts`, `upsert_texts` | `update_texts`           |
| `search`, `search_text`, `ids`               | `tune`, `apply_tuning`   |
| `delete`, `compact`                          | `len(col)`, `ext in col` |
| `build_ivf`, `snapshot`, `save`, `stats`     | —                        |

Remote `search(vector, top_k=10, where=None, explain=False, with_metadata=False)` also has **no `target_recall`** parameter — recall targets are an owner-side concern applied through tuning. The complete method list is in the [Remote API reference](https://docs.telys.ai/reference/remote-api.md).

## Expected result

Running the ingest-and-search snippet against a server that owns the `notes` collection prints a ranked result scoped to `ops`:

```
['doc-2', 'doc-1']
[0.83, 0.20]
[{'scope': 'ops'}, {'scope': 'ops'}]
```

Scores are similarity scores (higher is closer); exact values depend on the embedder and your data. The oncall document ranks first for the oncall query, confirming the round trip — client to server to store and back — works end to end.

## Next steps

* Next: [Auth & network model](https://docs.telys.ai/self-hosting/auth-and-network.md) — the trust model, token handshake, and wire limits behind these calls.
* [Remote API (connect / RemoteTelys)](https://docs.telys.ai/reference/remote-api.md) — every remote method and its signature.
* [Deployment notes](https://docs.telys.ai/self-hosting/deployment.md) — run the server durably in production.
