# xen-api

> Connector to the Xen API

Latest version **4.9.0** (published 2026-08-25) · ISC license · 0 weekly downloads

## Install

```sh
npm install xen-api
pnpm add xen-api
yarn add xen-api
bun add xen-api
```

Provides the command `xen-api`.

## Health

**Score 55/100 (C)** — status: active.

Positive: no vulnerabilities; recently updated; high maintenance score.

Warnings: low downloads; no types; no esm support.

## Facts

| | |
|---|---|
| Version | 4.9.0 |
| Published | 2026-08-25 |
| First published | 2015-04-10 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | none |
| Module format | CommonJS |
| Node | >=18 |
| Dependencies | 23 |
| Unpacked size | 75.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 989 |
| Author | Vates SAS |
| Maintainers | julien-f, marsaud, pdonias, tgoettelmann, mathieura, florent.beauchamp, mpiton, b-nollet, mlssfrncjrg, olivier.f, pierre.brunet289, elise-f |
| Keywords | xen, api, xen-api, xenapi, xapi |

## Links

- npm: https://www.npmjs.com/package/xen-api
- Repository: https://github.com/vatesfr/xen-orchestra
- Homepage: https://github.com/vatesfr/xen-orchestra/tree/master/packages/xen-api
- Issues: https://github.com/vatesfr/xen-orchestra/issues
- npm.io page: https://npm.io/package/xen-api

## Dependencies (23)

- [ms](https://npm.io/package/ms.md) ^2.1.1
- [pw](https://npm.io/package/pw.md) 0.0.4
- [lodash](https://npm.io/package/lodash.md) ^4.18.0
- [undici](https://npm.io/package/undici.md) ^6.2.1
- [blocked](https://npm.io/package/blocked.md) ^1.2.1
- [minimist](https://npm.io/package/minimist.md) ^1.2.0
- [jest-diff](https://npm.io/package/jest-diff.md) ^29.0.3
- [xo-common](https://npm.io/package/xo-common.md) ^0.11.0
- [@vates/xml](https://npm.io/package/@vates/xml.md) ^2.0.0
- [make-error](https://npm.io/package/make-error.md) ^1.3.0
- [proxy-agent](https://npm.io/package/proxy-agent.md) ^6.3.1
- [xo-collection](https://npm.io/package/xo-collection.md) ^0.6.1
- [@vates/compose](https://npm.io/package/@vates/compose.md) ^2.1.0
- [@vates/xml-rpc](https://npm.io/package/@vates/xml-rpc.md) ^1.0.0
- [promise-toolbox](https://npm.io/package/promise-toolbox.md) ^0.21.0
- [@vates/json-hash](https://npm.io/package/@vates/json-hash.md) ^0.2.0
- [@vates/obfuscate](https://npm.io/package/@vates/obfuscate.md) ^0.1.0
- [json-rpc-protocol](https://npm.io/package/json-rpc-protocol.md) ^0.13.1
- [@xen-orchestra/log](https://npm.io/package/@xen-orchestra/log.md) ^0.7.2
- [@vates/decorate-with](https://npm.io/package/@vates/decorate-with.md) ^2.1.0
- [@vates/coalesce-calls](https://npm.io/package/@vates/coalesce-calls.md) ^0.1.0
- [bind-property-descriptor](https://npm.io/package/bind-property-descriptor.md) ^2.0.0
- [limit-concurrency-decorator](https://npm.io/package/limit-concurrency-decorator.md) ^0.6.0

## Recent versions

- 4.9.0 (latest) — 2026-08-25
- 4.8.0 — 2026-07-27
- 4.7.8 — 2026-06-24
- 4.7.7 — 2026-04-24
- 4.7.6 — 2025-12-18
- 4.7.5 — 2025-11-24
- 4.7.4 — 2025-08-27
- 4.7.3 — 2025-07-03
- 4.7.2 — 2025-06-23
- 4.7.1 — 2025-02-26
- 4.7.0 — 2024-12-18
- 4.6.0 — 2024-12-16
- 4.5.0 — 2024-10-30
- 4.4.0 — 2024-10-28
- 4.3.2 — 2024-09-30
- … 151 more at https://npm.io/package/xen-api/versions

## README

<!-- DO NOT EDIT MANUALLY, THIS FILE HAS BEEN GENERATED -->

# xen-api

[![Package Version](https://badgen.net/npm/v/xen-api)](https://npmjs.org/package/xen-api) ![License](https://badgen.net/npm/license/xen-api) [![PackagePhobia](https://badgen.net/bundlephobia/minzip/xen-api)](https://bundlephobia.com/result?p=xen-api) [![Node compatibility](https://badgen.net/npm/node/xen-api)](https://npmjs.org/package/xen-api)

> Connector to the Xen API

## Install

Installation of the [npm package](https://npmjs.org/package/xen-api):

```sh
npm install --save xen-api
```

## Usage

Tested with:

- XenServer 7.6
- XenServer 7.5
- XenServer 7.4
- XenServer 7.3
- XenServer 7.2
- XenServer 7.1
- XenServer 7
- XenServer 6.5
- XenServer 6.2
- XenServer 5.6

### Library

```javascript
const { createClient } = require('xen-api')

const xapi = createClient({
  url: 'https://xen1.company.net',
  allowUnauthorized: false,
  auth: {
    user: 'root',
    password: 'important secret password',
  },
  readOnly: false,
})
```

Options:

- `url`: address of a host in the pool we are trying to connect to
- `allowUnauthorized`: whether to accept self-signed certificates
- `auth`: credentials used to sign in (can also be specified in the URL)
- `readOnly = false`: if true, no methods with side-effects can be called
- `callTimeout`: number of milliseconds after which a call is considered failed (can also be a map of timeouts by methods)
- `httpProxy`: URL of the HTTP/HTTPS proxy used to reach the host, can include credentials
- `candidateHostnames`: addresses of other pool members to fall back on when the configured target becomes unreachable (e.g. the master died and another host took over). Refreshed automatically from the pool on each connection and exposed back through the `candidateHostnames` getter, so a caller can persist them and feed them back across restarts
- `probeTimeout = 20e3`: number of milliseconds after which an unreachable member is given up on while probing for a survivor

```js
// Force connection.
xapi.connect().catch(error => {
  console.error(error)
})

// Watch objects.
xapi.objects.on('add', objects => {
  console.log('new objects:', objects)
})
```

> Note: all objects are frozen and cannot be altered!

Custom fields on objects (hidden − ie. non enumerable):

- `$type`: the type of the object (`VM`, `task`, …);
- `$ref`: the (opaque) reference of the object;
- `$id`: the identifier of this object (its UUID if any; otherwise, its reference);
- `$pool`: the pool object this object belongs to.

Furthermore, any field containing a reference (or references if an
array) can be resolved by prepending the field name with a `$`:

```javascript
console.log(xapi.pool.$master.$resident_VMs[0].name_label)
// vm1
```

#### Calling a XAPI method

For very fast methods, use `call(method, ...args)`:

```js
const nameLabel = await xapi.call('VM.get_name_label', vmRef)
```

For methods that could take some time (doing an action, etc.), use `callAsync(method, ...args)`, it will automatically call the asynchronous variant of the method and monitor the associated task:

```js
const snapshotRef = await xapi.callAsync('VM.snapshot', vmRef, 'My snapshot')
```

Both `call()` and `callAsync()` accepts an optional `Map`-like object as a first parameter to use as a cache:

```js
// to avoid leaking memory, make sure to not keep entries forever
//
// see:
// - https://www.npmjs.com/package/@isaacs/ttlcache
// - https://www.npmjs.com/package/lru-cache
const cache = new Map()

// the first time, the call is really executed
console.log(await xapi.call(cache, 'VM.get_name_label', vmRef))

// next times, the value of the cache is directly returned
console.log(await xapi.call(cache, 'VM.get_name_label', vmRef))

// to delete the entry from the cache, simply compute the key
const key = xapi.computeCacheKey('VM.get_name_label', vmRef)
cache.delete(key)
```

> Note: Failures are not cached.

### CLI

A CLI is provided to help exploration and discovery of the XAPI.

```
> xen-api xen1.company.net root
Password: ******
root@xen1.company.net> xapi.status
'connected'
root@xen1.company.net> xapi.pool.master
'OpaqueRef:ec7c5147-8aee-990f-c70b-0de916a8e993'
root@xen1.company.net> xapi.pool.$master.name_label
'xen1'
```

You can optionally prefix the address by a protocol: `https://` (default) or `http://`.

In case of error due to invalid or self-signed certificates you can use the `--allow-unauthorized` flag (or `--au`):

```
> xen-api --au xen1.company.net root
```

To ease searches, `find()` and `findAll()` functions are available:

```
root@xen1.company.net> findAll({ $type: 'VM' }).length
183
```

To get a record from the local cache:

```
root@xen1.company.net> vm = getObject('17ccab66-9cc0-90a4-71a5-95874f9ad5e0')

root@xen1.company.net> vm.name_label
'My VM'

root@xen1.company.net> vm.$ref
'OpaqueRef:9a533a13-64bf-4755-ad6a-9b0f67d686ca'
```

To call a XAPI method:

```
root@xen1.company.net> call('VM.start', 'OpaqueRef:9a533a13-64bf-4755-ad6a-9b0f67d686ca', false, false)
''

root@xen1.company.net> vm.$call('start', false, false)
''
```

To call a XAPI method

## Contributions

Contributions are _very_ welcomed, either on the documentation or on
the code.

You may:

- report any [issue](https://github.com/vatesfr/xen-orchestra/issues)
  you've encountered;
- fork and create a pull request.

## License

[ISC](https://spdx.org/licenses/ISC) © [Vates SAS](https://vates.fr)

---
_Source: https://npm.io/package/xen-api · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._