> 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

Once a server owns a store (see [Run a Telys server](/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](/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` is a strict subset of the local `Collection`. Index building, snapshots, 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`               | `build_ivf`, `snapshot`  |
| `delete`, `compact`                          | `tune`, `apply_tuning`   |
| `save`, `stats`                              | `len(col)`, `ext in col` |

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](/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](/self-hosting/auth-and-network.md) — the trust model, token handshake, and wire limits behind these calls.
* [Remote API (connect / RemoteTelys)](/reference/remote-api.md) — every remote method and its signature.
* [Deployment notes](/self-hosting/deployment.md) — run the server durably in production.


---

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