Enterprise

# Connect to a Core

> Connect and authenticate a Python or TypeScript client with a Synnax Core: log in with arguments or sy login, use TLS, and close the client.

Create a client to connect your code to a Synnax Core. The client logs in with the username and password of a [user](https://docs.synnaxlabs.com/reference/enterprise/users) on the Core.

## Connect with arguments

[Enterprise](https://docs.synnaxlabs.com/reference/get-started/editions "Needs Synnax Enterprise")

**Python**

```python
import synnax as sy

client = sy.Synnax(
    host="core.example.com",
    port=9090,
    username="operator",
    password="secret",
)
```

The client logs in when you create it. It raises `sy.AuthError` when the credentials are wrong. It raises `Unreachable`, from the `freighter` package, when it cannot reach the Core.

**TypeScript**

```typescript
import { Synnax } from "@synnaxlabs/client";

const client = new Synnax({
  host: "core.example.com",
  port: 9090,
  username: "operator",
  password: "secret",
});
await client.connect();
```

The client starts to connect when you create it, but it does not wait. `connect` waits for the connection. It throws `AuthError` when the credentials are wrong, and `DisconnectedError` when it cannot reach the Core. Without `connect`, the first request throws the same errors.

To keep credentials out of a script, read them from environment variables that you set. The clients read no environment variables by themselves.

## Log in once with sy login

The `sy login` command saves your credentials, so Python scripts can connect with no arguments. It is part of the Python client. Run it in a terminal:

```bash
sy login
```

Answer the prompts. Press **Enter** to keep the default in parentheses:

```plaintext
Enter your Synnax connection parameters:
Host (localhost): core.example.com
Port (9090):
Username (synnax): operator
Password:
Secure Connection? [y/n] (n):
```

When you answer `y` to the secure prompt, the command also asks for the “CA certificate path”. Enter the path to the `ca.crt` file of the Core. Leave it empty when the Core has a certificate from a public authority.

The command connects to the Core, then prints “Connection successful!”. In your scripts, create the client with no arguments:

```python
import synnax as sy

client = sy.Synnax()
```

The command stores the host, port, username, TLS setting, and CA certificate path in `~/.synnax/config.json`. It stores the password in the keychain of your operating system, under the name `synnax`. When the login fails, the command saves nothing. Run `sy login` again to change the values.

With no saved login, `sy.Synnax()` raises `sy.ValidationError`. When you give no host, the client ignores the other arguments and uses the saved login.

## Connect with TLS

When the Core serves TLS, set `secure` to true. For how to give the Core a certificate, see [Set up TLS](https://docs.synnaxlabs.com/reference/enterprise/tls).

[Enterprise](https://docs.synnaxlabs.com/reference/get-started/editions "Needs Synnax Enterprise")

**Python**

```python
client = sy.Synnax(
    host="core.example.com",
    port=9090,
    username="operator",
    password="secret",
    secure=True,
)
```

The Python client checks the certificate of the Core, and checks that the certificate is for the host that you connect to. A certificate from a public authority, such as Let’s Encrypt, needs no setup. When the Core uses a self-signed certificate, give the path to its CA certificate in `ca_cert`:

```python
client = sy.Synnax(
    host="core.example.com",
    port=9090,
    username="operator",
    password="secret",
    secure=True,
    ca_cert="/path/to/ca.crt",
)
```

A Core that you start with `--auto-cert` makes its own CA certificate. Give its path in `ca_cert`, or save it with [`sy login`](https://docs.synnaxlabs.com/reference/client/connect#log-in-once-with-sy-login). To find the file, see [Copy the CA certificate](https://docs.synnaxlabs.com/reference/enterprise/certificates#copy-the-ca-certificate).

**TypeScript**

```typescript
const client = new Synnax({
  host: "core.example.com",
  port: 9090,
  username: "operator",
  password: "secret",
  secure: true,
});
```

The TypeScript client checks the certificate of the Core. When the Core uses a self-signed certificate, the computer must trust its CA certificate. The TypeScript client has no CA certificate option. In a browser, [install the CA certificate](https://docs.synnaxlabs.com/reference/enterprise/certificates) on the computer. For Node.js, see [Node.js](https://docs.synnaxlabs.com/reference/enterprise/certificates#nodejs).

## Close the client

Close the client when your code is done with it:

[Enterprise](https://docs.synnaxlabs.com/reference/get-started/editions "Needs Synnax Enterprise")

**Python**

```python
client.close()
```

When the script exits, the client closes by itself.

**TypeScript**

```typescript
await client.close();
```

A Node.js script does not exit until you close the client.

## Client options

[Enterprise](https://docs.synnaxlabs.com/reference/get-started/editions "Needs Synnax Enterprise")

**Python**

* [`host`](https://docs.synnaxlabs.com/reference/client/connect#python-host)`str`

  The hostname or IP address of the Core. With no host, the client uses the values that `sy login` saved.

* [`port`](https://docs.synnaxlabs.com/reference/client/connect#python-port)`int`

  The port of the Core.

* [`username`](https://docs.synnaxlabs.com/reference/client/connect#python-username)`str`

  The username to log in with.

* [`password`](https://docs.synnaxlabs.com/reference/client/connect#python-password)`str`

  The password to log in with.

* [`secure`](https://docs.synnaxlabs.com/reference/client/connect#python-secure)`bool = False`

  Connect with TLS.

* [`ca_cert`](https://docs.synnaxlabs.com/reference/client/connect#python-ca-cert)`str`

  The path to the CA certificate that signs the certificate of the Core. With `ca_cert` and no `secure`, the client raises `ValueError`. With no path, the client trusts the CA certificates of the computer.

* [`open_timeout`](https://docs.synnaxlabs.com/reference/client/connect#python-open-timeout)`TimeSpan = 5 s`

  How long to wait to open a connection.

* [`read_timeout`](https://docs.synnaxlabs.com/reference/client/connect#python-read-timeout)`TimeSpan = 5 s`

  How long to wait for a response.

* [`keep_alive`](https://docs.synnaxlabs.com/reference/client/connect#python-keep-alive)`TimeSpan = 30 s`

  How often an async streamer checks its connection to the Core.

* [`max_retries`](https://docs.synnaxlabs.com/reference/client/connect#python-max-retries)`int = 3`

  How many times to retry a request that fails to reach the Core.

* [`clock_skew_threshold`](https://docs.synnaxlabs.com/reference/client/connect#python-clock-skew-threshold)`TimeSpan = 1 s`

  The largest difference between the clocks of the computer and the Core before the client prints a warning.

**TypeScript**

* [`host`](https://docs.synnaxlabs.com/reference/client/connect#typescript-host)`string`

  The hostname or IP address of the Core.

* [`port`](https://docs.synnaxlabs.com/reference/client/connect#typescript-port)`number | string`

  The port of the Core.

* [`username`](https://docs.synnaxlabs.com/reference/client/connect#typescript-username)`string`

  The username to log in with.

* [`password`](https://docs.synnaxlabs.com/reference/client/connect#typescript-password)`string`

  The password to log in with.

* [`secure`](https://docs.synnaxlabs.com/reference/client/connect#typescript-secure)`boolean = false`

  Connect with TLS.

* [`connectivityPollFrequency`](https://docs.synnaxlabs.com/reference/client/connect#typescript-connectivity-poll-frequency)`TimeSpan = 30 s`

  How often the client checks that it can reach the Core.

* [`clockSkewThreshold`](https://docs.synnaxlabs.com/reference/client/connect#typescript-clock-skew-threshold)`TimeSpan = 1 s`

  The largest difference between the clocks of the computer and the Core before the client prints a warning.

* [`name`](https://docs.synnaxlabs.com/reference/client/connect#typescript-name)`string`

  A name for the Core, which the client shows in its connection status messages.

* [`retry`](https://docs.synnaxlabs.com/reference/client/connect#typescript-retry)`object`

  How the client retries a request that fails to reach the Core: `baseInterval` (1 s), `maxInterval`, `maxRetries` (5), `scale` (1), and `jitter` (0).

* [`cache`](https://docs.synnaxlabs.com/reference/client/connect#typescript-cache)`boolean = true`

  Keep retrieved resources in memory and update them as they change on the Core.

* [`onRetry`](https://docs.synnaxlabs.com/reference/client/connect#typescript-on-retry)`function`

  Called each time the client retries a failed request. By default, the client logs a warning.

* [`onInternalError`](https://docs.synnaxlabs.com/reference/client/connect#typescript-on-internal-error)`function`

  Called with cache errors that have no caller to throw to. By default, the client logs the error.

When the client cannot connect, see [Troubleshooting](https://docs.synnaxlabs.com/reference/client/troubleshooting).