Filesystem

The filesystem feature is a host-owned capability. It works with any provider because the daemon manages file access directly.

Browse files

• GET /api/fs/roots — list workspace roots
• GET /api/fs/list?path=... — list a directory
• GET /api/fs/metadata?path=... — file metadata (size, mtime)

Read and write

• GET /api/fs/read?path=... — read file contents
• POST /api/fs/write — write or overwrite a file
• POST /api/fs/createDir — create a directory
• POST /api/fs/remove — delete a file or directory
• POST /api/fs/copy — copy a file

Live updates

Connect to WS /api/fs/live to receive real-time file change notifications. When the agent edits a file, the app refreshes the file view automatically.

Workspace sandboxing

The daemon resolves paths against an explicit allowlist plus the working directories reported by existing sessions. A normal sidemesh setup stores your home directory as the initial allowlisted root; advanced setup lets you choose narrower roots. You can also override the persisted list with a comma-separated environment variable:

SIDEMESH_WORKSPACE_ROOTS=/Users/me/code,/Users/me/documents sidemesh daemon

Each root must be absolute. resolveWorkspacePath canonicalizes paths with realpath and checks path boundaries to prevent traversal and symlink escapes. Unknown session IDs fail closed, direct blob/image reads use the same scope, and workspace roots themselves cannot be deleted through the API. Attempts to access files outside the workspace return HTTP 403.

Security notes

• Filesystem access requires the shared bearer token
• There is no per-file permission model; token holders can read/write anything inside the workspace roots
• Prefer the narrowest practical SIDEMESH_WORKSPACE_ROOTS allowlist
• Keep the daemon on trusted networks only