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

# Pilvio plugin

> Pilvio is an Estonian cloud IaaS for compute and storage. This plugin manages the user profile, API tokens and SSH keys, creates and controls virtual machines, provisions block storage disks and S3 buckets, and manages private networks and firewalls across Pilvio locations.

Use **Pilvio** through Corsair: one client, typed API calls.

Authenticate with an API token created in the Pilvio user interface; the plugin sends it in the apikey header. Every call goes against [https://api.pilvio.com/v1](https://api.pilvio.com/v1). Most write endpoints take form-encoded bodies; SSH keys and firewalls take JSON, and the plugin handles both. Answers are bare JSON objects or arrays; business errors carry \{"errors": \{"Error": …}}, and authentication failures answer 403.
Location-scoped resources live under /v1/\{slug}/… with the slug from config.listLocations (cyc01, bus02, …); without a slug the API serves the default location. Lists answer whole arrays with no pagination.
Deletes and reinstalls are destructive: vm.reinstall replaces the VM's operating system and storage.disks.delete / storage.buckets.delete / network.\*.delete remove the resource. Networks can only be deleted when empty and not the default.
The API documents more resources than this plugin covers (VM replicas, clones and backups, disk attach, floating IPs, load balancers, payments and invoices), all on the same shapes. Every operation is described in the official docs served at [https://api.pilvio.com](https://api.pilvio.com).

**What you get:**

* 40 typed API operations

## Setup

**1. Install**

```bash npm theme={null}
npm install corsair @corsair-dev/pilvio better-sqlite3
npm install --save-dev @types/better-sqlite3
```

```bash yarn theme={null}
yarn add corsair @corsair-dev/pilvio better-sqlite3
yarn add --dev @types/better-sqlite3
```

```bash pnpm theme={null}
pnpm install corsair @corsair-dev/pilvio better-sqlite3
pnpm install --save-dev @types/better-sqlite3
```

```bash bun theme={null}
bun add corsair @corsair-dev/pilvio better-sqlite3
bun add --dev @types/better-sqlite3
```

**2. Add the plugin**

```ts corsair.ts theme={null}
import Database from 'better-sqlite3';
import { createCorsair } from 'corsair';
import { pilvio } from '@corsair-dev/pilvio';

export const corsair = createCorsair({
	plugins: [
		pilvio(),
	],
	database: new Database('corsair.db'),
	kek: process.env.CORSAIR_KEK!,
	multiTenancy: true,
	hub: {
		projectApiKey: process.env.CORSAIR_API_KEY!,
		signingSecret: process.env.CORSAIR_SIGNING_SECRET!,
	},
});
```

With `multiTenancy: true`, scope calls with `corsair.withTenant(id)`. See [Quick start](https://docs.corsair.dev/quick-start.md) for KEK + Hub keys, and [Multi-tenancy](https://docs.corsair.dev/concepts/multi-tenancy.md) for account isolation.

**3. Choose authentication**

> [tab] API Key (Recommended)
>
> Store the Pilvio API key before the first call: `pnpm corsair setup --plugin=pilvio --tenant=acme api_key=<your-key>` (leave out `--tenant` without `multiTenancy`), or pass it as `key` in the plugin options. With Hub, each tenant enters their own key on the connect page. See [API key auth](https://docs.corsair.dev/concepts/api-key).
>
> ```ts theme={null}
> pilvio()
> ```
>
> More: [API Key](https://docs.corsair.dev/concepts/api-key)

**4. Connect a tenant**

Mint a connect link and send the tenant to it. Hub hosts the page and delivers the result to your app — see [Connect / OAuth](https://docs.corsair.dev/management/connect).

```ts theme={null}
const { connectUrl } = await corsair.manage.connect.createLink({
	plugin: 'pilvio',
	tenantId: 'acme',
});
// redirect the user's browser to connectUrl
```

## Example API calls

**List locations**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.pilvio.api.config.listLocations({});
```

**Create a VM**

```ts theme={null}
const tenant = corsair.withTenant('acme');
await tenant.pilvio.api.vm.create({
	name: 'web-1',
	osName: 'ubuntu',
	osVersion: '22.04-lts',
	disks: 20,
	vcpu: 2,
	ram: 2048,
});
```

See the full list on the [API](https://docs.corsair.dev/plugins/pilvio/api.md) page.

## What's next

> [card] [API reference](https://docs.corsair.dev/plugins/pilvio/api.md)
>
> Every `pilvio.api.*` operation with input and output types.

> [card] [Connect / OAuth](https://docs.corsair.dev/management/connect)
>
> createLink, Hub delivery, and tenant connect flows.

> [card] [Use with agents](https://docs.corsair.dev/mcp-adapters/mcp-adapters)
>
> Expose this plugin's operations as MCP tools.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.