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

# Node manifest reference for orun

> All fields in the Node manifest YAML: SSH connection details, Git repository URL, branch, poll interval, data directory, and local build code directory.

A Node manifest is a YAML file stored at `nodes/<name>.yaml` in your manifest repository. It tells orun how to reach a server over SSH during bootstrapping and what Git repository the node should watch for configuration changes after bootstrap is complete. Once provisioned, the node runs fully autonomously — it polls the configured branch on the `origin` remote of `gitRepo` every `pollInterval` and applies any changes it finds without requiring further SSH access.

## Example

```yaml theme={null}
apiVersion: run.orcra.dev/v0alpha
kind: Node
metadata:
  name: web-01
spec:
  host: 203.0.113.10
  user: root
  sshKeyPath: ~/.ssh/id_ed25519
  gitRepo: git@github.com:org/manifests.git
  gitBranch: main
  pollInterval: 5s
  dataDir: /opt/orun/
  codeDir: /var/lib/orun/code
```

<Note>
  Run `orun bootstrap` from the root of your manifest repository to have orun prompt you for these values and write the file automatically. You can also pass an existing manifest directly: `orun bootstrap nodes/web-01.yaml`.
</Note>

## Fields

<ParamField path="host" type="string" required>
  SSH host or IP address of the target server. Used during `orun bootstrap` to connect over SSH and during ongoing operation for identification purposes.
</ParamField>

<ParamField path="user" type="string" default="root">
  SSH user for the bootstrap connection. orun uses this account to install the binary and configure the systemd service on the node.
</ParamField>

<ParamField path="sshKeyPath" type="string" default="~/.ssh/id_ed25519">
  Path to the SSH private key on the **control plane** (the machine running `orun bootstrap`). This key is used only during bootstrap; the node itself communicates with Git, not back to your control plane.
</ParamField>

<ParamField path="gitRepo" type="string" required>
  URL of the manifest Git repository. The node clones this repository using the `origin` remote and polls it on the configured interval to derive its desired state.
</ParamField>

<ParamField path="gitBranch" type="string" default="main">
  Branch the node tracks for manifest changes. Use different branches to model environments — for example, `staging` and `production` pointing at the same repository but different branches.
</ParamField>

<ParamField path="pollInterval" type="string" default="5s">
  How often the node polls the remote Git repository for new commits. Accepts Go duration strings such as `5s`, `30s`, or `1m`. Shorter intervals reduce reconciliation lag; longer intervals reduce network traffic.
</ParamField>

<ParamField path="dataDir" type="string" default="/opt/orun/">
  Directory on the **node** where orun stores its local state, including the cloned manifest repository and runtime metadata.
</ParamField>

<ParamField path="codeDir" type="string" default="/var/lib/orun/code">
  Directory on the **node** where application source code is expected. orun scans subdirectories of this path for build candidates when a Deployment uses `spec.build`. If this path does not exist at runtime, no builds are attempted.
</ParamField>

## Deploy key access

The node fetches manifests using the `origin` remote of `gitRepo`. If your repository is private, ensure the node has read access — typically by adding an SSH deploy key to the repository and placing the corresponding private key on the node. The control-plane `sshKeyPath` is not copied to the node during bootstrap.

<Warning>
  If the node cannot authenticate to `gitRepo`, it will fail to fetch manifest updates silently after bootstrap completes. Verify access by running `git fetch` from `dataDir` on the node.
</Warning>