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).
Sandbox policies use virtual paths to grant access across these areas. Suppose the signed-in user's handle is alice:
| Policy path | Storage path |
|---|---|
user://alice/report.pdf | data/users/alice/files/report.pdf |
agent://researcher/output.csv | data/users/alice/agents/researcher/output.csv |
The user path includes its owner's handle. The agent path does not. Frona gets the user handle from the current account, then treats the first segment after agent:// as the agent handle. For example, agent://alice/researcher/output.csv names the agent alice and the relative path researcher/output.csv. It does not name user alice and agent researcher.
These virtual paths belong in sandbox settings and Cedar policies. They are not path arguments for the agent's read, write, edit, glob, or grep tools.
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
Open Files to browse My Files and all agent workspaces you own. You can:
- View the file list and directory structure
- Create folders, rename items, and delete content in either area
- Copy or move content between My Files and agent workspaces
- Download files the agent created
Direct uploads go to My Files. Copy or move them into an agent workspace afterward. The current folder is part of the URL, so reload and browser history return you to the same place.
Frona does not allow file operations on the My Files or workspace roots. It also rejects attempts to reach another user's storage or an agent workspace you do not own.
Workspace layers
Agent workspaces have two layers:
- Primary layer (read/write). The agent's own directory where it stores files.
- 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.