---
title: "Machine list reference"
description: "Look up every field in a gateway's machine list, ~/.ysra/targets.json, and which edits are safe to make by hand."
---

The **machine list** is the file `~/.ysra/targets.json` on a gateway, with
one entry per [machine](overview.md) it reaches. Read it when you need to
know what a field means or whether a hand edit is safe; for adding machines,
use `ysra machines add`, `ysra machines import` or **Settings → Machines**,
which check what you enter and pin the host key. The file kept its older
name: machines used to be called “targets”.

## Where it lives

| Property | Value |
|---|---|
| Path | `~/.ysra/targets.json`, on the gateway only |
| Permissions | `0600`, inside `~/.ysra` (`0700`) |
| Uploaded | Never |
| Ysra’s servers see | `name`, `kind`, `via`, `cli`, `mode`, `production`, `groups`, `tags`, `environment` |
| Never sent | `ssh_alias`, host name, address, user, port, keys |
| Synced to another computer | No, by design: add each machine again there and confirm its host key |

## Example

```json
[
  {
    "name": "edge-01",
    "kind": "linux",
    "via": "ssh",
    "ssh_alias": "edge-01",
    "mode": "observe",
    "production": false,
    "host_key_fingerprint": "SHA256:pV3n0cT7q…k9Q"
  },
  {
    "name": "lab-vcenter",
    "kind": "esxi",
    "via": "cli",
    "cli": "govc",
    "mode": "change",
    "production": true
  }
]
```

## Fields

| Field | Required | Values | What it does |
|---|---|---|---|
| `name` | Yes | Lowercase letters, digits, `.`, `_`, `-`; starts with a letter or digit; up to 63 characters | What you and Ysra call the machine; also the name typed to confirm a destructive step on production |
| `kind` | Yes | `linux`, `jetson`, `esxi`, `network`, `oss`, `other` | What sort of machine it is (`jetson` is set by `ysra machines import`) |
| `via` | Yes | `ssh` or `cli` | How Ysra reaches it |
| `ssh_alias` | When `via` is `ssh` | A `Host` from your `~/.ssh/config` | Host, user, port and key come from your SSH config; none is copied here |
| `managed_ssh` | No | `true` | Set by `ysra machines import`: the host lives in Ysra’s own `~/.ysra/targets/ssh_config`, not yours |
| `cli` | When `via` is `cli` | One tool name, such as `govc` or `kubectl` | The tool Ysra runs on the gateway with your sign-in. Not a shell, `sudo`, `ssh` or a scripting language |
| `mode` | Yes | `observe` or `change` | `observe`: Ysra only reads. `change`: changes, each after your OK |
| `production` | Yes | `true` or `false` | `true`: destructive commands need the machine’s name typed |
| `reads` | No | `ask` (default) or `allowed` | `allowed`: Ysra may look without asking; see [Let an unattended gateway look](../gateways/overview.md#let-an-unattended-gateway-look) |
| `groups`, `tags` | No | Lowercase words such as `site-a`, up to 20 each | Organise the inventory |
| `environment` | No | `prod`, `staging`, `lab`, `dev` | Shown in the inventory |
| `host_key_fingerprint` | SSH machines | `SHA256:…` | The fingerprint you confirmed, shown in lists; for display only |

## Editing it safely { #editing-it-safely }

| Change | By hand? | Better |
|---|---|---|
| `mode` | Fine | `ysra machines mode <name> observe|change` |
| `production` | Fine | `ysra machines production <name> on|off` |
| `reads` | Fine | `ysra machines reads <name> allowed|ask` |
| `kind`, `groups`, `tags`, `environment` | Fine | Import the CSV again |
| Add an SSH machine | **No** | `ysra machines add`: only that fetches, shows and pins the host key. An SSH machine without a pinned key is refused |
| Change `ssh_alias` | **No** | Remove the machine and add it again, so the new host’s key is checked |
| Rename a machine | **No** | Remove and add again; the pinned key and the log are kept under the name |
| `host_key_fingerprint` | **No** | Changing the text doesn’t change which key is pinned |

Before a hand edit:

1. Close Ysra, so it doesn’t write over your edit.
2. Keep it valid JSON. If the file can’t be read, Ysra treats it as having no
   machines and says so; nothing is deleted.
3. Keep it private: `chmod 600 ~/.ysra/targets.json`.
4. Run `ysra machines list` to confirm it reads the way you meant.

There is no field for passwords, keys or tokens, and Ysra never uses one.

## Related files

| Path | What |
|---|---|
| `~/.ysra/targets/known_hosts` | The pinned host keys. Managed for you; don’t edit |
| `~/.ysra/targets/ssh_config` | Addresses from `ysra machines import`. Your own `~/.ssh/config` is never touched |
| `~/.ysra/targets/<name>/log.jsonl` | What ran on that machine and who approved it. Kept when the machine is removed |

## Related

- [How machines work](overview.md) — modes, approvals and the log.
- [Machines and gateways](../gateways/overview.md) — importing many machines from a CSV.