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

# Installation

> Install and configure the Verial TypeScript SDK.

## Requirements

* **Node.js 18** or later
* **TypeScript 5.0** or later (recommended)
* The SDK is **ESM-only**. CommonJS (`require()`) is not supported.

## Install

```bash theme={null}
npm install @verial-ai/sdk
```

## Configure

Create a client instance with your API key:

```typescript theme={null}
import Verial from '@verial-ai/sdk'

const verial = new Verial({
  apiKey: process.env.VERIAL_API_KEY,
})
```

### Configuration Options

| Option       | Type   | Default                 | Description                                        |
| ------------ | ------ | ----------------------- | -------------------------------------------------- |
| `apiKey`     | string | Required                | Your Verial API key (starts with `vk_`)            |
| `baseUrl`    | string | `https://api.verial.ai` | API base URL (override for self-hosted or staging) |
| `timeout`    | number | `30000`                 | Request timeout in milliseconds                    |
| `maxRetries` | number | `2`                     | Number of automatic retries on failure             |

### Custom Base URL

For development or self-hosted deployments:

```typescript theme={null}
const verial = new Verial({
  apiKey: process.env.VERIAL_API_KEY,
  baseUrl: 'http://localhost:3001',
})
```

## ESM Configuration

The SDK uses ES modules. Make sure your project is configured for ESM:

**Option 1:** Set `"type": "module"` in your `package.json`:

```json theme={null}
{
  "type": "module"
}
```

**Option 2:** Use `.mts` file extensions for TypeScript files.

**Option 3:** Use a bundler (Vite, esbuild, tsup) that handles ESM resolution.

## TypeScript

The SDK ships with built-in type declarations. No additional `@types/` package is needed.

```typescript theme={null}
import Verial from '@verial-ai/sdk'
import type { Environment, Benchmark, Run, SimulatorType } from '@verial-ai/sdk'

const verial = new Verial({ apiKey: 'vk_xxx' })

const env: Environment = await verial.environments.create({
  name: 'Test Clinic',
})
```