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

# Workspace folder

> Hiro Server instance (workspace) artifacts

A Hiro workspace is a self-contained server instance directory. It contains server configuration, identity material, provider metadata, character content, system databases, user conversation data, runtime process files, logs, and generated media.

The global workspace registry lives outside the workspace folder. See [Global registry](#global-registry).

## Workspace root

### Folders

| Path          | Purpose                                                                                 |
| ------------- | --------------------------------------------------------------------------------------- |
| `data/`       | User content database, message media, and channel thumbnails.                           |
| `characters/` | File-backed character content, one folder per character id.                             |
| `logs/`       | Workspace log files. The default location can be overridden by `config.json` `log_dir`. |
| `channels/`   | Runtime PID files for spawned channel plugin subprocesses.                              |
| `tts_debug/`  | Generated MP3 files for TTS reply debugging.                                            |

### Files

| Path                   | Type               | Purpose                                                                                                                                                        |
| ---------------------- | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workspace.db`         | SQLite database    | System configuration database. Stores characters index rows, paired devices, channel plugin configuration, and LangGraph agent checkpoints.                    |
| `config.json`          | JSON config        | Boot-time server configuration: device identity, gateway URL, HTTP/plugin/admin ports, pairing settings, logging, metrics, and autostart method.               |
| `preferences.json`     | JSON config        | Workspace-level model, media, and memory preferences. Top-level sections are `version`, `llm`, `media`, and `memory`.                                          |
| `providers.json`       | JSON metadata      | Non-secret provider configuration metadata. Top-level sections are `version` and `providers`. Provider secrets are stored in the OS keyring, not in this file. |
| `master_key.pem`       | PEM key file       | Workspace Ed25519 private key used for desktop/server identity and device trust flows.                                                                         |
| `state.json`           | JSON runtime state | Last known gateway connection state for the workspace. Top-level data covers connection status, last connection time, and gateway URL.                         |
| `pairing_session.json` | JSON runtime state | Short-lived active pairing code session. Removed or ignored after expiry. Approved devices live in `workspace.db`.                                             |
| `hiro.pid`             | PID file           | Active background Hiro server process id.                                                                                                                      |
| `stderr.log`           | Plain log          | Detached server startup/crash stderr output.                                                                                                                   |

## `workspace.db`

`workspace.db` stores system configuration and agent runtime state.

| Table             | Purpose                                                                                                            |
| ----------------- | ------------------------------------------------------------------------------------------------------------------ |
| `characters`      | Relational index for file-backed characters. Character content lives under `characters/<id>/`.                     |
| `devices`         | Approved device records created by pairing and used for device trust/name lookup.                                  |
| `channel_plugins` | Channel plugin registration, enabled state, launch command, workspace directory, and plugin configuration payload. |
| `checkpoints`     | LangGraph checkpoint state for agent conversations. Created and managed by `AsyncSqliteSaver`.                     |
| `writes`          | LangGraph checkpoint writes for agent conversations. Created and managed by `AsyncSqliteSaver`.                    |

## `data/`

| Path                                              | Type            | Purpose                                                                                                          |
| ------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------- |
| `data/data.db`                                    | SQLite database | User content database for users, conversation channels, and messages.                                            |
| `data/media/<channel_id>/<message_pk>.<ext>`      | Media file      | Binary message attachments saved from inbound or outbound message content. Paths are stored relative to `data/`. |
| `data/channel_photos/<channel_id>/photo_512.webp` | Image file      | 512x512 WebP thumbnail for a conversation channel.                                                               |

## `data/data.db`

`data.db` stores user-facing conversation data.

| Table      | Purpose                                                                                                     |
| ---------- | ----------------------------------------------------------------------------------------------------------- |
| `users`    | Workspace-local users. New workspaces seed the default owner user.                                          |
| `channels` | Conversation channels linked to a user and character. New workspaces seed the default direct channel.       |
| `messages` | Persisted message transcript rows, including text content, media references, sender identity, and metadata. |

## `characters/`

Each character has one folder under `characters/<id>/`.

| Path                             | Type             | Purpose                                                                                                                                               |
| -------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `characters/<id>/character.json` | JSON content     | Structured character metadata. Top-level content covers identity, description, preferred chat/voice models, TTS settings, emotion toggle, and extras. |
| `characters/<id>/prompt.md`      | Markdown content | Character system prompt text used by the agent runtime.                                                                                               |
| `characters/<id>/backstory.md`   | Markdown content | Character backstory text.                                                                                                                             |
| `characters/<id>/photo.*`        | Image file       | Optional uploaded character photo. Supported workspace photo extensions include PNG, JPG/JPEG, WebP, and GIF.                                         |

The default character id is `hiro`. If the workspace has no uploaded photo for a character, the HTTP profile image endpoint can fall back to the packaged default character image.

## `logs/`

| Path                      | Type    | Purpose                                     |
| ------------------------- | ------- | ------------------------------------------- |
| `logs/server.log`         | CSV log | Server runtime events from non-CLI modules. |
| `logs/cli.log`            | CSV log | CLI command events.                         |
| `logs/channel-<name>.log` | CSV log | Channel plugin events for a named channel.  |

The admin log viewer and log tools read these files. Gateway logs are stored under the gateway instance folder, not inside the Hiro workspace.

## `channels/`

| Path                          | Type     | Purpose                                                     |
| ----------------------------- | -------- | ----------------------------------------------------------- |
| `channels/<channel_name>.pid` | PID file | Runtime process id for a spawned channel plugin subprocess. |

Channel plugin configuration does not live in this directory. It lives in the `channel_plugins` table of `workspace.db`.

## `tts_debug/`

| Path                         | Type       | Purpose                                                          |
| ---------------------------- | ---------- | ---------------------------------------------------------------- |
| `tts_debug/<message_id>.mp3` | Audio file | Debug copy of synthesized voice reply audio keyed by message id. |

## Global registry

The registry is not inside an individual workspace folder. It lives in the platform app data directory and points to all configured workspaces.

| Platform | Registry location                                  |
| -------- | -------------------------------------------------- |
| Windows  | `%LOCALAPPDATA%\hiro\registry.json`                |
| macOS    | `~/Library/Application Support/hiro/registry.json` |
| Linux    | `~/.local/share/hiro/registry.json`                |

`registry.json` tracks the default workspace, port range start, workspace ids, display names, paths, and port slots.