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:
# 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
# /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)
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)
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:
# ❌ 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
# ✅ 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:
# ❌ WRONG: write_file fails with Permission denied
write_file(path="/sdcard/VisualAgent/commands/cmd.json", content="{...}")
# ✅ 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:
#!/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)
cmd_type=$(su -c "cat '$cmd_file'" | grep -o '"type"[[:space:]]*:[[:space:]]*"[^"]*"' | cut -d'"' -f4)
✅ Python (robust, handles any valid JSON)
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
#!/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)
# 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)
su -c "printf '%s\n' '{\"type\":\"screenshot\",\"id\":\"test\"}' > /sdcard/VisualAgent/commands/test.json"
✅ heredoc with cat (best for multi-line JSON)
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)
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)
# 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)
# 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
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 |