# Termux /sdcard/ Permission Patterns ## Problem When working with `/sdcard/` subdirectories from Termux (e.g., `/sdcard/VisualAgent/commands/`), standard file operations often fail with permission errors even though the directory appears writable. This is because `/sdcard/` is a FUSE mount with `media_rw` group ownership, and the Termux app UID may not have the right group membership. ## Error Signatures ``` mkdir: cannot create directory '/sdcard/VisualAgent': Permission denied cat: /sdcard/VisualAgent/commands/cmd.json: Permission denied mv: cannot stat '/sdcard/VisualAgent/commands/cmd.json': Permission denied ``` Also, Hermes `write_file` tool may fail: ``` Failed to write file: /storage/self/primary/VisualAgent/commands/.hermes-tmp.XXXX: Permission denied ``` ## Android Storage Path Discovery On some Android devices (especially Android 10+ or certain OEM skins), the external storage path differs from `/sdcard/`: | Path | What it is | When to use | |------|-----------|-------------| | `/sdcard/` | Symlink to `/storage/self/primary` | May not exist or be accessible | | `/storage/emulated/0/` | The actual FUSE mount point | Use when `/sdcard/` fails | | `/mnt/user/0/emulated/` | Kernel mount point | Fallback if emulated fails | | `/data/media/0/` | Underlying filesystem (no FUSE) | Root-only, bypasses permissions | ### Discovery Workflow When `/sdcard/` operations fail: ```bash # Step 1: Check what's actually mounted su -c "cat /proc/mounts | grep fuse" # Look for lines like: # /dev/fuse /storage/emulated fuse ... # /dev/fuse /mnt/user/0/emulated fuse ... # Step 2: Verify the path exists and is accessible su -c "ls -la /storage/emulated/0/" | head -5 # Step 3: If that works, use /storage/emulated/0/ instead of /sdcard/ ``` ### Example: Path Discovery on a Real Device ```bash # /sdcard/ doesn't exist or is empty $ ls /sdcard/ ls: cannot access '/sdcard/': No such file or directory # Check mounts $ su -c "cat /proc/mounts | grep -E '(sdcard|fuse|storage)" tmpfs /storage tmpfs rw,seclabel,nosuid,nodev,noexec,relatime,mode=755,gid=1000 0 0 /dev/fuse /mnt/user/0/emulated fuse rw,lazytime,nosuid,nodev,noexec,noatime,user_id=0,group_id=0,allow_other 0 0 /dev/fuse /storage/emulated fuse rw,lazytime,nosuid,nodev,noexec,noatime,user_id=0,group_id=0,allow_other 0 0 # The real path is /storage/emulated/0/ $ su -c "ls -la /storage/emulated/0/" | head -5 drwxrws--- 2 u0_a305 media_rw 3452 2026-06-24 23:48 Alarms drwxrws--x 5 media_rw media_rw 3452 2026-06-24 23:48 Android ... ``` **Key insight**: The `EXTERNAL_STORAGE=/sdcard` environment variable may point to a non-existent path. Always verify the actual mount point before assuming `/sdcard/` works. ## The Fix: Use `su` for ALL File Operations When working with `/sdcard/` subdirectories, wrap **every** file operation with `su -c`: ### ❌ Without su (fails) ```bash ls /sdcard/VisualAgent/commands/ cat /sdcard/VisualAgent/commands/*.json mv /sdcard/VisualAgent/commands/cmd.json /sdcard/VisualAgent/processed/ echo '{"status":"ok"}' > /sdcard/VisualAgent/results/result.json ``` ### ✅ With su (works) ```bash su -c "ls /sdcard/VisualAgent/commands/" su -c "cat /sdcard/VisualAgent/commands/*.json" su -c "mv /sdcard/VisualAgent/commands/cmd.json /sdcard/VisualAgent/processed/" su -c "echo '{\"status\":\"ok\"}' > /sdcard/VisualAgent/results/result.json" ``` ## Critical Pitfall: Shell Glob Expansion The shell expands globs (`*.json`) **before** executing the command, so this pattern fails silently: ```bash # ❌ WRONG: glob expands in parent shell, which can't read the directory for f in /sdcard/VisualAgent/commands/*.json; do [ -e "$f" ] || continue echo "Processing: $f" done # Output: nothing, or "*.json" literally if directory is unreadable ``` ```bash # ✅ CORRECT: use su to list files, then iterate for f in $(su -c "ls -1 /sdcard/VisualAgent/commands/*.json 2>/dev/null"); do [ -e "$f" ] || continue echo "Processing: $f" done ``` ## Critical Pitfall: write_file Tool on /sdcard/ Hermes `write_file` tool writes to the path directly and may fail on `/sdcard/` subdirectories: ```python # ❌ WRONG: write_file fails with Permission denied write_file(path="/sdcard/VisualAgent/commands/cmd.json", content="{...}") ``` ```bash # ✅ CORRECT: use terminal with su echo '{"type":"screenshot"}' > /tmp/cmd.json su -c "cp /tmp/cmd.json /sdcard/VisualAgent/commands/" # Or directly: su -c "echo '{\"type\":\"screenshot\"}' > /sdcard/VisualAgent/commands/cmd.json" ``` ## Shebang for Android Shell Scripts When writing shell scripts that will run on Android via `su -c "sh script.sh"`, use the system shell path: ```bash #!/system/bin/sh # NOT: #!/data/data/com.termux/files/usr/bin/bash ``` The Termux bash may not be accessible from the `su` environment. `/system/bin/sh` is always available. ## Python vs Shell for JSON Parsing For Android automation that involves JSON command files, **Python is strongly preferred** over shell `grep`/`sed` parsing: ### ❌ Shell (fragile, breaks on nested quotes) ```bash cmd_type=$(su -c "cat '$cmd_file'" | grep -o '"type"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4) ``` ### ✅ Python (robust, handles any valid JSON) ```python import json def read_json_file(filepath): success, stdout, stderr = run_su(f"cat '{filepath}'") if success: return json.loads(stdout) return None ``` The Python version handles: - Nested quotes - Unicode/emoji in text fields - Numbers, booleans, nulls - Arrays and nested objects - Different whitespace formatting ## Practical Pattern: Python Script with su Helper ```python #!/data/data/com.termux/files/usr/bin/python3 import json, subprocess def run_su(cmd): full_cmd = f"su -c '{cmd}'" result = subprocess.run(full_cmd, shell=True, capture_output=True, text=True, timeout=30) return result.returncode == 0, result.stdout, result.stderr def read_json_file(path): success, stdout, _ = run_su(f"cat '{path}'") return json.loads(stdout) if success else None def write_json_file(path, data): json_str = json.dumps(data, ensure_ascii=False) run_su(f"echo '{json_str}' > '{path}'") # List files success, stdout, _ = run_su("ls -1 /sdcard/VisualAgent/commands/*.json 2>/dev/null") files = [line.strip() for line in stdout.split('\n') if line.strip()] for f in files: cmd = read_json_file(f) if cmd: result = process_command(cmd) write_json_file(f.replace('commands', 'results').replace('.json', '_result.json'), result) run_su(f"mv '{f}' '/sdcard/VisualAgent/processed/'") ``` ## Critical Pitfall: JSON Quoting in Shell Creating JSON command files via `echo` with complex quoting often fails because the shell interprets the quotes before they reach the file: ### ❌ echo with nested quotes (fragile) ```bash # This often fails because the shell interprets the inner quotes su -c "echo '{\"type\":\"screenshot\",\"id\":\"test\"}' > /sdcard/VisualAgent/commands/test.json" # May produce: {type:screenshot,id:test} (quotes stripped) ``` ### ✅ printf with explicit format (reliable) ```bash su -c "printf '%s\n' '{\"type\":\"screenshot\",\"id\":\"test\"}' > /sdcard/VisualAgent/commands/test.json" ``` ### ✅ heredoc with cat (best for multi-line JSON) ```bash su -c "cat > /sdcard/VisualAgent/commands/test.json << 'JSONEOF' {\"type\":\"screenshot\",\"id\":\"test\",\"params\":{\"path\":\"/sdcard/VisualAgent/screenshot.png\"}} JSONEOF" ``` ### ✅ Python one-liner (most reliable for complex JSON) ```bash su -c "python3 -c \"import json; json.dump({'type':'screenshot','id':'test'}, open('/sdcard/VisualAgent/commands/test.json','w'))\"" ``` **Key insight**: The `echo` command with single-quoted JSON containing double quotes works in some shells but fails in others (especially when wrapped in `su -c`). Use `printf '%s\n'` or Python for guaranteed correctness. ## Critical Pitfall: `cp` via `su` from Termux home to /sdcard/ When copying files from the Termux home directory (`/data/data/com.termux/files/home/`) to `/sdcard/` using `su -c "cp ..."`, the file may appear to copy successfully but then disappear or have incorrect permissions: ### ❌ Direct cp with su (may fail silently) ```bash # Write file in Termux home (works) echo '{"type":"screenshot"}' > /data/data/com.termux/files/home/test.json # Copy with su (appears to work but file may disappear) su -c "cp /data/data/com.termux/files/home/test.json /sdcard/VisualAgent/commands/" # File may be visible briefly then disappear due to FUSE cache or permission mismatch ``` ### ✅ Write directly with su (reliable) ```bash # Write directly to target with su, bypassing the copy su -c "printf '%s\n' '{\"type\":\"screenshot\"}' > /sdcard/VisualAgent/commands/test.json" ``` ### ✅ Use Python to create file atomically ```bash su -c "python3 -c \"import json; json.dump({'type':'screenshot'}, open('/sdcard/VisualAgent/commands/test.json','w'))\"" ``` **Why `cp` fails**: The FUSE filesystem (`/sdcard/`) may cache or validate files written by root differently than files written by the app UID. When `su` copies a file, the ownership and SELinux context may not match what the FUSE layer expects, causing the file to be hidden or removed. Writing directly with `su` avoids this issue because the file is created with the correct context from the start. ## Summary Table | Operation | Without su | With su | Notes | |-----------|-----------|---------|-------| | `mkdir` | ❌ Fails | ✅ Works | Always use su for /sdcard/ | | `ls` | ❌ Fails | ✅ Works | Directory listing | | `cat` | ❌ Fails | ✅ Works | File reading | | `echo >` | ❌ Fails | ✅ Works | File writing | | `mv` | ❌ Fails | ✅ Works | Moving files | | `rm` | ❌ Fails | ✅ Works | Deleting files | | `find` | ❌ Fails | ✅ Works | Recursive search | | `cp` (Termux→/sdcard/) | ❌ May fail | ⚠️ Use direct write | FUSE cache/permission issues | | Glob `*.json` | ❌ Fails | ✅ Use `$(su -c "ls -1 ...")` | Shell expands before su | | `write_file` tool | ❌ Fails | N/A | Use terminal + su instead | | `read_file` tool | ❌ Fails | N/A | Use terminal + su instead | | Path discovery | ❌ Blind | ✅ Check /proc/mounts | /sdcard/ may not exist | | JSON creation | ❌ echo fragile | ✅ printf or Python | Use printf '%s\n' or Python |