Skip to main content

Security

18.1 Path Validation

Import: from gaia.security import PathValidator
Every agent tool that takes a path checks it with validate_read or validate_write: reading, listing a folder, searching inside one, indexing it, watching it, and the files a tool saves (screenshots, transcripts, speech, exports). Out-of-scope paths go through the same approval prompt as read_file. The validator expands ~ and resolves .. and symlinks before it decides, and a folder walk skips any entry that leads outside the scope. Tools build on these checks through gaia.agents.tools.path_access rather than adding their own. Three things are wider on purpose:
  • A name search (search_file, find_files with a named scope) can return paths under the common document folders. Opening one is still checked. On macOS an undirected search skips Desktop, Documents, Downloads, iCloud Drive, Music, the TV app’s library and the Photos library unless the user named the folder or allowed it, because macOS blocks the first read of them behind a permission prompt; the result says which it skipped.
  • Output a tool writes to GAIA’s own folders (~/.gaia/screenshots, ~/.gaia/transcripts, ~/.gaia/tts) is not the user’s files and is not checked.
  • capture_skill may copy a local skill folder from anywhere, because every capture asks the user first with the source shown.
ChatAgent and GaiaAgent create one scratch directory per agent that has a file-writing tool, name it in the system prompt, and delete it when the agent is cleaned up (GaiaAgent.close()). The chat profile has no file-writing tools, so it gets none.
Only a validator built without an allowed_paths argument reads or writes the machine-global grants in ~/.gaia/cache/allowed_paths.json. A host that computes a per-session scope gets exactly that scope — one user’s one-off [a]lways approval in the CLI must not become standing access for every later Agent UI session.

Narrowing the scope for a run

GAIA_ALLOWED_PATHS (absolute paths joined with os.pathsep) narrows every PathValidator the process builds, whatever scope its host computed. An evaluation harness uses it so the agent cannot read answer keys stored outside the task folder.
  • The scope becomes the overlap of the host’s scope and the list. An entry outside the host’s scope is logged and ignored; it never widens.
  • Later grants are held to it too: add_allowed_path, approval prompts (including an approve-everything harness or full access), and persisted CLI grants.
  • The scratch directory set by set_scratch_dir stays allowed even when it sits outside the list, so run_python helper scripts keep working.
  • ChatAgent (and so GaiaAgent) narrows its allowed_paths once at construction, so its validator, the RAG SDK and the code-index ceilings agree.
  • An empty value, an empty entry, a relative path or a missing folder raises AllowedPathsEnvError (a ValueError) when the validator is built. The Agent UI server and the flagship sidecar check it before they start serving.
This confines GAIA’s tools, not code they run. A run_python script or shell command can still open any file the OS user can read. Real isolation needs OS-level separation: a separate user account, a container, or a VM.


18.3 File Size Limits