---
title: "Files and directories"
description: "Where servers, nodes and operators keep their state."
canonical_url: "https://docs.oz0.ai/reference/files"
---
# Files and directories

> Where servers, nodes and operators keep their state.

For: Operators locating configuration and state.

Locate persistent state by its owner: server, operator or node. Paths below use the default data directories.

## Server

<table>
<thead>
  <tr>
    <th>
      Path
    </th>
    
    <th>
      What
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ~/.local/share/orchestrator-zero
      </code>
    </td>
    
    <td>
      The default data directory (<code>
        --data-dir
      </code>
      
      )
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        &lt;data-dir>/master.key
      </code>
    </td>
    
    <td>
      The master key, unless <code>
        --master-key-file
      </code>
      
       points elsewhere: plain base64, or a document wrapped by a <a href="https://docs.oz0.ai/admin/key-commands">
        key command
      </a>
      
       (<code>
        master.key.plain
      </code>
      
      , <code>
        .prev
      </code>
      
       and <code>
        .wrapped
      </code>
      
       are what the wrap and unwrap-to-file commands keep next to it). Back it up.
    </td>
  </tr>
</tbody>
</table>

In dev mode with `--data-dir`, the directory also holds `oz0.db` (the management database), `temporal.db` (the embedded Temporal's), `operator/` (the operator's credentials and `context.json`), `join-token` (a reusable token for dev nodes) and `admin-password`. Without `--data-dir`, dev mode uses a temporary directory removed at exit. `server backup --dev` copies both databases while the server runs; see [backups](https://docs.oz0.ai/fleet/backups#back-up).

## Operator

`server init` writes the first operator's credentials to `--operator-dir`, by default `~/.config/orchestrator-zero/<cluster>/`. `server operator issue` writes new ones the same way, and `operator renew` replaces the certificate and key at the same paths, once it has checked them (a renewal stopped halfway leaves `operator.key.next` or `operator.crt.next` beside them, and the next command finishes it; `operator.key.lock` is the lock a command holds while it writes or moves them, so two commands that run at once never act on a pair the other is still writing):

<table>
<thead>
  <tr>
    <th>
      File
    </th>
    
    <th>
      What
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        context.json
      </code>
    </td>
    
    <td>
      The cluster's name, the edge and management addresses, the namespace, and the paths below
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        ca.crt
      </code>
    </td>
    
    <td>
      The cluster's CA certificate
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        operator.crt
      </code>
      
      , <code>
        operator.key
      </code>
    </td>
    
    <td>
      The operator's certificate and private key. Keep them private.
    </td>
  </tr>
</tbody>
</table>

Point the CLI at it with `export OZ0_CONTEXT=.../context.json` or `--context`. Without either, the CLI looks for `~/.config/orchestrator-zero/context.json`.

## Node

<table>
<thead>
  <tr>
    <th>
      Path
    </th>
    
    <th>
      What
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      <code>
        ~/.local/share/orchestrator-zero-node
      </code>
    </td>
    
    <td>
      The default data directory (<code>
        --data-dir
      </code>
      
      ): the node's identity and key, uv, Python, Node.js, runtimes and state
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        &lt;data-dir>/node.json
      </code>
    </td>
    
    <td>
      The node's state, including the list of edges it can fail over to
    </td>
  </tr>
  
  <tr>
    <td>
      <code>
        &lt;data-dir>/plugins/&lt;name>/&lt;commit>/
      </code>
    </td>
    
    <td>
      Each installed plugin, with its environments
    </td>
  </tr>
</tbody>
</table>

Nothing on a node needs a backup: its plugins come from the edge, and a lost node can join again.

## Temporary session files

Runtimes record the temporary folders they create so a later start can clean up after a crash. Older runtimes that created no record can leave folders under `oz0-sessions`, and `oz0-t-*` or `oz0-files-*` folders, containing job data. Remove those abandoned folders manually only while no session runs on the node.

A remote session's folder is kept across segments because a later segment may resume it. Cleanup removes a folder unused for a week at runtime startup or when the next remote session starts. A continuously running node with no new remote session can keep it longer.


## Sitemap

See the full [sitemap](https://docs.oz0.ai/sitemap.md) for all pages.
