# Initial setup

Source: [https://docs.aventail.co.uk/docs/getting-started/initial-setup](https://docs.aventail.co.uk/docs/getting-started/initial-setup)

Connect the device that will run your model, then make it available to Workspace or your software.

For the Aventail Link 2.0.0 desktop walkthrough, you need an **Apple Silicon Mac**, an available device slot and internet access. The package installs for your macOS user. Allow disk space and memory for the model and its engine. Terminal alternatives are under [Connect your device](https://docs.aventail.co.uk/docs/getting-started/initial-setup#connect-your-device).

## Sign in to Control

Use the same account and environment in Control and Aventail Link. The captured 2.0.0 build opened development Control; use the download and account for your intended environment. Production and development registrations are separate.

### Sign in to Control

Sign-in interface example; use the same account in Link.

1.  **Choose your sign-in method**
    
    Open Control and use Google, GitHub or your email and password. Use the provider you originally registered with.
    
    [Screenshot: Sign-in form — close-up from Control sign-in page.](https://docs.aventail.co.uk/img/sign_in_1_-.png)
    
2.  **Continue into setup**
    
    For a new account, review the terms and close What’s new. Control opens the three-stage setup wizard.
    
    [Screenshot: Control setup showing Platform, Connect and Deploy, with macOS selected.](https://docs.aventail.co.uk/img/control/setup-wizard/platform.jpg)
    

**Read the sign-in steps**

Open [Control](https://control.locai.co.uk/login). Choose **Continue with Google**, **GitHub**, or enter your email and password and select **Sign In**. Complete authentication to open the **Dashboard**.

On first sign-in, review the **Terms & Conditions** and accept if you agree. Close **What's new** if it appears to reach the setup wizard below.

### Trouble signing in?

-   Use the provider you originally used; another provider may open a different account.
-   For email/password access, select **Forgot password?** to start recovery.
-   If your organisation manages access, ask its administrator which sign-in method to use.

## Web setup wizard

The production Control walkthrough shows **Register your first device**, with **Platform → Connect → Deploy**. This is separate from Aventail Link's **Connect → Models → Serving → Finish** desktop setup; an organisation's development interface can differ.

### Connect your first device

Control setup screens captured 28 September 2026.

1.  **Choose a platform**
    
    Choose macOS for the Apple Silicon desktop app, then Continue. Terminal alternatives are under Advanced.
    
    [Screenshot: Platform selection — close-up from Control setup wizard.](https://docs.aventail.co.uk/img/guides/context/wizard-platform.png)
    
2.  **Download and connect**
    
    Install Link, then sign in with the same Control account. Wait for your Mac to connect before continuing.
    
    Older Control capture. Check the downloaded version; Aventail Link 2.0.0 has a different installer and setup.
    
    [Screenshot: Control Connect step with Download Locai Link for macOS and connection status.](https://docs.aventail.co.uk/img/control/setup-wizard/connect-macos.jpg)
    
3.  **Deploy the starter model**
    
    Choose Deploy model and keep Link running. After deployment, open Serving to start the model.
    
    The device name and available model can differ.
    
    [Screenshot: Control recommending Gemma 4 (X-Small), with the Deploy model button.](https://docs.aventail.co.uk/img/control/setup-wizard/deploy-model.jpg)
    
4.  **Resume setup**
    
    Close the wizard to minimise it. Use Finish setup to return; check deployment progress before retrying.
    
    [Screenshot: Finish setup button with its current step indicator.](https://docs.aventail.co.uk/img/control/setup-wizard/resume.jpg)
    

**Read the wizard steps**

### Open setup

After first sign-in, the wizard opens over the Control Dashboard with **macOS · Alpha · Apple Silicon** selected. If it is minimised, use **Finish setup** at the bottom-right.

### Choose a platform

-   **Apple Silicon Mac:** select **Continue** for the desktop app. Older Control screens label the button **Download Locai Link for macOS**; check the package version before following the Aventail 2.0.0 steps below.
-   **Terminal installation:** expand **Advanced: install via terminal** and choose **Linux / macOS (terminal)** or **Windows PowerShell**. Follow [headless registration](https://docs.aventail.co.uk/docs/getting-started/initial-setup#headless).

### Pause and resume

Select the **×** in the wizard header to minimise it, then **Finish setup** to reopen it. Before registration, the paused step also survives a page reload.

If a reloaded or second tab cannot resume deployment, check **Notifications → Deployments** before trying again. Once the model is **Deployed**, [start serving](https://docs.aventail.co.uk/docs/getting-started/initial-setup#start-serving); you do not need to download it again.

## Connect your device

Choose desktop sign-in or headless registration, then confirm the device is **Online**.

[Download Link for macOS (Apple Silicon)](https://get.aventail.co.uk/releases/latest/aventail-link-desktop-macos-arm64.pkg). This is the production release. For a development or staging account, use the download offered by that Control environment.

### Install Aventail Link on your Mac

Aventail Link 2.0.0 · Apple Silicon · captures from 2 October 2026.

1.  **Open the package**
    
    Open the macOS ARM64 .pkg supplied for your Control environment, then choose Continue.
    
    [Screenshot: Introduction and Continue — close-up from Aventail Link installer.](https://docs.aventail.co.uk/img/link/installation-2.0.0/macos-introduction.png)
    
2.  **Install for your user**
    
    Choose Install. This package installs into your home folder and is available to your macOS user.
    
    [Screenshot: Aventail Link installation type showing 33.1 MB and installation in the home folder.](https://docs.aventail.co.uk/img/link/installation-2.0.0/macos-installation-type.png)
    
3.  **Finish the installer**
    
    Wait for The installation was successful, then choose Close. The separate Aventail Link Setup window opens.
    
    [Screenshot: Aventail Link installer reporting successful installation.](https://docs.aventail.co.uk/img/link/installation-2.0.0/macos-installation-result.png)
    
4.  **Sign in to Aventail**
    
    Select Sign in with Aventail. In the browser, check the account and organisation before approving this device.
    
    The captured 2.0.0 build opens development Control. Use the environment intended for your package.
    
    [Screenshot: Full Aventail Link Setup window at Connect, with Sign in with Aventail and the four setup stages.](https://docs.aventail.co.uk/img/link/installation-2.0.0/setup-connect.png)
    
5.  **Choose your models**
    
    Tick a model to start downloading it. You can leave all models unticked to deploy from Control later, then select Continue.
    
    Available models depend on your account. This capture shows the development catalogue.
    
    [Screenshot: Full Aventail Link Setup window at Models, with the account model catalogue, download sizes and Continue.](https://docs.aventail.co.uk/img/link/installation-2.0.0/setup-models.png)
    
6.  **Let the download finish**
    
    Selecting a model starts its download immediately. Wait for it to finish before expecting a serving toggle on the next screen.
    
    This example uses a 2.0 GB model from the development account.
    
    [Screenshot: Full Aventail Link Setup window at Models, with llama\_3.2-3B-Instruct selected and downloading at 25 percent.](https://docs.aventail.co.uk/img/link/installation-2.0.0/setup-downloading.png)
    
7.  **Start serving**
    
    Once the download is complete, tick the installed model to serve it on port 8100, then choose Continue.
    
    The image shows the model before its serving checkbox is turned on.
    
    [Screenshot: Full Aventail Link Setup window at Serving, with the installed Llama model, its unchecked serving checkbox, Back and Continue.](https://docs.aventail.co.uk/img/link/installation-2.0.0/setup-serving.png)
    
8.  **Finish setup**
    
    Check All set and the installed/serving counts, then select Finish at the bottom-right of the setup window.
    
    Redacted copy of the supplied capture. This walkthrough finished with one model serving.
    
    [Screenshot: Full Aventail Link Setup window at Finish, showing 1 installed and 1 serving and the Finish button; node name and device ID are redacted.](https://docs.aventail.co.uk/img/link/installation-2.0.0/setup-finish-redacted.png)
    

**Read the installation and registration steps**

### Choose an installation path

If you are not using the wizard, open **Register Device** from the Dashboard or **Devices** page.

| Path | Use it for | What connects the device |
| --- | --- | --- |
| **Desktop app** | Apple Silicon Mac with a graphical desktop | Sign in from Link and approve it in your browser |
| **Headless** | A supported Linux, macOS or Windows machine managed from a terminal | Install the service, then register with a one-time key |

### Desktop Mac

1.  Obtain the **Aventail Link 2.0.0 macOS ARM64 `.pkg`** for your Control environment. Use the production download above, or the download offered by your development Control environment.
2.  Open it and select **Continue → Install**. Wait for the successful installation screen and choose **Close**. No administrator prompt or licence step appeared in the captured installer.
3.  In **Aventail Link Setup → Connect**, select **Sign in with Aventail**. Check the browser account, organisation and approval code before approving the device.
4.  In **Models**, tick a model to start its download, or leave all models unticked to deploy from Control later. Wait for the download, then select **Continue**.
5.  In **Serving**, tick the installed model to serve it on port **8100**, then select **Continue**. If **Nothing downloaded yet** appears, use **Back** to inspect download progress.
6.  On **Finish**, check **All set** and the installed/serving counts, then select **Finish**. Confirm the device is **Online** in the same Control environment.

The package installs under your user Library and starts its service automatically. A move from 1.x requires a new registration and model deployments; it does not migrate the old installation. See the [illustrated installation walkthrough](https://docs.aventail.co.uk/docs/getting-started/quickstartguide#connect) or [macOS installation help](https://docs.aventail.co.uk/docs/link-app/install-macos#if-setup-stops).

**Read the headless installation steps**

Use **Aventail Link 2.x** for current terminal installations. It supports Linux x64 with systemd, macOS Apple Silicon and Windows x64 through PowerShell. Check [platforms and release channels](https://docs.aventail.co.uk/docs/introduction/versions-and-supported-models) first.

1.  In the intended Control account, open **Devices → Register Device → Headless** and choose the target operating system.
2.  Run the install command **on that device**. These examples download the production release:

**Linux / macOS**

```bash
curl -fsSL https://get.aventail.co.uk/install.sh | sh
```

**Windows PowerShell**

```powershell
irm https://get.aventail.co.uk/install.ps1 | iex
```

The installer verifies the release checksum, installs for your user and starts the background service. Without a key, the service waits for registration. If the installer changes PATH, open a new terminal or use the executable path it prints. See [file locations](https://docs.aventail.co.uk/docs/link-app/file-locations) and [Linux server startup](https://docs.aventail.co.uk/docs/link-app/install-linux#keep-the-service-running).

3.  Back in Control, set **Key valid for** and select **Generate registration key**. A registration key is single-use; the default validity is 24 hours.
4.  Copy the **whole registration command** from Control, including `LINK_API_BASE`, and run it on the target device. For production, its form is:

**Linux / macOS**

```bash
LINK_API_BASE='https://api.locai.co.uk/api/v1' AVENTAIL_REGISTRATION_KEY='YOUR_REG_KEY' aventail register
```

**Windows PowerShell**

```powershell
$env:LINK_API_BASE = 'https://api.locai.co.uk/api/v1'
$env:AVENTAIL_REGISTRATION_KEY = 'YOUR_REG_KEY'
try { aventail register } finally { Remove-Item Env:AVENTAIL_REGISTRATION_KEY }
```

Replace `YOUR_REG_KEY` with the generated key. Keep it out of screenshots, source control and shared logs. The variables keep keys out of process arguments; pasted commands can still remain in shell history. Development keys require the development API address and release channel from Control. Link saves the selected API address with its registration.

5.  Run `aventail status`, then confirm the device is **Online** in that same Control account. If the key expired or was already used, generate another and repeat registration; do not reinstall only to replace a key.

### Unattended installation

The wizard's combined command installs and registers in one step. Put the environment variables on the shell **after** the pipe:

```bash
curl -fsSL https://get.aventail.co.uk/install.sh | LINK_API_BASE='https://api.locai.co.uk/api/v1' AVENTAIL_REGISTRATION_KEY='YOUR_REG_KEY' sh
```

For PowerShell, run the keyed installer in its own scope and remove the key even if installation fails:

```powershell
$env:LINK_API_BASE = 'https://api.locai.co.uk/api/v1'
$env:AVENTAIL_REGISTRATION_KEY = 'YOUR_REG_KEY'
try { & ([scriptblock]::Create((irm https://get.aventail.co.uk/install.ps1))) }
finally { Remove-Item Env:AVENTAIL_REGISTRATION_KEY }
```

Fleet enrollment uses `AVENTAIL_FLEET_KEY` instead. Copy the fleet command from **Add devices**; see [fleet enrollment](https://docs.aventail.co.uk/docs/fleet/overview#create-a-key-and-enroll).

**Locai Link (Legacy Aventail) 1.x registration screenshots**

### Headless registration in Locai Link (Legacy Aventail) 1.3.2

Older headless registration capture; match commands to the package installed on the target device.

1.  **Headless device**
    
    Choose the target operating system, run its installer there, then generate and use a registration key.
    
    Locai Link (Legacy Aventail) 1.3.2 registration example. Match the installer and command to your version; this capture shows Windows PowerShell.
    
    [Screenshot: Register Device dialog — close-up from Device registration in Control.](https://docs.aventail.co.uk/img/guides/context/registration.png)
    
2.  **Confirm Online**
    
    Check the new record belongs to the intended account. Registration success alone does not establish connectivity.
    
    -   Register: Use the intended account
    -   Run Link: Keep its service running
    -   Check Devices: Confirm Online

These earlier captures show the old `locai` command. Follow the current Aventail commands above for a new installation. `get.locai.co.uk` now serves Aventail releases too; it no longer selects a 1.x installer.

### Verify the device is connected

Open **Devices**, identify the new device and confirm **Online**. Aventail names the device from its operating-system user and hostname unless you supply a name. A registration success message alone does not establish that the background service is online.

In the wizard, **Continue to deploy** stays disabled while **Waiting for your Mac to connect…** appears. Once your Mac is connected, select **Continue to deploy**. A device registered to another account will not complete this account's setup.

If the device stays **Pending** or becomes **Offline**, check that Link is running, retain the exact error and follow [Link troubleshooting](https://docs.aventail.co.uk/docs/link-app/troubleshooting).

### Device limit reached

If Control shows **Device limit reached**, ask the account owner to make capacity available or review the plan. Preserve existing devices you do not own.

**Recognise a device-limit message**

![Control showing Device limit reached for an account using all five slots](https://docs.aventail.co.uk/assets/images/device-limit-230cc6a61c750e48ef82aadd3aa5023c.png)

### Remove a device

To remove Link or release a device slot, see [Remove a device](https://docs.aventail.co.uk/docs/link-app/uninstall#remove-a-device).

## Deploy a model

Choose a compatible model and an **Online** device with room for both the model and its engine. Aventail setup can download and serve a model directly; do not deploy another copy if it is already installed.

### Deploy a model

Control deployment screens captured 28 September 2026.

1.  **Choose a model**
    
    Open Models → Globally Shared. Check its task, framework and size before choosing Deploy.
    
    [Screenshot: Shared model library — close-up from Control model library.](https://docs.aventail.co.uk/img/guides/context/models.png)
    
2.  **Choose the device**
    
    Select the online target device and confirm deployment. It needs capacity for the model and engine.
    
    [Screenshot: Deploy Model dialog for Gemma 4 (X-Small), with Target Device selection and Deploy.](https://docs.aventail.co.uk/img/control/onboarding/deploy-model.png)
    
3.  **Wait for completion**
    
    Wait for Model deployed successfully. Start serving only when deployment is complete.
    
    [Screenshot: Successful deployment with a serving port field and Serve Model button.](https://docs.aventail.co.uk/img/control/onboarding/deployment-complete.png)
    

**Read the deployment steps**

### Choose a model

In the wizard, select **Deploy model** for the recommended starter model. Our walkthrough used **Gemma 4 (X-Small)**, a **2.44 GB GGUF** download.

Outside the wizard, open **Models → Globally Shared**. Check the model's type, framework and download size, then select **Deploy → Target Device → Deploy Model**.

If you selected a model during Link setup, check whether it is already installed before deploying it again. Custom uploads and image/audio classification require different compatibility checks and inputs from this language-model walkthrough.

### Check progress

Keep Link running until **Model deployed successfully!** appears, or the **Deployments** tab in [Notifications](https://docs.aventail.co.uk/docs/getting-started/notifications-hub) shows **Deployed**. Download percentage and overall progress can differ.

### If deployment fails

-   Check the target device is still **Online** and has free disk space.
-   Record the model name and exact error message before retrying.
-   Check progress before starting another deployment. An accepted upload format does not guarantee the device can run the model.

## Serve a model

Serving makes the installed model available to Workspace and API clients. Aventail setup's **Serving** checkbox starts the selected model on port **8100**. Keep Link running while you use it.

### Make the model available

Serving starts an endpoint; the deployed model stays installed when stopped.

1.  **Start serving**
    
    After a deployment, keep the available port and select Serve Model. For an installed model, open Serving and turn on its switch.
    
    [Screenshot: Completed deployment dialog — close-up from Deployment in Control.](https://docs.aventail.co.uk/img/guides/context/deployment-complete.png)
    
2.  **Find the local endpoint**
    
    In Serving → API Usage, find the model endpoint. On this machine use 127.0.0.1 and the displayed port.
    
    [Screenshot: API Usage panel showing local endpoint and request information for a served model.](https://docs.aventail.co.uk/img/control/onboarding/local-api.png)
    
3.  **Stop when finished**
    
    Turn off the model’s switch under Serving and check stopped. This interrupts requests but keeps the model installed.
    
    -   Serving: Expand the intended device
    -   Model switch: Turn it off
    -   Status: Confirm stopped

**Read the serving steps**

### Start serving

1.  In Control, open **Serving** and expand your device.
2.  Turn on the model's switch.
3.  In **Start Serving**, enter an available port, such as **8100**, and confirm.
4.  Wait for **serving** and the endpoint to appear.

You can also use **Serve Model** with the displayed port from a completed deployment dialog. The first request can take longer while the inference engine loads the model. If it fails, check **Notifications** and [Link troubleshooting](https://docs.aventail.co.uk/docs/link-app/troubleshooting).

### Choose the endpoint

| Client location | API base URL |
| --- | --- |
| Same machine as Link | `http://127.0.0.1:8100/v1` |
| Another authorised machine | The Link machine's reachable address and serving port, followed by `/v1` |
| Docker container | An address reachable from inside the container; see [Open WebUI](https://docs.aventail.co.uk/docs/integration/openwebui) |

Replace `8100` with your actual port. `0.0.0.0` is a server bind address, not a client destination. A network address shown in Control does not establish that it is reachable or protected for remote use.

### Stop serving

Turn off the model's switch in **Serving** and confirm **stopped**. Stopping interrupts requests using that model, but it stays installed for next time. To free disk space, see [Removing models](https://docs.aventail.co.uk/docs/model_management/removing-models).

Next: [chat in Workspace](https://docs.aventail.co.uk/docs/workspace/getting-started) or [connect your software](https://docs.aventail.co.uk/docs/getting-started/run-first-interface).