Each agent has its own isolated workspace on the filesystem. This is where the agent reads and writes files. Workspaces persist across conversations, so files created in one session are available in future sessions.

How storage is organized

Per-user state lives under a single root, data/users/{user_handle}/. Inside that root, Frona keeps separate subdirectories for each subsystem:

Path	Contents
data/users/{user_handle}/files/	Files you uploaded in chat
data/users/{user_handle}/agents/{agent_handle}/	One agent's workspace. Agents write here using CLI, Python, or Node.js tools, and expose files to you with produce_file.
data/users/{user_handle}/mcps/{mcp_handle}/	One MCP server's workspace
data/users/{user_handle}/channels/{channel_handle}/	One channel adapter's data (Signal/WhatsApp sessions, etc.)
data/users/{user_handle}/vault/, .../tokens/	Encrypted credentials and ephemeral tokens

Browser automation profiles are kept on the browserless container's own volume (browser.profiles_path, default /profiles), not under data/users/.

user_handle, agent_handle, mcp_handle, and channel_handle are all handles: 2–32 lowercase ASCII characters that start with a letter and contain only a-z, 0-9, -, or _. They're frozen at creation time, used everywhere a stable human-readable ID is needed (paths, URLs, policy entity IDs, tool IDs).

Agents can read across these areas using virtual paths, if they have permission:

• user://<user_handle>/report.pdf to read a file you uploaded
• agent://<user_handle>/<agent_handle>/output.csv to read a file another agent created

Uploading files

When you upload a file in the chat (drag and drop or the attachment button), it's stored in your user file area. You grant the agent permission to read it, and the agent can then access it during the conversation.

How agents create files

Agents create files in their own workspace using code execution tools (shell, Python, Node.js). When an agent wants to share a file with you, it uses the produce_file tool, which makes the file available as a downloadable attachment in the chat.

Browsing files

Use the workspace UI to browse files in an agent's workspace. You can:

• View the file list and directory structure
• Upload files
• Download files the agent created

Workspace layers

Agent workspaces have two layers:

1. Primary layer (read/write). The agent's own directory where it stores files.
2. Shared layer (read-only). Default files that ship with built-in agents, like prompt templates.

When an agent reads a file, it checks the primary layer first. If the file isn't there, it falls back to the shared layer. Writes always go to the primary layer. This lets agents customize defaults without modifying the originals.

Special files

Some files in the workspace have special meaning:

File	Purpose
AGENT.md	Custom agent instructions/prompt
HEARTBEAT.md	Checklist for heartbeat wake-ups

Next steps

• Working with Files. Details on file tools available to agents.
• Spaces. Shared conversation context (separate from workspaces).
• Creating & Configuring Agents. Agent settings and configuration.