File

In Eidos, while dynamic data (like tables and documents) lives in a SQLite database, static assets (images, audio, video) are handled more flexibly. This article introduces file management in Eidos through two lenses: File Storage & Paths and Extension Support.

File Storage & Paths

Eidos uses distinct path prefixes (such as /files/, /@/, and /~/) to categorize files from different sources.

These paths serve several key purposes:

Reference & Display: You can insert these paths into documents to reference assets like images or audio, or use them within a “File” type field in tables.
Extension Environment Access: In programming environments like Blocks, these paths can be used directly as the src attribute for native Web tags (e.g., <img />, <video />).
API Read/Write: For scenarios requiring lower-level control, you can use these paths with the eidos.space.fs API to read from or write to the file system.

You can see a unified view of these locations in the Eidos file browser:

Directorymy-awesome-space/ (Project Root /~/)
- Directory.eidos/
  - db.sqlite3
  - Directoryfiles/ (Internal Files /files/)
    screenshot.png
- Directorysrc/
  - main.js
- .gitignore
- Directorydocs/
  - api.md
- readme.md
Directory@audio/ (Mounted Folder)
- song.mp3
Directory@books/ (Mounted Folder)
- programming-guide.pdf
- design-principles.pdf
- api-reference.pdf

1. Default Storage (Internal Files)

Directorymy-project/
- Directory.eidos/
  - db.sqlite3 ← dynamic data storage
  - Directoryfiles/ ← /files/ path for internal assets
    screenshot.png

By default, when you load local files or paste screenshots into Eidos, these assets are copied from the clipboard or disk location to the .eidos/files/ directory.

You can access these internal files via the /files/ path, which is equivalent to accessing them via the project path at /~/.eidos/files/.

Eidos already supports basic file storage and management, with future versions planned to include enhancements like OCR text extraction and semantic search. All files are managed centrally by Eidos and bundled for easy synchronization.

2. Mounted Folders (External Files `/@/`)

Directory/Users/eidos/Music/ ← mounted as /@/audio/
- song.mp3
Directory/Users/eidos/Documents/Books/ ← mounted as /@/books/
- programming-guide.pdf
- design-principles.pdf
- api-reference.pdf

Since data within the .eidos directory is synchronized, large files (such as audio libraries or ebook collections) may not be suitable to store there. In such cases, use the Mount feature.

Once mounted, you can see the mounted items in the Eidos file picker and reference files using the /@/<mount-name>/filename syntax.

Command Line: Use eidos mount <mount-name> <actual-directory-path>
UI: Add via the “Mounts” tab in “Space Settings” by choosing a local directory and providing a name.

Example:

# Mount local music
eidos mount audio /Users/eidos/Music
# Then access via /@/audio/song.mp3

# Mount ebooks
eidos mount books /Users/eidos/Documents/Books
# Then access via /@/books/design.pdf

3. Project Folder (Contextual Path `/~/`)

Directorymy-code-project/
- Directory.eidos/
  - db.sqlite3
  - Directoryfiles/
    …
- Directorysrc/
  - main.js ← /~/src/main.js
- .gitignore ← /~/.gitignore
- Directorydocs/
  - api.md ← /~/docs/api.md
- readme.md ← /~/readme.md

The project folder is a special concept. Each Space creates a .eidos directory within a specific location; the folder containing that directory is called the Project Folder. This could be a code repository, a design project, or any other working directory.

You do not need a manual mount to access the project folder. Eidos provides a simplified syntax: /~/ points directly to the root of the project folder. This is ideal for referencing documentation, configuration files, or media assets within your current working project:

/~/src/main.js
/~/.gitignore
/~/docs/api.md

Extension & Interaction Support

Beyond basic referencing, Eidos allows you to use standard web technologies to customize how you interact with different file formats.

File Handlers

Leveraging Block Extensions, you can build custom interfaces for files using React, CSS, and HTML.

This acts like an “Open With” feature. You can register specialized Handlers for specific extensions (e.g., .excalidraw, .md). When you click a file in the directory tree, the system launches the associated Block. Extensions can directly read from and write to the raw local files using the eidos.space.fs API.

File Actions

With Script Extensions, you can define background tasks for files that don’t require a UI.

Integrated into the right-click context menu, File Actions enable one-click operations like “Compress Image,” “Convert Format,” or “Generate PDF.” Scripts run in the background and provide feedback via system notifications, making them perfect for batch processing or automated workflows.

For more details, see: