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.
# 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
import { HoodyClient } from ' @hoody-ai/hoody-sdk ' ;
const client = new HoodyClient ( { baseURL: ' https://api.hoody.icu ' , token: TOKEN } );
// ramdisk enabled by default — no flag needed
const container = await client . api . containers . create (
{ name: ' my-container ' , server_id: SERVER_ID , hoody_kit: true }
// Explicitly disable ramdisk
const noRamdisk = await client . api . containers . create (
{ name: ' no-ramdisk ' , server_id: SERVER_ID , hoody_kit: true , ramdisk: false }
# Create container — ramdisk enabled by default
curl -X POST " https://api.hoody.icu/api/v1/projects/ $PROJECT_ID /containers " \
-H " Authorization: Bearer $TOKEN " \
-H " Content-Type: application/json " \
-d ' {"name": "my-container", "server_id": " ' $SERVER_ID ' ", "hoody_kit": true} '
# Create container with ramdisk explicitly disabled
curl -X POST " https://api.hoody.icu/api/v1/projects/ $PROJECT_ID /containers " \
-H " Authorization: Bearer $TOKEN " \
-H " Content-Type: application/json " \
-d ' {"name": "no-ramdisk", "server_id": " ' $SERVER_ID ' ", "hoody_kit": true, "ramdisk": false} '
Click "Run" to execute the request
/ramdisk is available immediately but consuming ZERO RAM (empty = no allocation).
Click "Run" to execute the request
/ramdisk will NOT be available.
POST /api/v1/containers/{id}/{operation} # operation=stop
Authorization: Bearer $HOODY_TOKEN
PATCH /api/v1/containers/{id}
Authorization: Bearer $HOODY_TOKEN
Content-Type: application/json
# Start container - /ramdisk no longer available
POST /api/v1/containers/{id}/{operation} # operation=start
Authorization: Bearer $HOODY_TOKEN
# operation enum: start | stop | force-stop | restart | pause | resume
Check ramdisk status:
GET /api/v1/containers/{id}
# Response: "ramdisk": true (enabled) or false (disabled)
Access like any directory:
# In container (via terminal or SSH)
# Write files (ultra-fast)
echo " data " > /ramdisk/cache/session-abc.json
# Read files (ultra-fast)
cat /ramdisk/cache/session-abc.json
Files in /ramdisk are stored in RAM - no disk I/O.
# Use ramdisk for node_modules and build output
export NPM_CONFIG_CACHE = / ramdisk / npm-cache
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.
export GOCACHE = / ramdisk / go-cache
export GOTMPDIR = / ramdisk / go-tmp
go build -o /ramdisk/app .
# Test from ramdisk (fast startup)
# Copy final binary to persistent storage
cp /ramdisk/app /hoody/storage/bin/
Compilation 3-5x faster with ramdisk cache.
# Install packages to ramdisk
pip install --cache-dir=/ramdisk/pip-cache -r requirements.txt
# Or set environment variable
export PIP_CACHE_DIR = / ramdisk / pip-cache
pip install flask numpy pandas
# 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
echo ' {"user": 1, "token": "abc"} ' > /ramdisk/sessions/user-1.json
Response time: <1ms for cache hits.
Process files without disk I/O:
# 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.
# 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
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):
- /ramdisk CAPACITY: up to 4GB max
- Actual RAM used: Only what you store
- Empty ramdisk: 0 bytes RAM consumed
- /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:
# 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.
Caution
Rule of thumb: Total ramdisk ACTUAL USAGE (not capacity) should be ≤50% of host RAM.
Monitor how much data you’re actually storing in ramdisks, not maximum capacity.
Example planning:
# 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)
# 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:
# 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 " \
# 2. Run it — path-routed invocation returns the script's stdout
curl -sS " $SERVICE /free.sh " \
-H " Authorization: Bearer $PROXY_TOKEN "
# 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:
Disable ramdisk on less critical containers
Reduce ramdisk usage (delete unused files)
Add more RAM to host server
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 .
POST /api/v1/containers/{id}/{operation} # operation=stop
POST /api/v1/containers/{id}/{operation} # operation=start
# operation enum: start | stop | force-stop | restart | pause | resume
✅ PERSISTS
/ramdisk contents maintained
Same as restart behavior
When physical server reboots:
❌ CLEARED
All /ramdisk contents deleted
Directory structure wiped
Starts empty after host reboot
This is RAM storage - host reboot = power loss = data loss.
POST /api/v1/containers/{id}/snapshots
❌ NOT captured
Snapshots save disk state only
/ramdisk is RAM, not disk
Restore = empty /ramdisk
For backup: Copy critical ramdisk data to persistent storage before snapshot.
Try ramdisk first, fall back to disk:
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 )
if os.path. exists ( disk_path ):
data = read_file ( disk_path )
# Promote to ramdisk for next access
write_file ( ramdisk_path , data )
Build in ramdisk, save final output to disk:
# Compile in ramdisk (fast)
# Test binary (fast startup from RAM)
# 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 ` ;
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:
Storage Write Speed Time /ramdisk~15 GB/s ~0.07s SSD ~2 GB/s ~0.5s HDD ~200 MB/s ~5s
RAM is 7-70x faster.
10,000 small file operations:
Storage Operations/sec Time /ramdisk~50,000 ops/s ~0.2s SSD ~5,000 ops/s ~2s HDD ~100 ops/s ~100s
RAM is 10-500x faster for random I/O.
Time to access data:
Storage Latency /ramdisk<1µsSSD ~50-100µs HDD ~5-10ms
RAM has near-zero latency.
CRITICAL: Multiple containers with ramdisk can exceed host RAM.
Example scenario:
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)
# 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:
# 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:
# 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 "
# total USED ← If >0, you're using SWAP
# If SWAP used > 1GB: Reduce ramdisk usage
Solutions if SWAP is high:
Disable ramdisk on some containers
Clear unnecessary ramdisk data: rm -rf /ramdisk/*
Reduce number of containers with ramdisk enabled
Upgrade host server RAM
Ramdisk is enabled automatically, but you can opt out at creation time:
# 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:
# ✅ 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:
# Build script with cleanup
npm install --prefix /ramdisk/build
npm run build --prefix /ramdisk/build
cp /ramdisk/build/dist/ * .js /hoody/storage/production/
# Clean up immediately (free RAM)
trap ' rm -rf /ramdisk/build ' EXIT
# Check ramdisk usage regularly
USAGE = $( df /ramdisk | awk ' NR==2 {print $5} ' | sed ' s/%// ' )
if [ $USAGE -gt 80 ]; then
echo " ⚠️ Ramdisk >80% full "
Integrate with hoody-notifications for alerts.
If your app requires ramdisk:
// In container config or README
"name" : " video-processor " ,
"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):
/ramdisk capacity: up to 4GB max
/ramdisk capacity: up to 16GB max
But actual RAM consumption = only what you store:
# Filesystem Size Used Avail Use% Mounted on
# tmpfs 4.0G 1.2G 2.8G 30% /ramdisk
# ^^^^ ^^^^ ---- Capacity vs Actual
Empty ramdisk shows 4.0G size but uses 0 bytes RAM. RAM allocated on-demand.
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.
Yes:
POST /api/v1/containers/{id}/{operation} # operation=stop
PATCH /api/v1/containers/{id}
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:
rm -rf /ramdisk/old-cache/ *
No. /ramdisk is isolated per container .
Workaround:
# 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:
Verify ramdisk enabled:
GET /api/v1/containers/{id}
If false, enable it:
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
Restart container if status shows true but missing:
POST /api/v1/containers/{id}/{operation} # operation=restart
Problem: Container extremely slow, ramdisk operations taking seconds
Likely cause: SWAP usage (ramdisk overcommit)
Debug:
# 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:
Immediate: Clear ramdisk in other containers
Long-term: Disable ramdisk on non-critical containers
PATCH /api/v1/containers/{id} { " ramdisk " : false }
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.