# Installation

In this section, you will learn how to install the SurrealDB Mojo SDK and add it to your project.

In this section, you will learn how to install the SurrealDB Mojo SDK and add it to your project.

## Requirements

The only runtime dependency is Mojo itself, pinned to `0.26.1.x`. The project uses [pixi](https://pixi.sh/) to manage the Mojo toolchain.

| Platform | Architecture | Status |
|----------|--------------|--------|
| macOS    | arm64        | Tested |
| Linux    | x86_64       | Tested |
| Linux    | aarch64      | Tested |
| Windows  | n/a          | Use WSL2; Mojo has no native Windows toolchain |

## Install the SDK

Clone the repository and install the toolchain with pixi:

```bash
git clone https://github.com/surrealdb/surrealdb.mojo
cd surrealdb.mojo
pixi install
```

To use the SDK from your own project, either vendor `src/surrealdb` into your Mojo package path, or build it into a `.mojopkg`:

```bash
pixi run check     # produces build/surrealdb.mojopkg
```

## Import the SDK into your project

Import the client and connection options from the `surrealdb` package:

```python
from surrealdb import AsyncSurrealClient, ConnectOptions
from std.collections import Optional
```

For the blocking client, import `SurrealClient` instead:

```python
from surrealdb import SurrealClient
```

## Run your program

Run a Mojo file with the SDK source on the include path:

```bash
pixi run mojo run -I src yourfile.mojo
```

## Build with HTTPS

The TLS code sits behind a compile-time gate, so `mojo run` invocations without HTTPS keep working with no OpenSSL on the system. To connect over `https://` or `wss://`, build your program with `mojo build`, define the `HTTPS` flag, and link against `libssl` and `libcrypto` from the pixi environment:

```bash
PIXI_ENV=$(pwd)/.pixi/envs/default
pixi run mojo build -I src -o app \
  -D HTTPS=1 \
  -Xlinker -L$PIXI_ENV/lib \
  -Xlinker -lssl -Xlinker -lcrypto \
  yourfile.mojo

DYLD_LIBRARY_PATH=$PIXI_ENV/lib ./app  # macOS
LD_LIBRARY_PATH=$PIXI_ENV/lib ./app    # Linux
```

If you use an `https://` URL without `-D HTTPS=1`, the SDK raises a `ConnectionError` that names the build flags you need.

## Next steps

- [Getting started](/docs/languages/mojo.md) for a complete working example.
- [Connecting to SurrealDB](/docs/reference/mojo/concepts/connecting-to-surrealdb.md) for connection options and transports.
- [Authentication](/docs/reference/mojo/concepts/authentication.md) for signing in and managing credentials.