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

# Add a box

> Register a box, install Stout on it, and copy boxes between Stout and the Lager CLI.

To add a box, you register it in Stout, and then you install Stout on it. Only owners and admins can add boxes.

## Before you start

Make sure that these conditions are true:

* The box runs Lager. See [Setting up a Lager Box](https://docs.lagerdata.com/source/getting-started/setting-up-a-lager-box) in the Lager docs.
* Stout can reach the box at its IP address.
* You know the name of the SSH account on the box.
* For a box that you never prepared for Stout, you know the password of that account.

Stout refuses some addresses, for example loopback and link-local addresses.

## Set a default box username

An owner can set a **Default Box Username** in **Settings** > **General**. Stout fills in this username when you add or import a box. You can change the username of each box later on its **Settings** tab.

## Register a box

1. Open **Boxes**, and then select **Add Box**.
2. Enter the **Box Name**.
3. Enter the **IP Address** of the box.
4. Check the **Username**. Stout uses this SSH account on the box.
5. If you want the box in a group, select the group in **Group (optional)**.
6. If you want to set up nets from a template, select the template in **Template (optional)**. Stout creates the nets when the box first comes online.
7. Select **Add Box**.

The **Group (optional)** field appears only when your organization has box groups. For more about templates, see [Templates](/source/boxes/nets-and-templates#templates).

After you add the box, open its page to install Stout.

## Install Stout

When the Stout container on a box is not healthy, the box page opens the **Install Stout before proceeding** window. Only owners and admins can start the install.

1. If this is the first setup of the box, enter the password of the box account in **Box account password (optional)**. If you prepared the box for Stout before, leave the field empty.
2. Select **Install Stout**.

Stout uses the password once, for this install. Stout does not store the password.

The window shows the four steps of the install:

1. **Install requested**
2. **Write control-plane config**
3. **Start Stout container**
4. **Verify health on :9001**

To see the install output, select **View log**. If one step takes more than 3 minutes, the window tells you to check the log.

If the install fails, the window shows the error. Correct the problem, and then select **Install Stout** again.

The install does these things on the box:

* It writes the connection settings and the Stout SSH key.
* It sets up the `sudo` rules that Stout needs.
* It installs the rules that let Lager reach USB instruments.
* It starts the `stout` container and checks that the container is healthy.
* It turns on the access guard and asks for the SSH lockdown. See [Security and access](/source/boxes/security-and-access).

### After the install

After the install, the window changes to **Securing this box…**. It shows two lines: **Who can use this box** and **Who can log in over SSH**. The window closes by itself when the box is secure.

To use the box page before then, select **Open the box page anyway →**. To leave, select **← Go Back**.

## Import boxes from the Lager CLI

The Lager CLI keeps its list of boxes in the `.lager` file in your home directory. You can import that list into Stout.

1. Open **Boxes**.
2. Open the **…** menu, and then select **Import from Lager**.
3. Pick your `.lager` file. If the file picker does not open, select **Choose File**.
4. Check the preview. It shows the **Name**, **IP Address**, **SSH User**, and **Version** of each box.
5. Select the import button, for example **Import 3 Boxes**.
6. In **Step 2: Install Stout on Boxes**, find the **Box account password (optional)** field. If this is the first setup of the boxes, enter the password of the box account. If you prepared the boxes for Stout before, leave the field empty.
7. Select **Install from Dashboard** for a box. To install on many boxes, select them, and then select **Install Selected from Dashboard**.
8. Select **Done**.

The import follows these rules:

* If Stout already has a box with the same name, the import updates its IP address. It also updates the username when the file has one.
* A new box needs a username. The import uses the `user` value from the file, or else the default box username. If neither exists, the import rejects the box.
* The import rejects a box with an address that Stout refuses.

Each install that you start from the import window uses the password in that field. Stout uses the password only for those installs, and it does not store the password.

## Export boxes to the Lager CLI

**Export to Lager** gives you Lager CLI commands that copy your Stout boxes into the Lager CLI on your computer.

<Warning>
  Before you run the exported commands, write down every box in your local Lager CLI list that is not in Stout. The first command deletes all boxes from that list.
</Warning>

1. Open **Boxes**.
2. Open the **…** menu, and then select **Export to Lager**.
3. In **Export to Lager CLI**, read the commands.
4. Select **Copy to Clipboard**.
5. Paste the commands into a terminal on your computer, and run them.

The first command is `lager boxes delete-all --yes`. Each next command adds one box with `lager boxes add` and the SSH username of that box. The export skips boxes that have no IP address.

For the commands, see [lager boxes](https://docs.lagerdata.com/source/reference/cli/boxes) in the Lager docs.

<CardGroup cols={2}>
  <Card title="Security and access" href="/source/boxes/security-and-access">
    See what the install turns on, and give people access.
  </Card>

  <Card title="Nets and templates" href="/source/boxes/nets-and-templates">
    Name the instrument channels on the new box.
  </Card>
</CardGroup>