Skip to main content

​
Mounting via S3

Shelv stores structured files in S3-compatible object storage (Cloudflare R2). You can get scoped temporary credentials to mount a shelf’s filesystem directly in sandboxes like E2B, Daytona, or any environment that supports s3fs.

​
Get Temporary Credentials

curl https://api.shelv.dev/api/shelves/{id}/creds?ttl=3600 \
  -H "Authorization: Bearer sk_your_api_key"
Response: 
{
  "accessKeyId": "...",
  "secretAccessKey": "...",
  "sessionToken": "...",
  "endpoint": "https://....r2.cloudflarestorage.com",
  "bucket": "shelv-storage",
  "region": "auto",
  "prefix": "users/.../shelves/.../files/",
  "expiresAt": "2025-01-15T11:30:00.000Z"
}
The ttl query parameter controls how long the credentials are valid (in seconds). Default is 3600 (1 hour), maximum is 86400 (24 hours).

​
Mount with s3fs

Install s3fs-fuse and mount the shelf: 
# Create credentials file
echo "$ACCESS_KEY_ID:$SECRET_ACCESS_KEY" > ~/.passwd-s3fs
chmod 600 ~/.passwd-s3fs

# Mount
mkdir -p /mnt/shelf
s3fs "$BUCKET:$PREFIX" /mnt/shelf \
  -o url="$ENDPOINT" \
  -o passwd_file=~/.passwd-s3fs \
  -o use_session_token \
  -o session_token="$SESSION_TOKEN"
Now your agent can use standard filesystem operations: 
ls /mnt/shelf/
cat /mnt/shelf/chapter-01.md
grep -r "liability" /mnt/shelf/

​
Mount in E2B

from e2b_code_interpreter import Sandbox

sandbox = Sandbox()

# Get credentials from Shelv
creds = requests.get(
    f"https://api.shelv.dev/api/shelves/{shelf_id}/creds",
    headers={"Authorization": f"Bearer {api_key}"},
).json()

# Configure s3fs in the sandbox
sandbox.filesystem.write(
    "/root/.passwd-s3fs",
    f"{creds['accessKeyId']}:{creds['secretAccessKey']}"
)
sandbox.process.start("chmod 600 /root/.passwd-s3fs")

sandbox.process.start(
    f"s3fs {creds['bucket']}:{creds['prefix']} /mnt/shelf "
    f"-o url={creds['endpoint']} "
    f"-o passwd_file=/root/.passwd-s3fs "
    f"-o use_session_token "
    f"-o session_token={creds['sessionToken']}"
)

# Now your agent can read files
result = sandbox.process.start("cat /mnt/shelf/chapter-01.md")
print(result.stdout)

​
Credential Scoping

Temporary credentials are scoped to only the shelf’s files/ prefix. They provide read-only access — agents cannot modify the stored files through S3. Credentials expire at the time specified in expiresAt. Request new credentials as needed.