termux-sdcard-permission-patterns.md 10.1 KB

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