Skip to content

Ultra-fast temporary storage in RAM, enabled by default. Every container has /ramdisk available (unless explicitly disabled)—perfect for caches, build artifacts, and temporary processing that needs maximum speed.


Container Configuration:

File Access:


Understanding /ramdisk:

Capacity: up to 50% of Host Memory

Maximum size, not allocated upfront:

Host with 64GB RAM:

  • /ramdisk capacity: up to 32GB max (capped lower if the project is bound to a memory-limited subserver)
  • Actual usage: Only what you store
  • Empty ramdisk = 0 bytes RAM used

On-demand allocation - RAM consumed only when files written, freed when deleted.

Speed: RAM Performance

Orders of magnitude faster than disk:

  • Read: ~10-20 GB/s
  • Write: ~10-20 GB/s
  • Latency: <1µs

vs. SSD:

  • Read: ~0.5-3 GB/s
  • Write: ~0.5-2 GB/s
  • Latency: ~50-100µs

Survives Container Restarts

Unique Hoody feature:

  • ✅ Persists through container stop/start
  • ✅ Persists through container restart
  • Cleared on host reboot

Data survives container operations, not host reboots.

NOT Shared Between Containers

Each container has isolated ramdisk:

  • Container A’s /ramdisk ≠ Container B’s /ramdisk
  • Cannot share via storage shares
  • Independent memory allocation

For shared RAM: Use shared storage + OS page cache.


Every container automatically has /ramdisk available unless explicitly disabled.

Terminal window
# Create container — ramdisk enabled by default
hoody containers create --project $PROJECT_ID --server-id $SERVER_ID --name "my-container" --hoody-kit
# Create container with ramdisk explicitly disabled
hoody containers create --project $PROJECT_ID --server-id $SERVER_ID --name "no-ramdisk" --hoody-kit --no-ramdisk
POST Create container with ramdisk enabled (default behavior)
/api/v1/projects/{project_id}/containers
Click "Run" to execute the request

/ramdisk is available immediately but consuming ZERO RAM (empty = no allocation).

Check ramdisk status:

Terminal window
GET /api/v1/containers/{id}
# Response: "ramdisk": true (enabled) or false (disabled)

Access like any directory:

Terminal window
# In container (via terminal or SSH)
cd /ramdisk
# Create directories
mkdir -p /ramdisk/cache
mkdir -p /ramdisk/builds
# Write files (ultra-fast)
echo "data" > /ramdisk/cache/session-abc.json
# Read files (ultra-fast)
cat /ramdisk/cache/session-abc.json
# Check usage
df -h /ramdisk

Files in /ramdisk are stored in RAM - no disk I/O.


Terminal window
# Use ramdisk for node_modules and build output
export NPM_CONFIG_CACHE=/ramdisk/npm-cache
cd /home/user/project
npm install # Downloads to /ramdisk (fast)
npm run build # Output to /ramdisk/dist (fast)
# Then copy final artifacts to persistent storage
cp -r /ramdisk/dist /hoody/storage/production/

Speed boost: 5-10x faster npm install and builds.

Terminal window
# Application cache in RAM
mkdir -p /ramdisk/app-cache
# Store frequently accessed data
cp /hoody/databases/users.db /ramdisk/app-cache/
sqlite3 /ramdisk/app-cache/users.db "SELECT ..." # Ultra-fast
# Session storage
echo '{"user": 1, "token": "abc"}' > /ramdisk/sessions/user-1.json

Response time: <1ms for cache hits.

Process files without disk I/O:

Terminal window
# Download large file to ramdisk
curl "https://data.example.com/dataset.csv" > /ramdisk/dataset.csv
# Process in RAM (no disk writes)
awk -F',' '{sum+=$3} END {print sum}' /ramdisk/dataset.csv > /ramdisk/result.txt
# Upload result (delete temp file automatically on next host reboot)
curl -X POST "https://api.example.com/results" \
-d "@/ramdisk/result.txt"

No disk wear from temporary files.

Terminal window
# Extract frames to ramdisk (burst I/O)
ffmpeg -i video.mp4 /ramdisk/frames/frame_%04d.png
# Process frames (parallel reads - ultra-fast)
for frame in /ramdisk/frames/*.png; do
convert $frame -resize 50% $frame
done
# Merge back to video
ffmpeg -i /ramdisk/frames/frame_%04d.png output.mp4

Thousands of small file operations benefit massively from RAM speed.


CRITICAL: You are responsible for memory balance across containers.

Each container ramdisk has CAPACITY of up to 50% of total host memory (capped lower if the project is bound to a memory-limited subserver):

Host with 8GB RAM:
- /ramdisk CAPACITY: up to 4GB max
- Actual RAM used: Only what you store
- Empty ramdisk: 0 bytes RAM consumed
Host with 16GB RAM:
- /ramdisk CAPACITY: up to 8GB max
- Store 1GB: 1GB RAM used
- Store 8GB: 8GB RAM used

Critical distinction: CAPACITY ≠ allocation. RAM consumed on-demand, freed automatically.

If multiple containers FILL their ramdisks, total usage can exceed host RAM:

Terminal window
# Host has 32GB RAM total
# Create 4 containers (ramdisk enabled by default)
# Each container's /ramdisk CAPACITY is up to 16GB (50% of the 32GB host)
Container A: /ramdisk capacity up to 16GB
Container B: /ramdisk capacity up to 16GB
Container C: /ramdisk capacity up to 16GB
Container D: /ramdisk capacity up to 16GB
# Scenario 1: Light usage (SAFE)
# Each stores 1GB: Total 4GB RAM used ✅
# Scenario 2: Heavy usage (CAREFUL)
# Each stores 8GB: Total 32GB RAM used (maxed) ⚠️
# Scenario 3: Overcommit (SWAP)
# Each stores 8GB + processes use RAM: >32GB → SWAP ❌

When ACTUAL ramdisk usage exceeds host RAM:

  • ✅ Containers run without errors
  • Performance degrades heavily (SWAP is disk-based)
  • Defeats the purpose of using ramdisk (now using disk anyway)

Remember: Having 10 containers with ramdisk enabled is fine if they’re mostly empty. Problem occurs when you FILL multiple ramdisks simultaneously.

Example planning:

Terminal window
# Host: 128GB RAM
# Safe allocation:
# Target max ramdisk USAGE: 64GB (50% of 128GB)
# Scenario A: Many containers, light ramdisk usage
# 16 containers (each /ramdisk can grow to ~64GB, but you keep usage light)
# Each stores ~2GB actually
# Total: 16 × 2GB = 32GB ✅ (safe, plenty of headroom)
# Scenario B: Fewer containers, heavy usage
# 4 containers (each /ramdisk can grow to ~64GB)
# Each stores 12GB actually
# Total: 4 × 12GB = 48GB ✅ (safe on 128GB host)
# Scenario C: Dangerous
# 10 containers, each storing 10GB in ramdisk
# Total: 100GB ramdisk + processes + OS → SWAP ❌

Monitor ACTUAL usage via df -h /ramdisk, not theoretical capacity.

Check host-level memory:

Terminal window
# Drop a one-off script into hoody-exec and invoke it. Auth: Bearer $PROXY_TOKEN
# is the token issued for the container-proxy path (see /kit/exec/).
SERVICE="https://{project}-{container}-exec-1.{server}.containers.hoody.icu"
# 1. Upload scripts/default/1/free.sh (raw body)
curl -sS -X POST "$SERVICE/hoody/storage/hoody-exec/scripts/default/1/free.sh" \
-H "Authorization: Bearer $PROXY_TOKEN" \
--data-binary 'free -h'
# 2. Run it — path-routed invocation returns the script's stdout
curl -sS "$SERVICE/free.sh" \
-H "Authorization: Bearer $PROXY_TOKEN"
# Response shows:
# total used free shared buff/cache available
# Mem: 64Gi 45Gi 2Gi 8Gi 16Gi 10Gi
# Swap: 16Gi 12Gi 4Gi ← ⚠️ SWAP usage is bad

If SWAP usage is high: Too many ramdisks in use simultaneously.

Fix:

  1. Disable ramdisk on less critical containers
  2. Reduce ramdisk usage (delete unused files)
  3. Add more RAM to host server

Terminal window
POST /api/v1/containers/{id}/{operation} # operation=restart

PERSISTS

  • All files in /ramdisk remain
  • Directory structure intact
  • No data loss

Unique to Hoody: Traditional ramdisks clear on reboot. Hoody’s /ramdisk persists through container operations.


Try ramdisk first, fall back to disk:

import os
def get_cached_data(key):
ramdisk_path = f'/ramdisk/cache/{key}.json'
disk_path = f'/hoody/storage/cache/{key}.json'
# Try ramdisk first (fast)
if os.path.exists(ramdisk_path):
return read_file(ramdisk_path)
# Fall back to disk
if os.path.exists(disk_path):
data = read_file(disk_path)
# Promote to ramdisk for next access
write_file(ramdisk_path, data)
return data
# Cache miss
return None

Build in ramdisk, save final output to disk:

#!/bin/bash
# Build script
# Compile in ramdisk (fast)
cd /ramdisk/build
cmake ..
make -j$(nproc)
# Test binary (fast startup from RAM)
./test-suite
# Copy ONLY final binary to persistent storage
cp binary /hoody/storage/production/app-v1.2.3
# Ramdisk build artifacts auto-deleted on host reboot

Store sessions in RAM for speed + auto-expiry:

// Sessions in ramdisk (fast read/write)
const sessionPath = `/ramdisk/sessions/${sessionId}.json`;
// Write session
fs.writeFileSync(sessionPath, JSON.stringify({userId, token, expiresAt}));
// Read session (ultra-fast)
const session = JSON.parse(fs.readFileSync(sessionPath));
// Host reboot = automatic session cleanup (no stale sessions)

Actual speed comparison:

Writing 1GB file:

StorageWrite SpeedTime
/ramdisk~15 GB/s~0.07s
SSD~2 GB/s~0.5s
HDD~200 MB/s~5s

RAM is 7-70x faster.


CRITICAL: Multiple containers with ramdisk can exceed host RAM.

Example scenario:

Terminal window
Host Server: 64GB RAM total
# Create 5 containers, each with ramdisk enabled
# Each /ramdisk can grow to up to 32GB (50% of the 64GB host)
Container 1: stores 16GB in /ramdisk
Container 2: stores 16GB in /ramdisk
Container 3: stores 16GB in /ramdisk
Container 4: stores 16GB in /ramdisk
Container 5: stores 16GB in /ramdisk
# Total ramdisk usage: 80GB (5 × 16GB)
# Host actual RAM: 64GB
# Overcommit: 80GB - 64GB = 16GB goes to SWAP

When SWAP is used:

  • SEVERELY degrades performance (SWAP is disk-based)
  • Defeats ramdisk purpose (now using disk for “RAM” storage)
  • Causes system instability (excessive swapping)

Example planning:

Terminal window
# Host: 128GB RAM
# Safe target:
# Max total ramdisk USAGE: 64GB (50% of host)
# Budget ~16GB of ramdisk usage per container
# Comfortable fit: ~4 containers (4 × 16GB = 64GB)
# Or: More containers with lighter ramdisk usage
# Budget ~8GB of ramdisk usage per container
# Comfortable fit: ~8 containers (8 × 8GB = 64GB)

Detect if you’re over-committed:

Terminal window
# Via hoody-exec (same upload-then-invoke pattern as above)
curl -sS -X POST "$SERVICE/hoody/storage/hoody-exec/scripts/default/1/swap.sh" \
-H "Authorization: Bearer $PROXY_TOKEN" \
--data-binary 'free -h | grep Swap'
curl -sS "$SERVICE/swap.sh" -H "Authorization: Bearer $PROXY_TOKEN"
# Response example:
# Swap: 32Gi 8Gi 24Gi
# ^^^^^^ ^^^^^
# total USED ← If >0, you're using SWAP
# If SWAP used > 1GB: Reduce ramdisk usage

Solutions if SWAP is high:

  1. Disable ramdisk on some containers
  2. Clear unnecessary ramdisk data: rm -rf /ramdisk/*
  3. Reduce number of containers with ramdisk enabled
  4. Upgrade host server RAM

1. ramdisk is Enabled by Default (Disable if Not Needed)

Section titled “1. ramdisk is Enabled by Default (Disable if Not Needed)”

Ramdisk is enabled automatically, but you can opt out at creation time:

Terminal window
# Disable ramdisk when creating the container (ramdisk is a create-time field)
POST /api/v1/projects/{id}/containers
{
"ramdisk": false // Explicitly disable at creation
}

When to disable:

  • ✅ Simple APIs (CRUD operations, no heavy I/O)
  • ✅ Static file servers
  • ✅ Long-running daemons with minimal disk access
  • ✅ Containers on hosts with limited RAM

When to keep enabled (default):

  • ✅ Build servers (compilation, npm install)
  • ✅ Cache servers (Redis-like workloads)
  • ✅ Media processing (video/image transcoding)
  • ✅ Data processing (ETL, analytics)

Remember: Enabled ramdisk with NO files = zero RAM consumed. Only disable if you’re CERTAIN container won’t benefit.

Never rely on /ramdisk for critical data:

Terminal window
# ✅ Good: Temporary processing
wget https://example.com/dataset.zip -O /ramdisk/dataset.zip
unzip /ramdisk/dataset.zip -d /ramdisk/processing/
# Process and save results to /hoody/storage
# ❌ Bad: Long-term storage
cp important-data.db /ramdisk/ # Lost on host reboot!

Rule: If data matters after host reboot, don’t put it ONLY in /ramdisk.

Ramdisk space is limited - clean up after tasks:

#!/bin/bash
# Build script with cleanup
# Build in ramdisk
npm install --prefix /ramdisk/build
npm run build --prefix /ramdisk/build
# Copy final bundle
cp /ramdisk/build/dist/*.js /hoody/storage/production/
# Clean up immediately (free RAM)
rm -rf /ramdisk/build
# Or clean on exit
trap 'rm -rf /ramdisk/build' EXIT
Terminal window
# Check ramdisk usage regularly
df -h /ramdisk
# Alert if >80% full
USAGE=$(df /ramdisk | awk 'NR==2 {print $5}' | sed 's/%//')
if [ $USAGE -gt 80 ]; then
echo "⚠️ Ramdisk >80% full"
fi

Integrate with hoody-notifications for alerts.

If your app requires ramdisk:

// In container config or README
{
"name": "video-processor",
"ramdisk": true,
"ramdisk_usage": "Required for frame extraction (temporary storage of 1000+ image files)"
}

Future maintainers know why ramdisk is enabled.


Yes. Dramatically faster:

  • RAM: ~15 GB/s throughput, <1µs latency
  • SSD: ~2 GB/s throughput, ~50-100µs latency
  • 10-50x faster for I/O-intensive workloads

CAPACITY is up to 50% of total host memory (capped lower if the project is bound to a memory-limited subserver):

Terminal window
# Host has 8GB RAM
/ramdisk capacity: up to 4GB max
# Host has 32GB RAM
/ramdisk capacity: up to 16GB max

But actual RAM consumption = only what you store:

Terminal window
df -h /ramdisk
# Filesystem Size Used Avail Use% Mounted on
# tmpfs 4.0G 1.2G 2.8G 30% /ramdisk
# ^^^^ ^^^^ ---- Capacity vs Actual
# Max Used Free

Empty ramdisk shows 4.0G size but uses 0 bytes RAM. RAM allocated on-demand.

Why does data persist through container restart but not host reboot?

Section titled “Why does data persist through container restart but not host reboot?”

Container restart:

  • Container stops → Host keeps RAM allocated → Container starts → Same RAM data

Host reboot:

  • Host powers off → All RAM cleared → Host powers on → Fresh RAM

Physical limitation of RAM - power loss = data loss.

Can I disable ramdisk after creating container?

Section titled “Can I disable ramdisk after creating container?”

Yes:

Terminal window
# Stop container
POST /api/v1/containers/{id}/{operation} # operation=stop
# Disable ramdisk
PATCH /api/v1/containers/{id}
{"ramdisk": false}
# Start container
POST /api/v1/containers/{id}/{operation} # operation=start
# operation enum: start | stop | force-stop | restart | pause | resume
# /ramdisk no longer available (RAM freed)

⚠️ WARNING: Any data in /ramdisk is lost when disabling.

Same as any filesystem:

  • “No space left on device” errors
  • Applications fail to write
  • System may become unstable

Solution:

Terminal window
# Delete old files
rm -rf /ramdisk/old-cache/*
# Or clear everything
rm -rf /ramdisk/*

No. /ramdisk is isolated per container.

Workaround:

Terminal window
# Copy from ramdisk to persistent storage
cp /ramdisk/data.json /hoody/storage/shared/
# Share persistent storage instead
POST /api/v1/containers/{id}/storage/shares {"source_path": "/hoody/storage/shared"}

Or use shared concurrent-write database in /hoody/databases/.


Problem: /ramdisk directory doesn’t exist

Solutions:

  1. Verify ramdisk enabled:

    Terminal window
    GET /api/v1/containers/{id}
    # Check: "ramdisk": true
  2. If false, enable it:

    Terminal window
    POST /api/v1/containers/{id}/{operation} # operation=stop
    PATCH /api/v1/containers/{id} {"ramdisk": true}
    POST /api/v1/containers/{id}/{operation} # operation=start
    # operation enum: start | stop | force-stop | restart | pause | resume
  3. Restart container if status shows true but missing:

    Terminal window
    POST /api/v1/containers/{id}/{operation} # operation=restart

Problem: Container extremely slow, ramdisk operations taking seconds

Likely cause: SWAP usage (ramdisk overcommit)

Debug:

Terminal window
# Check SWAP usage via exec (upload once, then run)
SERVICE="https://{project}-{container}-exec-1.{server}.containers.hoody.icu"
curl -sS -X POST "$SERVICE/hoody/storage/hoody-exec/scripts/default/1/free.sh" \
-H "Authorization: Bearer $PROXY_TOKEN" --data-binary 'free -h'
curl -sS "$SERVICE/free.sh" -H "Authorization: Bearer $PROXY_TOKEN"
# If Swap "used" column >0:
# - Too much ramdisk allocated across containers
# - System paging to disk (extremely slow)

Solutions:

  1. Immediate: Clear ramdisk in other containers

    Terminal window
    rm -rf /ramdisk/*
  2. Long-term: Disable ramdisk on non-critical containers

    Terminal window
    PATCH /api/v1/containers/{id} {"ramdisk": false}
  3. Permanent: Reduce containers or increase host RAM

Problem: Files existed yesterday, now missing

Cause: Host server rebooted

Remember: /ramdisk is cleared on host reboot (not container reboot).

Prevention:

  • Never store critical data ONLY in /ramdisk
  • Always copy important results to persistent storage
  • Document ramdisk as temporary storage in your app

Storage ecosystem:

Performance tuning:

Understanding gained:

  • /ramdisk enabled by default (set ramdisk: false to disable)
  • ✅ RAM consumed on-demand (empty ramdisk = 0 bytes used)
  • ✅ Capacity is up to 50% of total host memory, actual usage varies
  • ✅ Provides RAM-speed storage (10-50x faster than SSD)
  • ✅ Persists through container restarts (unique Hoody feature!)
  • ✅ Cleared on host reboot (RAM = power loss = data loss)
  • ✅ Monitor ACTUAL usage across containers to avoid SWAP

Ultra-fast RAM storage, enabled by default. Consumes RAM on-demand. Survives container restart. Cleared on host reboot.

Monitor actual usage, not capacity. Avoid SWAP. Use for speed, not persistence.