---
title: "targets.json"
description: "The file your targets are kept in: where it lives, what each field means, and how to edit it safely."
---

Your targets are kept in one file:

```text
~/.ysra/targets.json
```

**It lives only on your computer.** It's readable and writable by you alone
(mode `0600`, inside `~/.ysra`, which is `0700`). It's never uploaded. Ysra's
servers learn each target's `name`, `kind`, `via`, `cli`, `mode` and
`production`, so I know what I can ask for. They never learn `ssh_alias`, a
host name, an address, a user or a port.

!!! tip

    Prefer the commands (`ysra target …`) or **Settings → Targets**. They check
    what you enter and pin the host key. Edit the file by hand only for the cases
    listed under [Editing it safely](#editing-it-safely).

## 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
  }
]
```

The file is a list. Each entry is one target.

## Fields

| Field | Required | Values | Meaning |
|---|---|---|---|
| `name` | Yes | Lowercase letters, digits, `.`, `_`, `-`. Starts with a letter or digit. Up to 63 characters | What you and I call the target. Also the name you type to confirm a destructive step on production |
| `kind` | Yes | `linux`, `esxi`, `network`, `oss`, `other` | What sort of machine it is |
| `via` | Yes | `ssh` or `cli` | How I reach it |
| `ssh_alias` | When `via` is `ssh` | A `Host` from your `~/.ssh/config` | The host, user, port and key all come from your SSH config. None of that is copied here |
| `cli` | When `via` is `cli` | One tool name, for example `govc`, `kubectl` | The command-line tool I run on your computer with your sign-in. Not a shell, `sudo`, `ssh` or a scripting language |
| `mode` | Yes | `observe` or `change` | `observe`: I only read. `change`: I may run changes, each after your OK |
| `production` | Yes | `true` or `false` | `true`: destructive commands need the target's name typed |
| `host_key_fingerprint` | SSH targets | `SHA256:…` | The fingerprint you confirmed when adding the target. Shown in lists so you can recognise it. For display |

## Editing it safely

| Change | By hand? | Better |
|---|---|---|
| `mode` | Fine | `ysra target mode <name> observe\|change` |
| `production` | Fine | `ysra target production <name> on\|off` |
| `kind` | Fine | — |
| Add an SSH target | **No** | `ysra target add`. Only adding it properly fetches the host key, shows you the fingerprint and pins it. An SSH target without a pinned key is refused |
| Change `ssh_alias` | **No** | Remove the target and add it again, so the new host's key is checked |
| Rename a target | **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 |

If you do edit by hand:

1. Close Ysra first, so it doesn't write over your edit.
2. Keep it valid JSON. If the file can't be read, I treat it as having no
   targets and say so. Nothing is deleted.
3. Keep it private: `chmod 600 ~/.ysra/targets.json`.
4. Run `ysra target list` to confirm it reads the way you meant.

Don't put passwords, keys or tokens in this file. There's no field for them,
and I never use one.

## Related files

| Path | What |
|---|---|
| `~/.ysra/targets/known_hosts` | The pinned host keys. Managed for you; don't edit |
| `~/.ysra/targets/<name>/log.jsonl` | What ran on that target and who approved it. Kept when the target is removed |

## Moving to another computer

Targets don't sync, by design. On the new computer, add each one again with
`ysra target add` and confirm its host key there.