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