/ramdisk reference
Section titled “/ramdisk reference”Lookup tables for /ramdisk. Every computer field is in the Computers API.
| Path | Who can read and write it | Notes |
|---|---|---|
/ramdisk | This computer only | Your general-purpose scratch space. Computer A’s /ramdisk and computer B’s are separate trees |
/ramdisk/secrets | This computer only, mode 0700 | The designated place for credential material; only the computer’s own root can open it |
/ramdisk/project | Your computers in this project on the same server | Present only when ramdisk_scope is project, which is refused for now |
Capacity is shared even where the files are not: every path draws on the one pool of the server.
ramdisk_scope accepts computer (the default); project is refused for now, so /ramdisk stays private to each computer. Computer creation does not document this field, and a new computer starts at computer; set it afterward with PATCH /api/v1/computers/{id}.
/ramdiskand/ramdisk/secretsare always private to a single computer.- It cannot be shared through storage shares; see share beyond one server.
A computer that already holds project keeps /ramdisk/project, shared with your computers in the same project and on the same server. For such a computer:
- A RAM disk cannot span servers: computers of the same project on different servers get separate, non-shared
/ramdisk/projectdirectories, and they do not see each other’s files. - Narrowing
ramdisk_scopeback tocomputeris rejected while the computer is running; pause or stop it first (update a computer). - To turn ramdisk off, send
ramdisk_scope: computerin the same request asramdisk: false, with the computer stopped or paused.
Fields, flags and calls
Section titled “Fields, flags and calls”| Field, flag or call | What it does |
|---|---|
ramdisk on create | Whether to mount /ramdisk. Enabled by default; set ramdisk: false to disable |
ramdisk on update | ramdisk: false turns it off while the computer runs. Its files remain in the server’s pool and return if you enable it again. Delete the files before disabling ramdisk to free their space; deleting the computer after disabling ramdisk does not guarantee cleanup. A host reboot clears the pool. Omitted, the current value is kept |
ramdisk_scope on update | computer; project is refused for now. See Paths. Not documented on create, where a new computer starts at computer |
POST /api/v1/projects/{id}/computers | Create a computer (ramdisk enabled by default, or set ramdisk: false) |
PATCH /api/v1/computers/{id} | Turn ramdisk on or off with ramdisk, with no stop needed, or set ramdisk_scope. PUT is accepted with identical behavior |
GET /api/v1/computers/{id} | View the saved setting: "ramdisk": true (enabled) or false (disabled). A saved true does not prove the mount; see troubleshooting |
GET /api/v1/computers/{id}/stats | Measured ramdisk usage per scope, reported beside memory, never under disk; see usage stats |
POST /api/v1/computers/{id}/{operation} | Stop, pause or restart the computer, for example before narrowing ramdisk_scope. operation is one of start, stop, force-stop, restart, pause, resume |
POST /api/v1/computers/{id}/snapshots | Snapshots do not capture /ramdisk. Restoring a snapshot does not roll its contents back or guarantee an empty ramdisk; existing RAM-backed files can remain until explicitly deleted or the host reboots |
| Hoody Files | Access /ramdisk via HTTP |
| Hoody Terminal | Shell access to ramdisk |
The create CLI exposes --ramdisk / --no-ramdisk. For an existing computer, hoody computers update <id> exposes --ramdisk, --no-ramdisk and --ramdisk-scope <computer|project>; project is refused for now. The steps with all four request forms are in turn /ramdisk on or off.
Capacity and limits
Section titled “Capacity and limits”| Item | Value |
|---|---|
| Pool | One tmpfs pool per server, which every computer of yours on that server draws from. There is no per-computer ramdisk quota to plan |
| Pool size | 512 MiB by default, a per-server value you cannot set yourself |
| Hard ceiling | 50% of that server’s memory. The configured size is clamped to it, so a small server’s pool is smaller than 512 MiB |
| Reserved per computer | Nothing; first come, first served |
| Empty ramdisk | File contents consume RAM on demand, while filesystem metadata also uses memory. df -h /ramdisk shows the shared pool’s capacity, not reserved RAM. Deleting a file may leave its data allocated while a process still holds it open |
| Size controls | No size field on the computer API, no Hub control, and no per-computer override; the size belongs to the server your computer sits on |
| Memory, not disk | Charged to your server’s memory: counts against RAM and appears in no disk total |
| Swap | Mounted noswap: the kernel cannot page these pages out, and there is no swap fallback. Everything you store is RAM your own processes can no longer use, which is why the pool is capped conservatively |
| Pool full | Writes fail immediately with ENOSPC; nothing silently degrades to disk. Computers keep running; only the write fails. Deleting files in any computer on that server frees the space again. The pool also has an inode limit, normally 1,048,576: if writes fail while byte capacity remains, run df -i /ramdisk. Delete finished files to free inodes; emptying a file without removing it frees none |
| No pool | In rare placements without a dedicated RAM pool, a computer gets no /ramdisk at all: there is no pool to attach |
# Example for a server whose reported pool ceiling is 512 MiB.
Computer A writes 500 MiB to /ramdisk → ~12 MiB left for everyone elseComputer B tries to write 50 MiB → "No space left on device"Plan capacity
Section titled “Plan capacity”/ramdisk is for the hot, small part of a workload: a package cache, one dataset chunk, a batch of frames. A full node_modules, a large model, or a multi-gigabyte video will not fit, and filling the pool starves your siblings on that server. The figures here and in the recipes assume a server whose reported pool ceiling is 512 MiB.
# Example for a server whose reported pool ceiling is 512 MiB.
# Scenario A: One build computer (comfortable)# package cache in /ramdisk: ~200 MiB, cleared after each build
# Scenario B: Four small services (comfortable)# each keeps ~50 MiB of hot cache = ~200 MiB total
# Scenario C: Tight# two computers each holding 240 MiB leave about 32 MiB for the others;# a larger write fails with no space leftUse df -h /ramdisk to see shared-pool capacity, usage and available space. The stats endpoint reports the pool ceiling and per-scope usage; it does not report shared-pool free space. sudo du -sh /ramdisk measures the visible tree, including shared project files when /ramdisk/project is mounted. For this computer’s private usage, read ramdisk.usage.private and ramdisk.usage.secrets from the stats endpoint, and keep usage.project separate.
# Example for a server whose reported pool ceiling is 512 MiB.df -h /ramdisk# Filesystem Size Used Avail Use% Mounted on# tmpfs 512M 120M 392M 24% /ramdisk# ^^^^ ^^^^ ---- pool capacity vs pool usage# Pool Used by all your computers on this serverUsage stats
Section titled “Usage stats”The ramdisk field of GET /api/v1/computers/{id}/stats sits beside memory, because it is memory, never disk:
"ramdisk": { "scope": "computer", "shared_pool_maximum": 536870912, # the shared ceiling for this server; null if unconfirmed "capacity_reserved": false, # always false: nothing is held for you "usage": { "private": 4096, "secrets": 0 }}| Field | Meaning |
|---|---|
scope | computer or project |
shared_pool_maximum | The whole pool in bytes, or null when the server reports no confirmed ceiling. Co-tenant computers of yours also draw from it. It is not your quota, so do not turn it into a percentage |
capacity_reserved | Always false: nothing is held for you |
usage | Per-scope measurements, or null when no measurement was obtained. The project stats endpoint (GET /api/v1/projects/{id}/stats) does not measure it, so usage is null there: that means “open the computer to measure”, not “empty”. Single-computer stats can also return null when measurement is unavailable. Within a measured object, a null member means that scope could not be measured; 0 is measured and empty |
usage.project | With scope: project, the shared directory’s size. It is shared with sibling computers, so summing it across sibling computers counts the same bytes once for each |
No ramdisk field | Ramdisk is off on this computer, or the placement has no RAM pool to attach |
From inside the computer, run sudo du -sh /ramdisk to measure the visible tree, including secrets and any shared project files. Run df -h /ramdisk to inspect shared-pool capacity and available space.
sudo du -sh /ramdisk # the tree this computer sees, shared project files includeddf -h /ramdisk # the shared pool: total size and how much is leftPerformance
Section titled “Performance”Typical hardware figures, not measured on Hoody:
| Measure | /ramdisk | SSD |
|---|---|---|
| Read | ~10-20 GB/s | ~0.5-3 GB/s |
| Write | ~10-20 GB/s | ~0.5-2 GB/s |
| Latency | <1µs | ~50-100µs |
By these figures, RAM is about 3-40x faster than SSD for throughput. Workloads made of thousands of small file operations benefit most, and temporary files here cause no disk wear.
Writing a 256 MiB file (a 1 GB file does not fit the 512 MiB pool):
| Storage | Write speed | Time |
|---|---|---|
/ramdisk | ~15 GB/s | ~0.02s |
| SSD | ~2 GB/s | ~0.13s |
| HDD | ~200 MB/s | ~1.3s |
RAM is about 7.5x faster than SSD and 75x faster than HDD.
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µs |
| SSD | ~50-100µs |
| HDD | ~5-10ms |
RAM latency is under a microsecond.
When to turn it off
Section titled “When to turn it off”Ramdisk is enabled automatically; opt out at creation with ramdisk: false. Later, in the Hub, open the computer, select Overview, find Features, and turn RAM disk off. Confirm with Turn off RAM disk. A computer with ramdisk_scope: project needs the API instead, as the guide shows. Delete unwanted scratch files first to free their space. An enabled ramdisk that holds few files uses little RAM, so disable it only when you are certain the computer will not benefit.
| Disable it for | Keep it (the default) for |
|---|---|
| Simple APIs (CRUD operations, no heavy I/O) | Build servers (compilation, npm install) |
| Static file servers | Cache servers (Redis-like workloads) |
| Long-running daemons with minimal disk access | Media processing (video/image transcoding) |
| Computers that would only compete for a pool their siblings need | Data processing (ETL, analytics) |
Recipes
Section titled “Recipes”These examples require root access. In the default terminal, start a root shell with sudo -i and set any required variables in that shell. For a program running as another user, grant it access to a dedicated scratch directory and permission to traverse its parent; keep /ramdisk/secrets root-only.
Build caches
Section titled “Build caches”# Put the cache in ramdisk, not node_modules, which rarely fits in 512 MiBexport NPM_CONFIG_CACHE=/ramdisk/npm-cache
cd /home/user/projectnpm install # Tarball cache reads/writes stay in RAM
# Then copy final artifacts to persistent storagecp -r dist /hoody/storage/production/Cache-heavy installs get much faster, as long as what you put in /ramdisk fits the pool.
# Build in ramdiskexport GOCACHE=/ramdisk/go-cacheexport GOTMPDIR=/ramdisk/go-tmpmkdir -p "$GOTMPDIR"
go build -o /ramdisk/app .
# Test from ramdisk (fast startup)/ramdisk/app
# Copy final binary to persistent storagecp /ramdisk/app /hoody/storage/bin/Compilation is much faster with a ramdisk cache. Watch du -sh /ramdisk, since a large GOCACHE will exhaust the 512 MiB pool.
# Keep pip's download and wheel cache in ramdisk; packages install into the active Python environmentpip install --cache-dir=/ramdisk/pip-cache -r requirements.txt
# Or set environment variableexport PIP_CACHE_DIR=/ramdisk/pip-cachepip install flask numpy pandasDatabase temp space
Section titled “Database temp space”Keep the temporary b-trees of a heavy one-off query out of storage:
mkdir -p /ramdisk/tmpexport SQLITE_TMPDIR=/ramdisk/tmpFor Postgres, the equivalent is a temp tablespace pointed at a directory under /ramdisk.
Application cache
Section titled “Application cache”# Application cache in RAMmkdir -p /ramdisk/app-cache
# Store frequently accessed data (a small database; the pool is 512 MiB).# Copy a consistent snapshot of the database: a plain cp can miss changes# still in the WAL (SQLite backups: /kit/sqlite/reference/).# The destination must not exist.sqlite3 /hoody/databases/users.db "VACUUM INTO '/ramdisk/app-cache/users.db'"sqlite3 /ramdisk/app-cache/users.db "SELECT ..." # Served from RAM
# Session storagemkdir -p /ramdisk/sessionsecho '{"user": 1, "token": "abc"}' > /ramdisk/sessions/user-1.jsonCache hits return in <1ms.
Temporary file processing
Section titled “Temporary file processing”Process files without disk I/O, keeping each chunk well under the 512 MiB pool:
# Download a dataset chunk to ramdiskcurl "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 the result, then free the pool immediatelycurl -X POST "https://api.example.com/results" \ -d "@/ramdisk/result.txt"rm -f /ramdisk/dataset.csv /ramdisk/result.txtVideo frames
Section titled “Video frames”Work in batches. A full frame dump will overflow a 512 MiB pool long before the video ends:
# Extract a window of frames to ramdisk (burst I/O)mkdir -p /ramdisk/framesffmpeg -ss 00:00:10 -t 5 -i video.mp4 /ramdisk/frames/frame_%04d.png
# Process frames (parallel reads)for frame in /ramdisk/frames/*.png; do convert $frame -resize 50% $framedone
# Merge back to videoffmpeg -i /ramdisk/frames/frame_%04d.png output.mp4Cache with fallback
Section titled “Cache with fallback”Try ramdisk first, fall back to disk:
from pathlib import Pathimport json
def get_cached_data(key): ram = Path('/ramdisk/cache') / f'{key}.json' disk = Path('/hoody/storage/cache') / f'{key}.json'
try: return json.loads(ram.read_text()) except (OSError, ValueError): pass
try: data = json.loads(disk.read_text()) except FileNotFoundError: return None
try: ram.parent.mkdir(parents=True, exist_ok=True) ram.write_text(json.dumps(data)) except OSError: pass # Persistent data remains usable if RAM caching fails.
return dataBuild then persist
Section titled “Build then persist”Build in ramdisk, save the final output to disk:
#!/bin/bashset -euo pipefail# Build script; keep the intermediate tree inside the 512 MiB pool
# Compile in ramdiskcmake -S /home/user/project -B /ramdisk/buildmake -C /ramdisk/build -j"$(nproc)"
# Test binary/ramdisk/build/test-suite
# Copy only the final binary to persistent storagesudo mkdir -p /hoody/storage/productionsudo chown user:user /hoody/storage/productioncp /ramdisk/build/binary /hoody/storage/production/app-v1.2.3
# Free the pool after the copy succeedsrm -rf /ramdisk/buildSession files
Section titled “Session files”Sessions in RAM get fast reads and writes. Your application must check expiration and delete expired session files. expiresAt is a Unix timestamp in milliseconds:
// Sessions in ramdisk (fast read/write)fs.mkdirSync('/ramdisk/sessions', { recursive: true });const sessionPath = `/ramdisk/sessions/${sessionId}.json`;
// Write sessionfs.writeFileSync(sessionPath, JSON.stringify({userId, token, expiresAt}));
// Read sessionconst session = JSON.parse(fs.readFileSync(sessionPath));if (Date.now() >= session.expiresAt) { fs.unlinkSync(sessionPath); throw new Error('Session expired'); }
// A host reboot clears the session files.Clean up after a build
Section titled “Clean up after a build”The pool is shared and its ceiling is fixed per server (512 MiB by default, clamped to 50% of server memory), so clean up the moment a task finishes:
#!/bin/bash# Build script with cleanup
# Build in ramdiskcp -r /home/user/project /ramdisk/buildnpm install --prefix /ramdisk/buildnpm run build --prefix /ramdisk/build
# Copy final bundlecp /ramdisk/build/dist/*.js /hoody/storage/production/
# Clean up immediately (free RAM)rm -rf /ramdisk/build
# Or clean on exittrap 'rm -rf /ramdisk/build' EXITTemporary data only
Section titled “Temporary data only”Never rely on /ramdisk for critical data. If data matters after a host reboot, do not put it only in /ramdisk:
# Good: temporary processingwget https://example.com/dataset.zip -O /ramdisk/dataset.zipunzip /ramdisk/dataset.zip -d /ramdisk/processing/# Process and save results to /hoody/storage
# Bad: long-term storagecp important-data.db /ramdisk/ # Lost on host rebootWatch the pool
Section titled “Watch the pool”# The shared pool: how full it is for everyone on this serverdf -h /ramdisk
# Alert if the pool is >80% fullUSAGE=$(df /ramdisk | awk 'NR==2 {print $5}' | sed 's/%//')if [ $USAGE -gt 80 ]; then echo "WARNING: shared ramdisk pool >80% full"fi
# What this computer sees, shared project files includeddu -sh /ramdiskSend the warning through Hoody Notifications to get an alert.
Note the dependency
Section titled “Note the dependency”If your app requires ramdisk, say so in your README, so future maintainers know why ramdisk is enabled and what it costs the pool:
## Runtime requirements
- `ramdisk: true` (the default). Frame extraction writes ~200 MiB of PNGs to `/ramdisk/frames` in batches, then deletes them. Remember the pool is shared with our other computers on this server; check its real ceiling with `df -h /ramdisk` (512 MiB by default).Share beyond one server
Section titled “Share beyond one server”To share data with another computer, copy it to persistent storage first:
# Copy from ramdisk to persistent storagesudo mkdir -p /hoody/storage/shared && sudo chown user:user /hoody/storage/sharedcp /ramdisk/data.json /hoody/storage/shared/Cross-server storage sharing is a pilot feature and is off by default. It is unavailable if either computer is on a free-tier server or paid subserver. When it is available, create a storage share: POST /api/v1/computers/{id}/storage/shares with source_path /hoody/storage/shared, your target_computer_id and mode readonly. Check status_message and the target mount before relying on it.
Or transfer the data through Hoody Files, or keep it in a SQLite database and let the other computer read it over the hoody-sqlite HTTP API.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | What to do |
|---|---|---|
The /ramdisk directory does not exist | Ramdisk may be disabled: verify that GET /api/v1/computers/{id} shows "ramdisk": true | If false, enable it: send {"ramdisk": true} to PATCH /api/v1/computers/{id}; no stop is needed (steps). If the status shows true but the directory is missing: a computer running directly on a physical server has no pool (see the next row); otherwise restart the computer (operation=restart) |
No /ramdisk, and GET /api/v1/computers/{id}/stats omits the ramdisk field entirely | Ramdisk is off, or in rare placements a computer has no RAM pool to attach and therefore no /ramdisk | Check "ramdisk" on GET /api/v1/computers/{id} first; if it is true, check whether the placement has a pool |
/ramdisk/project does not exist | It exists only when ramdisk_scope is project, which is refused for now | Share files through persistent storage instead: share beyond one server |
/ramdisk/project missing although the computer already holds scope: project | The expected project mount is unavailable | Computers of the same project on different servers each get their own /ramdisk/project and do not see each other’s files, but each should still have one. If the mount is absent, contact support |
”No space left on device”: writes to /ramdisk fail even though the computer has free memory | The shared pool is full, often filled by one of your other computers on that server | Debug with df -h /ramdisk (pool Size, Used and Avail across all your computers here) and sudo du -sh /ramdisk (the tree this computer sees, shared project files included). Immediate: delete finished work in this computer or any sibling on that server (sudo rm -rf /ramdisk/build /ramdisk/old-cache, or sudo find /ramdisk -mindepth 1 -maxdepth 1 ! -name secrets ! -name project -exec rm -rf -- {} + to clear this computer’s scratch files, hidden ones included). Long-term: on computers that never use it, delete their /ramdisk files, then disable ramdisk with PATCH /api/v1/computers/{id} {"ramdisk": false}. Structural: move anything bigger than a working set to computer storage; the pool cannot be enlarged |
| Files existed yesterday, now missing | The host server rebooted and the pool was recreated empty at boot; or, with ramdisk_scope: project, one of your sibling computers deleted them from the shared /ramdisk/project | /ramdisk is cleared on host reboot, not computer reboot. Never store critical data only in /ramdisk, always copy important results to persistent storage, and document ramdisk as temporary storage in your app |