---
title: Devices & machines
description: "Add a Linux server to Ysra from the desktop app, as a device or as a machine, start working on it, and remove it again."
---
Ysra can work on your servers in two ways: as a **device**, where Ysra is
installed and does the work itself, or as a **machine**, which Ysra reaches
over SSH through a gateway, one approved command at a time. Use this page to
pick one and set it up from the desktop app, start to finish; the reference
for each is in [Devices](../devices/overview.md) and
[Machines](../machines/overview.md).
| Word | Means |
|---|---|
| **Device** | A computer with Ysra installed and signed in |
| **Gateway** | A device that reaches other computers over SSH. Your own computer acts as a gateway when it reaches machines over your SSH |
| **Machine** | A computer you manage through a gateway. Older versions called machines “targets” |
## Device or machine?
Ask one question: **can Ysra be installed on the computer?**
- **Yes → make it a device.** Ysra is installed *on* the computer and does the
work itself, like a colleague logged in on it.
- **No → make it a machine.** Ysra reaches it over SSH or an admin tool,
through a gateway, and asks you before each command it sends. When you add
the machine from the desktop app, your own computer is the gateway.
| | Device | Machine |
|---|---|---|
| Ysra installed there | Yes, the CLI | No, nothing |
| Where the work happens | On the computer itself | The gateway sends commands over your SSH or tool |
| Coding, builds, tests, GPU and camera | Yes, fully | No. It works command by command, for operations work |
| Who connects | The device connects **out** to Ysra. No port is opened on it | The gateway connects to the machine |
| Approvals | Edits in its folder, after you switch it to Change | **Every** change command. Destructive ones on production need the name typed |
| Best for | Projects, development, builds, tests, machine learning and GPU work | Checking status and logs, careful configuration changes, step-by-step runbooks |
### Examples
| The computer | Pick | Why |
|---|---|---|
| A Linux VM with your web app’s code, where you want features or fixes | **Device** | Ysra edits and tests where the code runs |
| A GPU box for a model to benchmark or tune | **Device** | The work needs the computer’s own hardware |
| Your build server or CI runner | **Device** | Builds run where the tools are |
| A production database server where nothing may be installed | **Machine** | Ysra reads logs and status, and makes careful, approved changes over SSH |
| A VMware ESXi host | **Machine**, kind *ESXi host*, through `govc` | Nothing can be installed on ESXi |
| A switch or router | **Machine**, kind *Network gear* | It offers only SSH or a vendor’s command line |
| A server managed by a hosting company | **Machine** | Only their SSH access is available |
### Using both is normal
A common setup: the app server as a **device**, where Ysra develops, and the
database and load balancer as **machines**, which Ysra checks and adjusts
carefully. One conversation can use both, asking you at each step.
If your own computer runs Windows and the servers run Linux, the choice is the
same: devices for the servers Ysra should work on code on, where you’re allowed
to install; machines for the ones you look after, or where nothing may be
installed.
Either way, every change is approved by a person — one at a time, or ahead of
time with a [signed approval](../machines/approvals.md) — and you can remove
access at any time.
## Add a Linux server as a device
> Diagram: A device signs in with a code you approve, connects out, and does the work on its own folder.
### Install Ysra on the server
SSH in as the user who owns the project, then:
```bash
curl -fsSL https://ysra.ai/install.sh | sh -s -- --device
```
### Let Ysra run commands there
```bash
sudo apt install bubblewrap socat ripgrep
```
These let Ysra keep its commands contained to the folder you share. You can
skip this step; without them Ysra reads and edits files on the server but
doesn’t run commands.
### Ask to sign in
```bash
ysra login --device
```
The server shows a code such as `ABCD-EFGH`. It is valid for 10 minutes.
### Approve it in the desktop app
On your computer, open **Settings → Devices → Approve a device**.
1. Type the code and choose **Find it**.
2. Check the server’s name and system.
3. Choose **Approve**.
{ width="1242" height="962" }
/// caption
The app shows what is asking before you approve it.
///
### Share the project folder
Back on the server:
```bash
ysra serve --folder /opt/app --install-service
```
Replace `/opt/app` with your project’s folder. `--install-service` keeps the
folder available after you log out; Ysra shows the service file and asks before
installing it. Repeat `--folder` for each folder you want to share.
### Start working
In the desktop app, open **Settings → Devices**, choose **Folders on
*server name*…**, then **New thread** next to the folder.
{ width="1242" height="718" }
/// caption
The folders the server is sharing.
///
The thread shows **on *server name*** in its header: the work runs on the
server, and your computer only shows it.
### Allow changes when you’re ready
A new device starts in **Observe**: Ysra can look around and run checks, but
can’t edit anything. To let it make changes, switch the device to **Change** in
**Settings → Devices**. Each change still asks for your OK.
**To remove a device:** **Settings → Devices → Remove → Remove it**. It is
signed out at once.
| The app says | Do this |
|---|---|
| *edge-01 is offline. Run `ysra serve` there.* | Start `ysra serve` on the server, or check the service is running |
| *edge-01 isn’t sharing a folder. Run `ysra serve --folder …` there.* | Share a folder from it |
More: [Devices](../devices/overview.md) and
[Install on a server or edge device](../install/device.md).
## Add a server as a machine
Nothing is installed on the server. Ysra runs on your computer, which acts as
the gateway, and reaches the server through your own SSH, one approved command
at a time. It never asks for,
stores or types a password.
### Make sure SSH works on its own
Add the server to your SSH config, then check that you can log in **without
being asked for a password**.
=== "Windows"
OpenSSH is built into Windows 10 and 11. Edit
`C:\Users\\.ssh\config`:
```text
Host web-01
HostName 10.0.0.12
User deploy
IdentityFile ~/.ssh/id_ed25519
```
In PowerShell:
```powershell
ssh web-01
```
If it asks for a password, start the SSH agent and add your key:
```powershell
Get-Service ssh-agent | Set-Service -StartupType Automatic
Start-Service ssh-agent
ssh-add
```
=== "macOS and Linux"
Edit `~/.ssh/config`:
```text
Host web-01
HostName 10.0.0.12
User deploy
IdentityFile ~/.ssh/id_ed25519
```
```bash
ssh web-01
```
If it asks for a password, add your key to the agent with `ssh-add`.
### Add the machine
In the desktop app, open **Settings → Machines → Add a machine…**. From a
terminal, `ysra machines add` asks the same questions.
| Field | Example |
|---|---|
| **Name** | `web-01` |
| **Kind** | Linux server |
| **How I reach it** | SSH |
| **SSH host alias** | `web-01`, the `Host` name from your SSH config |
| **Production** | Tick it if this is a production machine |
### Confirm the server’s host key
Choose **Check its host key**. Ysra shows the server’s fingerprint. Compare it
with the server itself:
```bash
ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
```
If it matches, tick **Yes, this is my server** and add the machine. The key is
then pinned: if a different computer ever answers at that address, Ysra refuses
to connect.
{ width="1242" height="1686" }
/// caption
Confirm the host key before the machine is added.
///
### Ask Ysra to look
In any thread, name the machine:
```text
check why nginx keeps restarting on web-01
```
The first time, a card asks **Look around web-01?** Choose **Allow for this
session**. Reading changes nothing on the server.
### Allow changes when you’re ready
A new machine starts in **Observe**, which is read-only. To allow changes, use
the **Observe / Change** switch in **Settings → Machines**, or:
```bash
ysra machines mode web-01 change
```
Each change then shows a card with the exact command, why, what to expect and
how to undo it. On a **production** machine, anything that can’t be undone also
needs you to type the machine’s name.
**To remove a machine:** **Settings → Machines → Remove**, or
`ysra machines rm web-01`. Its log stays on your computer.
More: [Machines](../machines/overview.md).
## Once it’s connected
### Cards for a machine
| Card | When | Answers |
|---|---|---|
| **Look around edge-01?** | The first read in a thread | Allow for this session · Not now |
| **Run this on edge-01?** | Every change | Run it · Skip |
| **This can’t be undone on edge-01** | A destructive command | Run it · Skip |
{ width="1440" height="891" }
/// caption
The exact command, why, what to expect, and how to undo it.
///
{ width="1440" height="891" }
/// caption
On production, **Run it** stays off until the name is typed exactly.
///
Only you can answer these cards; auto mode never does. A card left unanswered
for 15 minutes counts as declined, and quitting the app declines every waiting
one.
### What ran on a machine
**Settings → Machines → Log** lists every command: when, what ran, whether it
was a read, a change or destructive, and whether you approved it.
{ width="1242" height="870" }
/// caption
A machine, its mode, and its log.
///
### Camera and GPU on a device
Ysra’s commands can’t see a device’s hardware until you allow it, once per
thread.
{ width="1440" height="891" }
/// caption
The card names the impact before you allow it.
///
### Runbooks
Give Ysra a written procedure and a machine. The plan appears as one card with
every step, its check and its recovery step. **Start** runs the read-only
checks first, then asks before each step and stops at the first check that
fails.
{ width="1440" height="891" }
/// caption
The whole plan, before anything runs.
///
More: [Runbooks](../machines/runbooks.md).
## Good to know
| Point | Detail |
|---|---|
| Your credentials stay yours | A device signs in with a code you approve. A machine is reached with your own SSH keys |
| What Ysra’s servers know about a machine | Only its name, kind and mode, never its address, user or SSH details |
| Switching a device or machine to **Change** | Always your action. Ysra can’t do it |
## Related
- [Approvals and auto mode](approvals.md): the cards for devices and machines.
- [The Machines panel](machines-panel.md): work on many machines from one thread.
- [Install on a server or edge device](../install/device.md): the device install in full.
- [Runbooks](../machines/runbooks.md): step-by-step procedures on machines.