Introduction

Welcome to NetDefense — a CLI-first management platform for teams running fleets of decentralized OPNsense firewalls. This page is the complete path from “no account” to “device authorized and managed.” It takes about 15 minutes and you shouldn’t need to leave this page.

You’ll need one thing you don’t already have from NetDefense: an OPNsense 25.7 firewall you can reach via a physical keyboard/monitor, a VM console, or SSH. Everything else — your account, your organization, the agent — gets created along the way.

Step 1: Create a NetDefense account

Both routes below end up in the same place: an account with credentials set, mandatory multi-factor authentication (MFA) enrolled, and NDWeb showing an empty environment with no organizations yet.

Web

1. Go to app.netdefense.io and select Get Started.
2. On the login screen, choose to create a new account and set your email and password.
3. Complete the mandatory MFA setup — every new account enrolls an authenticator app before it can do anything else.

You land on an empty dashboard — no organizations yet.

CLI

Install NDCLI first if you haven’t (platform-specific instructions), then run the guided setup wizard:

ndcli setup

1. The wizard opens your browser for interactive login. There’s no terminal-only way to create an account — set your email and password there, and complete the same mandatory MFA setup as the Web route.
2. Once you’re authenticated, the wizard returns you to the terminal and immediately continues into organization setup — that’s Step 2 below, so keep this session open.

Tip

ndcli setup also runs automatically the first time you use any ndcli command with no config file yet, so you don’t have to remember to invoke it by name. Prefer to do just the login step by hand? ndcli auth login runs the same browser-based flow on its own — see the auth reference.

Step 2: Create an organization

An organization is NetDefense’s top-level container — every device, policy, and account lives inside one. You need one before you can deploy NDAgent in Step 3. Creating one only takes a name.

Note

Already invited to someone else’s organization instead of starting your own? Skip creating one — accept the invitation (Web: the Join an Organization card on your dashboard; CLI: ndcli setup detects it and offers to accept automatically, or run ndcli org invite accept <org-name>) and ask that organization’s admin for the registration token, then go straight to Step 3.

Web

1. From the dashboard, select Create Your Organization (or Organizations → + New Organization).
2. Name it — lowercase letters, numbers, and hyphens only. You become its first Admin.

That’s it. The organization’s registration token is embedded automatically when you deploy a device in Step 3 — you won’t need to copy or track it by hand.

CLI

Continuing the ndcli setup session from Step 1: when it asks, answer yes to Create your first organization? and give it a name — that’s the only required field.

The wizard prints your registration token directly in its closing summary. Copy it now; you’ll need it in Step 4.

Prefer to skip the wizard? Create the organization directly and the token prints immediately:

ndcli org create acme-lab

✓ Organization created and set as default: acme-lab
  Token: 9fc86b59-a821-465a-bb29-6ffd7f3a9165

Use this token to register devices with the NetDefense agent.
To retrieve the token later: ndcli org describe acme-lab

Misplaced it later? ndcli org describe <org-name> prints it again under Registration Token.

Step 3: Install NDAgent

From here the two routes converge on where you install — NDAgent goes on the OPNsense box itself, not on your workstation — though the exact command you’ll run still depends on which route you took.

Get a root prompt on the firewall

1. Prerequisite: console access to the OPNsense box — a physical keyboard/monitor, a VM console through your hypervisor, or SSH.
2. Planning to use SSH and it’s never been turned on for this device? Log in to the OPNsense web interface (reachable by default at https://<lan-ip>) and go to System → Settings → Administration. Check Secure Shell Server and Save.
3. Connect using whichever access method you have — keyboard/monitor, VM console, or ssh root@<lan-ip>. All three land on the same OPNsense console menu.
4. From the menu, choose 8) Shell to drop to a root prompt.

Install OPNsense plugin

Web

Go to Devices and select Deploy Device (the same button appears in the empty state, since this is your first device). In the dialog’s Unattended tab, copy the install command — your registration token is already embedded — and paste it at the root prompt:

curl -sSL https://repo.netdefense.io/install.sh | sh -s -- --auto-setup=<token>

This installs the plugin, provisions its OPNsense API credentials, and registers the device — all in one step. Skip ahead to Step 5 to approve it.

Would rather not put a live credential into this shell’s history? Switch to the dialog’s Manual tab for a plain install command plus the token shown separately, then continue to Step 4 to finish configuring the plugin by hand.

CLI

curl -sSL https://repo.netdefense.io/install.sh | sh

This is the exact command ndcli setup printed for you at the end of Step 1/2. It sets up the NetDefense package repository and installs the plugin; continue to Step 4 to finish configuring it from the web UI with the token you copied in Step 2.

Tip

Rolling this out to a whole fleet, doing an air-gapped install, or want more detail on the unattended (--auto-setup), manual-repository, or offline-package methods? See the full NDAgent Installation guide. This page only covers the interactive quick install for a single device.

Close up

1. Exit the shell (exit) to return to the console menu, then log out (0) Logout) or disconnect.
2. Only turned on Secure Shell for this install? Turn it back off the same way you enabled it — System → Settings → Administration → Secure Shell Server, unchecked, Save.

Step 4: Configure the NetDefense plugin

Note

Took the Web route and used the Unattended install command in Step 3? The plugin is already configured and registering — skip ahead to Step 5. This step is for the CLI route, or if you used the Web route’s Manual install variant.

Installing the package doesn’t connect anything yet. The plugin needs its own OPNsense API credentials and your organization’s registration token before it will register with NetDefense.

1. In the OPNsense web interface, go to Services → NetDefense → Settings.
2. Under API Configuration, select Setup API Credentials. This provisions a dedicated netdefense-agent OPNsense user with the minimum privileges the agent needs — you don’t fill in anything yourself.
3. Under Service Configuration, paste the registration token — from Step 2 if you took the CLI route, or from the org’s Device Registration card or the deploy dialog’s Manual tab if you took the Web route — into Registration Token, and check Enable NetDefense Agent.
4. Click Apply.

The agent starts and registers with NetDefense. Watch it happen under Services → NetDefense → Log File, or see the full field-by-field breakdown in Configuration.

Step 5: Authorize the device

The agent is now talking to NetDefense, but it sits in PENDING until someone approves it — a deliberate checkpoint so a leaked registration token can’t silently add a rogue device to your fleet.

Web

Go to Devices. Your firewall appears with status PENDING. Open its row’s … menu and select Approve.

CLI

ndcli device list --status PENDING

ndcli device approve <device-name>

Approving a whole batch of freshly-installed devices at once? ndcli device approve-all approves everything currently PENDING.

Once approved, the device is ENABLED and ready to receive policy.

You’re managing your first firewall

From here, everything else in NetDefense builds on what you just set up — assign the device to an organizational unit, attach a template, and sync it.

Getting Started

Core concepts — the policy chain, sync, VPN, and more.

Continue

NDCLI

The full command-line reference.

View NDCLI Docs

NDAgent

Advanced install methods, updates, and troubleshooting.

View NDAgent Docs

MCP Server

Drive NetDefense from Claude Code, Claude Desktop, or any MCP-compatible client.

View MCP Docs

Need Help?

Have questions about NetDefense? Contact us or visit app.netdefense.io to get started.