Workspace folder

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.

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.

Concepts

Misc

Protocol

Workspace root

Folders

Files

`workspace.db`

`data/`

`data/data.db`

`characters/`

`logs/`

`channels/`

`tts_debug/`

Global registry

​Workspace root

​Folders

​Files

​workspace.db

​data/

​data/data.db

​characters/

​logs/

​channels/

​tts_debug/

​Global registry

Workspace root

Folders

Files

`workspace.db`

`data/`

`data/data.db`

`characters/`

`logs/`

`channels/`

`tts_debug/`

Global registry