Part 1: Your First Network

In this first part you’ll create an Alchemy project, connect it to your console, and deploy a lab network on its own VLAN.

Prerequisites

• Node.js 22 or later.
• A UniFi console running Network 10.6, and an API key for it. See Setup.

Your console is live

Everything in this tutorial changes your real network. You’ll build a separate lab: its own VLAN, SSID and firewall zone, which alchemy destroy removes at the end. Part 2 adopts your default network, and checks the plan first so nothing about it changes.

Create a project

Start with an empty directory and a package.json:

mkdir unifi-lab && cd unifi-lab
npm init -y
npm pkg set type=module

Install dependencies

npm

npm install @alchemy-unifi/network alchemy effect @effect/platform-node

pnpm

pnpm add @alchemy-unifi/network alchemy effect @effect/platform-node

yarn

yarn add @alchemy-unifi/network alchemy effect @effect/platform-node

Connect to your console

Add the UnifiNetwork provider to Alchemy’s default profile:

npm

npx alchemy profile edit --add UnifiNetwork

pnpm

pnpm exec alchemy profile edit --add UnifiNetwork

yarn

yarn alchemy profile edit --add UnifiNetwork

Choose Directly and give your console’s URL and Network API key, or Through ui.com with a Site Manager key. Then check the connection:

npm

npx alchemy profile show

pnpm

pnpm exec alchemy profile show

yarn

yarn alchemy profile show

You see your console’s Network version.

Create the Stack

A Stack is a set of resources Alchemy manages together. Create alchemy.run.ts:

alchemy.run.ts

import * as UnifiNetwork from "@alchemy-unifi/network";
import * as Alchemy from "alchemy";
import * as Effect from "effect/Effect";

export default Alchemy.Stack(
  "UnifiLab",
  { providers: UnifiNetwork.providers(), state: UnifiNetwork.state() },
  Effect.gen(function* () {
    // Resources go here.
  }),
);

UnifiNetwork.providers() lets the Stack manage UniFi resources, and UnifiNetwork.state() keeps the Stack’s state on your console, so there’s nothing else to set up.

Add a network

Declare a gateway network on VLAN 50, with DHCP:

alchemy.run.ts

import * as UnifiNetwork from "@alchemy-unifi/network";
import * as Alchemy from "alchemy";
import * as Effect from "effect/Effect";

export default Alchemy.Stack(
  "UnifiLab",
  { providers: UnifiNetwork.providers(), state: UnifiNetwork.state() },
  Effect.gen(function* () {
    // Resources go here.
    const lab = yield* UnifiNetwork.Network("lab", {
      management: "GATEWAY",
      name: "Lab",
      vlanId: 50,
      enabled: true,
      cellularBackupEnabled: false,
      internetAccessEnabled: true,
      isolationEnabled: false,
      zone: UnifiNetwork.FirewallZone.INTERNAL,
      ipv4Configuration: {
        autoScaleEnabled: false,
        hostIpAddress: "192.168.50.1",
        prefixLength: 24,
        dhcpConfiguration: {
          mode: "SERVER",
          ipAddressRange: { start: "192.168.50.100", stop: "192.168.50.250" },
          leaseTimeSeconds: 86400,
          pingConflictDetectionEnabled: true,
        },
      },
    });
  }),
);

Pick a VLAN ID and subnet your console doesn’t use yet.

Return an output

Return the network’s ID, so the deploy prints it:

alchemy.run.ts

import * as UnifiNetwork from "@alchemy-unifi/network";
import * as Alchemy from "alchemy";
import * as Effect from "effect/Effect";

export default Alchemy.Stack(
  "UnifiLab",
  { providers: UnifiNetwork.providers(), state: UnifiNetwork.state() },
  Effect.gen(function* () {
    const lab = yield* UnifiNetwork.Network("lab", {
      management: "GATEWAY",
      name: "Lab",
      vlanId: 50,
      enabled: true,
      cellularBackupEnabled: false,
      internetAccessEnabled: true,
      isolationEnabled: false,
      zone: UnifiNetwork.FirewallZone.INTERNAL,
      ipv4Configuration: {
        autoScaleEnabled: false,
        hostIpAddress: "192.168.50.1",
        prefixLength: 24,
        dhcpConfiguration: {
          mode: "SERVER",
          ipAddressRange: { start: "192.168.50.100", stop: "192.168.50.250" },
          leaseTimeSeconds: 86400,
          pingConflictDetectionEnabled: true,
        },
      },
    });
    return { labNetworkId: lab.networkId };
  }),
);

Deploy

npm

npx alchemy deploy --stage home

pnpm

pnpm exec alchemy deploy --stage home

yarn

yarn alchemy deploy --stage home

The stage names this deployment of the Stack. You’ll use home throughout, and add a second site in Part 6.

Verify it worked

Open your console’s Network app, then Settings → Networks. Lab is there, on VLAN 50.

Recap

You created a project, connected it to your console, and deployed a network. Next, in Part 2, you’ll take over a network that already exists: your default network.