Using connections with the Aluvia client

The Aluvia client can create a new connection, use an existing connection, and generate integration URLs so a connection can easily be used with a variety of automation tools.

Understanding the connection object

For custom workflows, you can use the flexible Aluvia API directly. The Aluvia SDK offers language-specific API wrappers.

---

Install the Aluvia client

Get Aluvia API key

1. Create an account at dashboard.aluvia.io
2. Go to Settings > API Keys and create an Account API Key

Install

npm install @aluvia/sdk

Requirements: Node.js 18 or later

Start the Aluvia client

• Use your account API key (required) as apiKey.
• If you want to reuse an existing connection, include its connectionId (optional).
• If you omit connectionId, the client automatically creates a new connection.
• Always call await connection.close() when you’re done. This stops the local proxy (default mode) and polling timers so Node.js can shut down cleanly.

import { AluviaClient } from '@aluvia/sdk';

const client = new AluviaClient({
  apiKey: process.env.ALUVIA_API_KEY!, // required
  connectionId: process.env.ALUVIA_CONNECTION_ID, // optional
});

const connection = await client.start();

// Integration and automation code...

await connection.close(); // recommended cleanup

Client configuration options

Apart from the required apiKey and the optional connectionId, there are several other configuration options you can use:

new AluviaClient({
  apiKey: string, // required
  connectionId?: string, // optional
  localProxy?: boolean, // optional, default true
  strict?: boolean, // optional, default true (fail fast if config can't be loaded/created)
  apiBaseUrl?: string, // optional, default https://api.aluvia.io/v1
  pollIntervalMs?: number, // optional, default 5000
  timeoutMs?: number, // optional, default 30000 (API wrapper HTTP only)
  gatewayProtocol?: 'http' | 'https', // optional, default http
  gatewayPort?: number, // optional, default 8080 or 8443 depending on protocol
  localPort?: number, // optional; only relevant when localProxy true
  logLevel?: 'silent' | 'info' | 'debug', // optional, default info
});

Integrate with tools

After const connection = await client.start(), the client returns a connection object with integration adapters.

Integration adapters return proxy settings in the format various tools expect:

Playwright

import { chromium } from 'playwright';
import { AluviaClient } from '@aluvia/sdk';

const client = new AluviaClient({
  apiKey: process.env.ALUVIA_API_KEY!,
  connectionId: process.env.ALUVIA_CONNECTION_ID, // optional
});

const connection = await client.start();

const browser = await chromium.launch({
  proxy: connection.asPlaywright(),
});

try {
  const page = await browser.newPage();
  await page.goto('https://ipconfig.io/json');
} finally {
  await browser.close();
  await connection.close();
}

Puppeteer

import puppeteer from 'puppeteer';
import { AluviaClient } from '@aluvia/sdk';

// Tip: For Puppeteer, `localProxy: true` (default) is recommended so you don't have to implement proxy auth yourself.
const client = new AluviaClient({
  apiKey: process.env.ALUVIA_API_KEY!,
  connectionId: process.env.ALUVIA_CONNECTION_ID, // optional
  localProxy: true, // true is default
});

const connection = await client.start();

const browser = await puppeteer.launch({
  headless: true,
  args: connection.asPuppeteer(),
});

try {
  const page = await browser.newPage();
  await page.goto('https://ipconfig.io/json', { waitUntil: 'domcontentloaded' });
} finally {
  await browser.close();
  await connection.close();
}

Selenium

import { Builder } from 'selenium-webdriver';
import chrome from 'selenium-webdriver/chrome';
import { AluviaClient } from '@aluvia/sdk';

// Tip: For Selenium, `localProxy: true` (default) is recommended so you don't have to implement proxy auth yourself.
const client = new AluviaClient({
  apiKey: process.env.ALUVIA_API_KEY!,
  connectionId: process.env.ALUVIA_CONNECTION_ID, // optional
  localProxy: true, // true is default
});

const connection = await client.start();

const options = new chrome.Options();
options.addArguments(connection.asSelenium());

const driver = await new Builder().forBrowser('chrome').setChromeOptions(options).build();

try {
  await driver.get('https://ipconfig.io/json');
} finally {
  await driver.quit();
  await connection.close();
}

Fetch

import { AluviaClient } from '@aluvia/sdk';

// Node's built-in fetch does not accept Node proxy agents. Use the undici-powered fetch adapter.
const client = new AluviaClient({ apiKey: process.env.ALUVIA_API_KEY! });
const connection = await client.start();

const fetch = connection.asUndiciFetch();

try {
  const res = await fetch('https://ipconfig.io/json');
  console.log(await res.json());
} finally {
  await connection.close();
}

Axios

import axios from 'axios';
import { AluviaClient } from '@aluvia/sdk';

const client = new AluviaClient({ apiKey: process.env.ALUVIA_API_KEY! });
const connection = await client.start();

try {
  const res = await axios.get('https://ipconfig.io/json', connection.asAxiosConfig());
  console.log(res.data);
} finally {
  await connection.close();
}

Got

import got from 'got';
import { AluviaClient } from '@aluvia/sdk';

const client = new AluviaClient({ apiKey: process.env.ALUVIA_API_KEY! });
const connection = await client.start();

try {
  const data = await got('https://ipconfig.io/json', connection.asGotOptions()).json();
  console.log(data);
} finally {
  await connection.close();
}