---
sidebar_position: 1
title: Installation
description: Install and configure the official Firetell Node.js / TypeScript Server SDK (@firetell/firetell-node-sdk).
---

# Installation & Setup

The `@firetell/firetell-node-sdk` package is the official **server-to-server** Node.js and TypeScript SDK for the **Firetell Workspace API**. Use it from your backend services to initiate programmable voice calls, send SMS/MMS messages, manage Voice AI agents, upload Knowledge Base documents, administer agents/teams/SIP accounts, and verify incoming webhook signatures.

- **Package:** [`@firetell/firetell-node-sdk`](https://www.npmjs.com/package/@firetell/firetell-node-sdk)
- **Repository:** [`github.com/firetellcom/firetell-node-sdk`](https://github.com/firetellcom/firetell-node-sdk)
- **License:** MIT
- **Zero runtime dependencies** (uses native Node.js 18+ `fetch`, `FormData`, `Blob`, and `node:crypto`)
- **Dual format:** ESM (`.mjs`) and CommonJS (`.cjs`) with full TypeScript declarations (`.d.ts` / `.d.cts`)

---

## Requirements

- **Node.js `>= 18.0.0`**

---

## 1. Install via Package Manager

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

<Tabs>
<TabItem value="npm" label="npm" default>

```bash
npm install @firetell/firetell-node-sdk
```

</TabItem>
<TabItem value="yarn" label="yarn">

```bash
yarn add @firetell/firetell-node-sdk
```

</TabItem>
<TabItem value="pnpm" label="pnpm">

```bash
pnpm add @firetell/firetell-node-sdk
```

</TabItem>
</Tabs>

---

## 2. Initialize the Client

Authenticate using your **Workspace Domain** (e.g. `yourcompany.firetell.app`) and your **API Secret Key** (`sk-...`). The SDK automatically sends `Authorization: ApiKey <secretKey>` on every request to `https://{domain}/api/v1`.

<Tabs>
<TabItem value="ts" label="TypeScript / ESM" default>

```typescript
import { Firetell } from '@firetell/firetell-node-sdk';

const firetell = new Firetell({
  domain: 'yourcompany.firetell.app',
  secretKey: process.env.FIRETELL_SECRET_KEY!,
});
```

</TabItem>
<TabItem value="cjs" label="JavaScript (CommonJS)">

```javascript
const { Firetell } = require('@firetell/firetell-node-sdk');

const firetell = new Firetell({
  domain: 'yourcompany.firetell.app',
  secretKey: process.env.FIRETELL_SECRET_KEY,
});
```

</TabItem>
</Tabs>

> [!WARNING]
> **Server-side use only:** Never expose your API Secret Key (`sk-...`) in browser or mobile client code. For browser/mobile WebRTC calling, use [`@firetell/firetell-client-sdk`](/developers/sdks/javascript/installation) or [`firetell_flutter_sdk`](/developers/sdks/flutter/installation) with short-lived Agent JWT tokens.

---

## 3. Configuration Options

```typescript
const firetell = new Firetell({
  // Required: workspace domain or full URL (e.g. "yourcompany.firetell.app" or "https://yourcompany.firetell.app")
  domain: 'yourcompany.firetell.app',

  // Required: workspace API secret key (sent as "Authorization: ApiKey <secretKey>")
  secretKey: process.env.FIRETELL_SECRET_KEY!,

  // Optional: default request timeout in ms (default: 30000)
  timeout: 30_000,

  // Optional: automatic retries on 429, 5xx, and transient network errors (default: 2)
  maxRetries: 2,

  // Optional: default custom headers attached to every request
  headers: {
    'X-App-Name': 'my-backend-service',
  },

  // Optional: custom fetch implementation (useful for testing or custom proxies)
  fetch: customFetch,
});
```

### Per-Request Options

Every SDK method accepts an optional `RequestOptions` object as its final parameter to override timeout, attach headers, or pass an `AbortSignal`:

```typescript
const controller = new AbortController();

const calls = await firetell.calls.list(
  { direction: 'outbound', page: 1, limit: 20 },
  {
    timeout: 10_000,
    signal: controller.signal,
    headers: { 'X-Request-Trace': 'req-123' },
  },
);
```

---

## Related Documentation

- [Quickstart Guide](/developers/sdks/nodejs/quickstart)
- [API Reference](/developers/sdks/nodejs/api-reference)
- [Authentication](/developers/getting-started/authentication)
- [Workspace API Reference](/developers/rest-api/overview)
