Skip to main content

Installation

To get started with nilbox, first install the desktop app, then install the Linux for nilbox operating system during the first launch.

Linux for nilbox is a dedicated Linux environment managed by nilbox, and is the operating system where agents like OpenClaw actually run. Regardless of whether your current OS is macOS, Windows, or Linux, this Linux environment is installed separately.

Step 1: Download the Desktop App​

Download the nilbox desktop app for your current operating system.

Visit the nilbox Download Page and download the version for your operating system:

🍎 macOS

Desktop app for Mac (Intel, Apple Silicon)

Download for Mac

🪟 Windows

Desktop app for Windows 10 and above

Download for Windows

🐧 Linux

Desktop app for Linux (.deb package)

Download for Linux

System Requirements​

Check the following requirements before installation:

PlatformMinimumRecommended
macOS13.0 (Ventura)Latest version
WindowsWindows 10Windows 11
Linuxglibc 2.29+Ubuntu 18.04 LTS+

Install the Desktop App​

Install the nilbox desktop app according to your operating system.

macOS​

  1. Download the .dmg file from the download page.
  2. Open the downloaded .dmg file.
  3. Drag the nilbox app icon to the Applications folder.
  4. Launch nilbox from Applications or Spotlight.

Windows​

  1. Download the installer (.exe) from the download page.
  2. Run the installer and follow the on-screen instructions.
  3. Select an installation path. Using the default path is recommended.
  4. Complete the installation.
  5. Launch nilbox from the Start menu or the desktop shortcut.

Linux​

Option A: .deb Package (Debian/Ubuntu)​

  1. Download the .deb file from the download page.
  2. Install the package: 
    sudo dpkg -i nilbox-*.deb
  3. Launch nilbox from the application menu or terminal: 
    nilbox

Step 2: Install Linux for nilbox​

After installing the desktop app, the Linux for nilbox installation process begins the first time you launch nilbox.

What is Linux for nilbox?​

  • Linux for nilbox is a Linux operating system directly managed by nilbox.
  • Agents like OpenClaw run inside this Linux environment.
  • It is installed separately regardless of whether your host OS is macOS, Windows, or Linux.
  • In other words, the desktop app is installed on your host OS, while the agent runtime environment is set up in Linux for nilbox.

Installation Flow​

  1. Launch nilbox for the first time.
  2. When the Linux for nilbox installation screen appears, proceed with the Set Up nilbox installation.

nilbox Linux for nilbox setup screen

  1. When the disk size configuration screen appears, review the default value.
  2. The initial disk size is set to the minimum, so you must increase it by at least 4–5 GB above the default.
  3. If you have spare disk space, it is recommended to set it generously for future use.

Resize disk

Example: disk size changed to 7 GB

  1. nilbox automatically prepares the required Linux environment and runtime configuration.
  2. Once installation is complete, nilbox is ready to run agents based on that Linux environment.
Disk size recommendation

The default disk size is set to the minimum capacity. If you install with too little space, you may quickly run out of room during agent execution, package installation, and saving work files — so it is best to allocate plenty of space at installation time.

Why this step is required

nilbox does not run agents directly on the host operating system. Instead, it sets up a consistent Linux runtime environment managed by nilbox, so agents run the same way regardless of your OS.

Verify Installation​

Check the following to confirm that installation completed successfully:

  1. The nilbox application launches without errors.
  2. On first launch, the Linux for nilbox installation flow is shown, or you can confirm its completed state.
  3. The disk size is set to at least 4–5 GB above the default minimum.
  4. The nilbox screen opens without errors.
  5. You are ready to install agents.

If you encounter any issues, refer to the troubleshooting documentation to be added later.

Next Steps​

Once installation is complete, proceed to the next step:

  • Basic Setup — Configure your initial workspace
  • Creating Your First Project — Start your first project