Skip to content

paths

paths

Platform-aware path resolution for terok-agent directories.

Provides XDG / FHS resolution for the agent's own state directory, independent of terok-sandbox's namespace.

state_root()

Writable state root for agent-owned data.

Priority: TEROK_AGENT_STATE_DIR → /var/lib/terok/agent (root) → platformdirs.user_data_dir() → $XDG_DATA_HOME/terok/agent → ~/.local/share/terok/agent.

Source code in src/terok_agent/paths.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
def state_root() -> Path:
    """Writable state root for agent-owned data.

    Priority: ``TEROK_AGENT_STATE_DIR`` → ``/var/lib/terok/agent`` (root)
    → ``platformdirs.user_data_dir()`` → ``$XDG_DATA_HOME/terok/agent``
    → ``~/.local/share/terok/agent``.
    """
    env = os.getenv("TEROK_AGENT_STATE_DIR")
    if env:
        return Path(env).expanduser()
    if _is_root():
        return Path("/var/lib") / _UMBRELLA / _SUBDIR
    if _user_data_dir is not None:
        return Path(_user_data_dir(_UMBRELLA)) / _SUBDIR
    xdg = os.getenv("XDG_DATA_HOME")
    if xdg:
        return Path(xdg) / _UMBRELLA / _SUBDIR
    return Path.home() / ".local" / "share" / _UMBRELLA / _SUBDIR

mounts_dir()

Base directory for agent config bind-mounts.

Each agent/tool gets a subdirectory (e.g. _claude-config/) that is bind-mounted read-write into task containers. These directories are intentionally separated from the credentials store since they are container-exposed and subject to potential poisoning.

Source code in src/terok_agent/paths.py 
54
55
56
57
58
59
60
61
62
def mounts_dir() -> Path:
    """Base directory for agent config bind-mounts.

    Each agent/tool gets a subdirectory (e.g. ``_claude-config/``) that is
    bind-mounted read-write into task containers.  These directories are
    intentionally separated from the credentials store since they are
    container-exposed and subject to potential poisoning.
    """
    return state_root() / "mounts"