docs/mounting/sprite.md

Mounting on Sprite

Prerequisites and remote mount flow for Sprite sandboxes.

Markdown

Sprite sandboxes are Linux containers (Ubuntu 25.10 base as of 2026-05-18). They can mount FUSE but require four one-time prerequisites because the base image is minimal.

See `README.md` for the general overview and architecture.

Prerequisites

Run these four commands inside the sprite before mounting:

bash
sudo apt-get update -qq && sudo apt-get install -y fuse3
sudo chmod 666 /dev/fuse
sudo ln -sf /proc/mounts /etc/mtab
echo user_allow_other | sudo tee -a /etc/fuse.conf

Each step is necessary:

StepWhy
apt-get install fuse3fusermount3 + libfuse3 are not in the sprite base image.
chmod 666 /dev/fuseDefault perms on the sprite are c-w--wx-wT, unreadable for the non-root sprite user.
ln -sf /proc/mounts /etc/mtab/etc/mtab is absent; fusermount3 errors out trying to update the mount table.
user_allow_otherThe helper passes allow_other so other UIDs (supervisors) can read the mount.

One-liner idempotent script

bash
#!/usr/bin/env bash
# Apply all four agent-fs mount prereqs. Safe to re-run.
set -euo pipefail


sudo apt-get update -qq
sudo apt-get install -y fuse3
sudo chmod 666 /dev/fuse
[ -e /etc/mtab ] || sudo ln -sf /proc/mounts /etc/mtab
grep -q '^user_allow_other' /etc/fuse.conf 2>/dev/null \
  || echo user_allow_other | sudo tee -a /etc/fuse.conf
echo "agent-fs mount prereqs applied."

Save as prereqs.sh, then chmod +x prereqs.sh && ./prereqs.sh.

Sprite envs do not persist these changes across fresh sprite creations. Re-run the script every time you spin up a new sprite.

Install + mount

bash
# 1. Install the CLI (pulls the right FUSE sub-package via optionalDependencies).
# Sprite ships Bun pre-installed; use it. `npm install -g` against the stock
# Node aborts on a transitive dep's postinstall syntax.
bun install -g @desplega.ai/agent-fs


# 2. Configure auth (writes ~/.agent-fs/config.json).
mkdir -p ~/.agent-fs
cat > ~/.agent-fs/config.json <<EOF
{
  "apiUrl": "https://agent-fs-taras.fly.dev",
  "apiKey": "<YOUR_API_KEY>"
}
EOF


# 3. Verify auth.
agent-fs auth whoami


# 4. Make a mount point and mount in remote mode.
mkdir -p ~/mnt
agent-fs mount ~/mnt --remote

Verify

bash
ls ~/mnt
ls ~/mnt/current
echo "hello from sprite $(date)" > ~/mnt/current/sprite-test.txt
cat ~/mnt/current/sprite-test.txt
rm ~/mnt/current/sprite-test.txt

Unmount

bash
fusermount3 -u ~/mnt

Known issues

  • Writes return `EACCES` if you used a sprite-local daemon without an S3 backend. Use --remote against a hosted instance instead — the FUSE plumbing itself works fine.
  • `fusermount3: failed to access mountpoint` — your mount path doesn't exist (mkdir -p ~/mnt first).
  • See `fuse-troubleshooting.md` for the full error catalogue.

See also