> ## Documentation Index
> Fetch the complete documentation index at: https://docs.2501.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Host

> MDX frontmatter reference for host resources

**Subdirectory:** `hosts/` · **Body:** host knowledge (free-form text, optional)

The MDX body becomes the host's **knowledge** — free-form notes the agent reads before working on this host. Keep it operator-facing: installed tools, quirks, where credentials live, exact software versions.

## Frontmatter

| Field                       | Type             | Required | Default                        | Description                                                                                                                  |
| --------------------------- | ---------------- | -------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `org`                       | string           | **Yes**  | —                              | Organization name. Hosts are always org-scoped — every host belongs to an organization.                                      |
| `name`                      | string           | **Yes**  | —                              | Primary identifier. Typically the machine's hostname or a descriptive name.                                                  |
| `public_ip`                 | string \| null   | No       | `null`                         | Externally accessible IP. At least one of `public_ip` or `private_ip` is required at create time.                            |
| `private_ip`                | string \| null   | No       | `null`                         | Internal IP.                                                                                                                 |
| `additional_names`          | string\[]        | No       | `[]`                           | Free-form aliases for recognition and search — **not** structured tags.                                                      |
| `target_type`               | `ssh` \| `winrm` | No       | `ssh`                          | Connection protocol.                                                                                                         |
| `target_port`               | integer \| null  | No       | `null` (defaults to 22 / 5985) | Override only for non-standard ports.                                                                                        |
| `skip_tls_verify`           | boolean          | No       | `false`                        | Accept self-signed certs on WinRM-over-HTTPS targets.                                                                        |
| `tags`                      | string\[]        | No       | `[]`                           | [Vocab-validated tags](/0.8/configure/operational-rules#tag-axes): `os:*`, `shell:*`, `type:*`, `tech:*`, plus open `app:*`. |
| `is_jump_host`              | boolean          | No       | `false`                        | Marks this host as an SSH bastion relay — set `target_type: ssh`, since bastions are reached over SSH.                       |
| `jump_host`                 | string           | No       | —                              | Reference an existing host by its `name` to route this host's SSH connections through that bastion.                          |
| `jump_host_credential`      | string           | No       | —                              | Reference a [Credential](/0.8/configure/resources/credentials) by its `name` for the bastion's password or PEM private key.  |
| `jump_host_user_credential` | string           | No       | —                              | Reference a [Credential](/0.8/configure/resources/credentials) by its `name` for the bastion's SSH username.                 |
| `eligible_subnets`          | string\[]        | No       | `[]`                           | IPv4 CIDRs whose hosts are reasonable to route through this bastion (UX hint only — not enforced by the executor).           |

Jump hosts are applied before the hosts that reference them during `resources sync`, so forward references within the same sync are safe.

## Fields NOT supported

These come from later forms or other resources and are not yet declarable in MDX:

* `knowledge` field — comes from the MDX **body**, not frontmatter
* `description` — set in the UI for now
* `id`, `tenant_id`, `org_id`, `created_at`, `updated_at` — system-set

Any extra key in frontmatter fails strict validation.

## Example

```mdx hosts/web-01.mdx theme={null}
---
org: platform-team
name: web-01
public_ip: 203.0.113.10
private_ip: 10.0.0.10
target_type: ssh
target_port: 22
additional_names:
  - web-front-01
tags:
  - os:linux
  - os:ubuntu
  - shell:posix
  - type:web
  - tech:nginx
---
Nginx serves the public site; vhosts live in /etc/nginx/sites-enabled.
Deploys land in /var/www/releases with a `current` symlink.
The PostgreSQL client is installed but `psql` should be invoked with
`--no-psqlrc` because the system one has a hard-coded pager.
```

## Gotchas

* **Tags are vocab-validated.** Free-text tags are rejected. See the [tag vocabulary](/0.8/configure/operational-rules#tag-axes) for the closed list.
* **`additional_names` are not the structured tags.** They're free-form aliases for search. Real tags go in `tags`.
* **Re-syncing the body replaces host knowledge wholesale.** Editing the body in MDX and re-syncing overwrites what's in Command Center.
* **At least one IP is required.** Either `public_ip` or `private_ip` must resolve to a non-null value before the host can be created.