---
title: Machines
description: "Use the Machines page in the desktop app: read each machine's state, filter and organise machines, add or remove one, and pair a gateway with a workspace."
new_in: "2.2"
---

The **Machines** page lists every machine in the current workspace: the
ones its [gateways](../gateways/overview.md) reach, and any you listed by
hand. Use it to see which machines are reachable and healthy, and to label
them. To work on machines from a thread, see
[The Machines panel](machines-panel.md); to add one machine this computer
reaches over SSH, see [Devices & machines](devices-machines.md).

Open it from **Machines** on the rail; its number key follows the rail’s
order (see [Shortcuts](shortcuts.md#sections-by-number)).

## The rule

The page shows names only. Addresses and keys stay on the gateway that
reaches each machine.

## Get machines onto the page

Machines come from a gateway. Pair one with the workspace:

1. Open **Settings → Devices** and find the gateway.
2. Under **Machines *gateway* reaches**, choose **Use its machines in
   *workspace***.

The gateway keeps the list current from then on. It has to be online to
pair; if it isn’t, start `ysra serve` on it.

With no gateway yet, the page says *No machines yet. Run ysra machines import
machines.csv on your gateway, or add one here.* Setting up a gateway and
importing machines: [Machines and gateways](../gateways/overview.md).

## What each card shows

| On the card | Meaning |
|---|---|
| **reachable now** | Its gateway can reach it at this moment |
| **its gateway can’t reach it** | The gateway is online but the machine doesn’t answer |
| **gateway offline** | The gateway isn’t connected. The last reading is still shown |
| **no gateway yet** | Added by hand; nothing reaches it yet |
| Labels | Its environment, groups and `#tags`, then **through *gateway*** or **added by hand** |
| **Last checked …** | When Ysra last looked at it. **Not checked yet** until it has |

The list refreshes by itself every 30 seconds; **Refresh** reloads it now.
Click a card to open it.

## Filter the list

| Filter | Shows |
|---|---|
| **All groups**, then one button per group | Machines in that group, with a count. With **All groups**, machines are listed under their group, the rest under **Not in a group** |
| **All** | Every machine |
| **Needs you** | Machines whose last check found something to look at, or that couldn’t be reached, with a count |
| **Healthy** | Machines whose last check was fine |
| **Not checked yet** | Machines Ysra hasn’t looked at |

## Organise a machine

Open a machine’s card, edit, and choose **Save**.

| Field | Notes |
|---|---|
| **Groups** | Separate several with commas, for example `site-a, cameras` |
| **Tags** | For example `rack-2` |
| **Environment** | Production, Staging, Lab, Dev, or none |
| **Kind** | Editable for a machine added by hand. For a gateway’s machine it reads *from its gateway*: change it there |

Whether a machine is look-only or can be changed, and whether it is
production, are held by its gateway. Change those on the gateway, not here.

## Add a machine by hand

Choose **Add machine** to list one before its gateway is set up. Give it a
**Name**, **Kind**, **Groups**, **Tags** and **Environment**, tick
**Production machine** if it is one, and choose **Add it**.

A machine added by hand is only a label: Ysra can’t look at it or change it.
When a gateway reports a machine with the same name, the two are linked and
the machine becomes reachable through that gateway.

## Remove a machine

Open the card and choose **Remove**, then **Remove it**.

| Machine | What happens |
|---|---|
| Added by hand | Removed from the workspace |
| A gateway’s | Comes back while its gateway still reaches it. To remove it for good, run `ysra machines rm <name>` on the gateway: that removes the machine, its pinned key and its address there |

## Related

- [The Machines panel](machines-panel.md): work on machines from a thread.
- [Machines and gateways](../gateways/overview.md): set up a gateway and import machines.
- [Devices & machines](devices-machines.md): add a single device or machine.