Workspaces
Last updated:
Workspaces give agents a named, reviewable view of files. Managed workspaces and additional folders appear only when granted in agent settings or a task run scope.
Note
A managed workspace is a folder inside your private Oscova file area. It is not your whole user-data folder or your browser downloads folder.
Understand the file-access sources
An agent run can receive four kinds of file access:
| Source | How it is granted | Access |
|---|---|---|
| Managed workspace | Select it under Workspace Folders | Read and write, except Library |
| Agent data | Added automatically for that agent | Read and write |
| Additional folder | Add it under Additional Folder Access | Your selected mode |
| Run attachment | Attach it to the current chat | Temporary read-only access |
The default workspace is available for selection but is not automatically granted. The agent's data folder is automatic and private to that agent. It stores agent-owned material such as private notes.
The managed Library workspace is always read-only to agents. Selecting it also enables Library Search. Manage Library files through Settings > Files so indexing stays synchronized.
Additional folders support two sources:
- External points to an existing folder on the Oscova host.
- Managed points to a folder inside your private Oscova user area.
Give every additional folder a label and choose Read Only or Read & Write. Prefer read-only for reference material.
Use agent-facing paths
Container-sandboxed runs use one stable path vocabulary:
- Managed workspaces appear as
/workspace/<name>. - The agent's private data folder appears as
/data. - Additional folders appear as
/mnt/<label>.
Labels and workspace names are normalized for mount paths. For example, repeated punctuation becomes a hyphen and letters become lowercase. Saving is blocked when two entries under the same mount root normalize to the same path.
In Host or Disabled execution mode, the agent receives real host paths instead. Relative paths use the run's writable working directory, normally the selected default workspace or the first writable grant.
File tools run in the host process, resolve the agent-facing path to an approved host path, and perform host file operations there. Container-sandboxed shell commands see the same files through bind mounts. A Docker sandbox therefore isolates command execution, while path grants remain the file-access boundary shared by both surfaces.
MCP servers have their own execution environment and permissions. Review the server configuration as well as the agent's tool selection before trusting an MCP tool with files.
Know what containment blocks
Oscova checks file-tool paths again when the tool is invoked. It rejects:
- paths outside the run's approved directories.
..traversal that resolves outside a grant.- symlink or reparse-point hops beneath an approved root.
- writes inside a read-only grant.
When grants overlap, the most specific matching directory controls access. If the same path has conflicting modes, read-only wins.
This enforcement does not make every tool safe. Host shell commands are not confined by file-tool grants. They retain Oscova's operating-system account permissions. A tool must mark its file parameters for workspace validation, and commands or external programs retain the permissions of their configured execution environment.
Troubleshoot file access
- Confirm the workspace or folder is selected for the current agent or task scope.
- Save the agent after changing grants.
- Confirm the agent has an appropriate file or PDF tool.
- Use the agent-facing path shown for the current execution mode.
- Check whether the grant is read-only before requesting a write.
- Rename labels that collide after mount-name normalization.
- For Library search problems, manage files through Settings > Files and check indexing status.
- For MCP file problems, review that server's host or Docker execution environment.