> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trychroma.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Chroma Clients

> Learn how to instantiate Chroma clients for Cloud, in-memory, and persistent use cases.

There are several ways you can instantiate clients to connect to your Chroma database.

## Cloud Client

You can use the `CloudClient` to create a client connecting to Chroma Cloud.

<CodeGroup>
  ```python Python theme={null}
  import chromadb

  client = chromadb.CloudClient(
      tenant='Tenant ID',
      database='Database name',
      api_key='Chroma Cloud API key'
  )
  ```

  ```typescript TypeScript theme={null}
  import { CloudClient } from "chromadb";

  const client = new CloudClient({
    tenant: "Tenant ID",
    database: "Database name",
    apiKey: "Chroma Cloud API key",
  });
  ```

  ```rust Rust theme={null}
  use chroma::{ChromaHttpClient, ChromaHttpClientOptions};

  let options = ChromaHttpClientOptions::cloud(
      "ck-...",
      "Database name",
  )?;
  let client = ChromaHttpClient::new(options);
  ```
</CodeGroup>

The `CloudClient` can be instantiated just with the API key argument. In which case, we will resolve the tenant and DB from Chroma Cloud. Note our auto-resolution will work only if the provided API key is scoped to a single DB.

If you set the `CHROMA_API_KEY`, `CHROMA_TENANT`, and the `CHROMA_DATABASE` environment variables, you can simply instantiate a `CloudClient` with no arguments:

<CodeGroup>
  ```python Python theme={null}
  client = chromadb.CloudClient()
  ```

  ```typescript TypeScript theme={null}
  const client = new CloudClient();
  ```

  ```rust Rust theme={null}
  use chroma::ChromaHttpClient;

  let client = ChromaHttpClient::cloud()?;
  ```
</CodeGroup>

### Connecting to a non-default region

By default, `CloudClient` connects to `api.trychroma.com` (AWS `us-east-1`). To target a database in another region — for example, our GCP `europe-west1` region — point the client at that region's hostname. See [Regions](/cloud/getting-started#regions) for the list of available endpoints.

<CodeGroup>
  ```python Python theme={null}
  import chromadb

  client = chromadb.CloudClient(
      cloud_host='europe-west1.gcp.trychroma.com',
      cloud_port=443,
      api_key='Chroma Cloud API key',
      tenant='Tenant ID',
      database='Database name',
  )
  ```

  ```typescript TypeScript theme={null}
  import { ChromaClient } from "chromadb";

  const client = new ChromaClient({
    host: "europe-west1.gcp.trychroma.com",
    ssl: true,
    headers: { "x-chroma-token": "Chroma Cloud API key" },
    tenant: "Tenant ID",
    database: "Database name",
  });
  ```

  ```rust Rust theme={null}
  use chroma::{ChromaAuthMethod, ChromaHttpClient, ChromaHttpClientOptions};

  let client = ChromaHttpClient::new(ChromaHttpClientOptions {
      endpoint: "https://europe-west1.gcp.trychroma.com:443".parse()?,
      auth_method: ChromaAuthMethod::cloud_api_key("Chroma Cloud API key")?,
      database_name: Some("Database name".to_string()),
      ..Default::default()
  });
  ```
</CodeGroup>

The dashboard's **Connect** panel generates a ready-to-paste snippet for whichever region a database lives in, including the corresponding `.env` block. For databases outside `aws-us-east-1`, the snippet sets `CHROMA_HOST` to the region-specific host:

```bash theme={null}
CHROMA_HOST=europe-west1.gcp.trychroma.com
CHROMA_API_KEY=...
CHROMA_TENANT=...
CHROMA_DATABASE=...
```

## In-Memory Client

In Python, you can run a Chroma server in-memory and connect to it with the ephemeral client:

```python theme={null}
import chromadb

client = chromadb.Client()
```

The `Client()` method starts a Chroma server in-memory and also returns a client with which you can connect to it.

This is a great tool for experimenting with different embedding functions and retrieval techniques in a Python notebook, for example. If you don't need data persistence, the ephemeral client is a good choice for getting up and running with Chroma.

## Persistent Client

<Tabs>
  <Tab title="Python" icon="python">
    You can configure Chroma to save and load the database from your local machine, using the `PersistentClient`.

    Data will be persisted automatically and loaded on start (if it exists).

    ```python theme={null}
    import chromadb

    client = chromadb.PersistentClient(path="/path/to/save/to")
    ```

    The `path` is where Chroma will store its database files on disk, and load them on start. If you don't provide a path, the default is `.chroma`

    The client object has a few useful convenience methods.

    * `heartbeat()` - returns a nanosecond heartbeat. Useful for making sure the client remains connected.
    * `reset()` - empties and completely resets the database. WARNING: This is destructive and not reversible.

    ```python theme={null}
    client.heartbeat()
    client.reset()
    ```
  </Tab>

  <Tab title="TypeScript" icon="js">
    To connect with the JS/TS client, you must connect to a Chroma server.

    To run a Chroma server locally that will persist your data, install Chroma from npm using any npm compatible client.

    ```terminal theme={null}
    npm install chromadb
    ```

    And run the server using our CLI:

    ```terminal theme={null}
    npx chroma run --path ./getting-started
    ```

    The `path` is where Chroma will store its database files on disk, and load them on start. The default is `.chroma`.

    Alternatively, you can also use our official Docker image:

    ```terminal theme={null}
    docker pull chromadb/chroma
    docker run -p 8000:8000 chromadb/chroma
    ```

    With a Chroma server running locally, you can connect to it by instantiating a new `ChromaClient`:

    ```typescript theme={null}
    import { ChromaClient } from "chromadb";

    const client = new ChromaClient();
    ```

    By default, the `ChromaClient` is wired to connect to a Chroma server at `http://localhost:8000`, with `default_tenant` and `default_database`. If you have different settings you can provide them to the `ChromaClient` constructor:

    ```typescript theme={null}
    const client = new ChromaClient({
      ssl: false,
      host: "localhost",
      port: 9000, // non-standard port based on your server config
      database: "my-db",
      headers: {},
    });
    ```

    The client object has a few useful convenience methods.

    * `heartbeat()` - returns a nanosecond heartbeat. Useful for making sure the client remains connected.
    * `reset()` - empties and completely resets the database. WARNING: This is destructive and not reversible.

    ```typescript theme={null}
    await client.heartbeat();
    await client.reset();
    ```
  </Tab>

  <Tab title="Rust" icon="rust">
    The Rust client connects to a running Chroma server. For local persistence, run the server with a data path and connect over HTTP.

    ```bash theme={null}
    chroma run --path /db_path
    ```

    ```rust theme={null}
    use chroma::{ChromaHttpClient, ChromaHttpClientOptions};

    let mut options = ChromaHttpClientOptions::default();
    options.endpoint = "http://localhost:8000".parse()?;

    let client = ChromaHttpClient::new(options);
    client.heartbeat().await?;
    ```
  </Tab>
</Tabs>