Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

Lookup tables for /ramdisk. Every computer field is in the Computers API.

PathWho can read and write itNotes
/ramdiskThis computer onlyYour general-purpose scratch space. Computer A’s /ramdisk and computer B’s are separate trees
/ramdisk/secretsThis computer only, mode 0700The designated place for credential material; only the computer’s own root can open it
/ramdisk/projectYour computers in this project on the same serverPresent 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}.

  • /ramdisk and /ramdisk/secrets are 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/project directories, and they do not see each other’s files.
  • Narrowing ramdisk_scope back to computer is rejected while the computer is running; pause or stop it first (update a computer).
  • To turn ramdisk off, send ramdisk_scope: computer in the same request as ramdisk: false, with the computer stopped or paused.
Field, flag or callWhat it does
ramdisk on createWhether to mount /ramdisk. Enabled by default; set ramdisk: false to disable
ramdisk on updateramdisk: 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 updatecomputer; project is refused for now. See Paths. Not documented on create, where a new computer starts at computer
POST /api/v1/projects/{id}/computersCreate 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}/statsMeasured 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}/snapshotsSnapshots 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 FilesAccess /ramdisk via HTTP
Hoody TerminalShell 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.

ItemValue
PoolOne tmpfs pool per server, which every computer of yours on that server draws from. There is no per-computer ramdisk quota to plan
Pool size512 MiB by default, a per-server value you cannot set yourself
Hard ceiling50% 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 computerNothing; first come, first served
Empty ramdiskFile 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 controlsNo 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 diskCharged to your server’s memory: counts against RAM and appears in no disk total
SwapMounted 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 fullWrites 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 poolIn 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 else
Computer B tries to write 50 MiB → "No space left on device"

/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.

Terminal window
# 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 left

Use 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.

Terminal window
# 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 server

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 }
}
FieldMeaning
scopecomputer or project
shared_pool_maximumThe 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_reservedAlways false: nothing is held for you
usagePer-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.projectWith 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 fieldRamdisk 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.

Terminal window
sudo du -sh /ramdisk # the tree this computer sees, shared project files included
df -h /ramdisk # the shared pool: total size and how much is left

Typical hardware figures, not measured on Hoody:

Measure/ramdiskSSD
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):

StorageWrite speedTime
/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.

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 forKeep it (the default) for
Simple APIs (CRUD operations, no heavy I/O)Build servers (compilation, npm install)
Static file serversCache servers (Redis-like workloads)
Long-running daemons with minimal disk accessMedia processing (video/image transcoding)
Computers that would only compete for a pool their siblings needData processing (ETL, analytics)

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.

Terminal window
# Put the cache in ramdisk, not node_modules, which rarely fits in 512 MiB
export NPM_CONFIG_CACHE=/ramdisk/npm-cache
cd /home/user/project
npm install # Tarball cache reads/writes stay in RAM
# Then copy final artifacts to persistent storage
cp -r dist /hoody/storage/production/

Cache-heavy installs get much faster, as long as what you put in /ramdisk fits the pool.

Keep the temporary b-trees of a heavy one-off query out of storage:

Terminal window
mkdir -p /ramdisk/tmp
export SQLITE_TMPDIR=/ramdisk/tmp

For Postgres, the equivalent is a temp tablespace pointed at a directory under /ramdisk.

Terminal window
# Application cache in RAM
mkdir -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 storage
mkdir -p /ramdisk/sessions
echo '{"user": 1, "token": "abc"}' > /ramdisk/sessions/user-1.json

Cache hits return in <1ms.

Process files without disk I/O, keeping each chunk well under the 512 MiB pool:

Terminal window
# Download a dataset chunk 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 the result, then free the pool immediately
curl -X POST "https://api.example.com/results" \
-d "@/ramdisk/result.txt"
rm -f /ramdisk/dataset.csv /ramdisk/result.txt

Work in batches. A full frame dump will overflow a 512 MiB pool long before the video ends:

Terminal window
# Extract a window of frames to ramdisk (burst I/O)
mkdir -p /ramdisk/frames
ffmpeg -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% $frame
done
# Merge back to video
ffmpeg -i /ramdisk/frames/frame_%04d.png output.mp4

Try ramdisk first, fall back to disk:

from pathlib import Path
import 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 data

Build in ramdisk, save the final output to disk:

#!/bin/bash
set -euo pipefail
# Build script; keep the intermediate tree inside the 512 MiB pool
# Compile in ramdisk
cmake -S /home/user/project -B /ramdisk/build
make -C /ramdisk/build -j"$(nproc)"
# Test binary
/ramdisk/build/test-suite
# Copy only the final binary to persistent storage
sudo mkdir -p /hoody/storage/production
sudo chown user:user /hoody/storage/production
cp /ramdisk/build/binary /hoody/storage/production/app-v1.2.3
# Free the pool after the copy succeeds
rm -rf /ramdisk/build

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 session
fs.writeFileSync(sessionPath, JSON.stringify({userId, token, expiresAt}));
// Read session
const 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.

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 ramdisk
cp -r /home/user/project /ramdisk/build
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

Never rely on /ramdisk for critical data. If data matters after a host reboot, do not put it only in /ramdisk:

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
Terminal window
# The shared pool: how full it is for everyone on this server
df -h /ramdisk
# Alert if the pool is >80% full
USAGE=$(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 included
du -sh /ramdisk

Send the warning through Hoody Notifications to get an alert.

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).

To share data with another computer, copy it to persistent storage first:

Terminal window
# Copy from ramdisk to persistent storage
sudo mkdir -p /hoody/storage/shared && sudo chown user:user /hoody/storage/shared
cp /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.

SymptomCauseWhat to do
The /ramdisk directory does not existRamdisk may be disabled: verify that GET /api/v1/computers/{id} shows "ramdisk": trueIf 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 entirelyRamdisk is off, or in rare placements a computer has no RAM pool to attach and therefore no /ramdiskCheck "ramdisk" on GET /api/v1/computers/{id} first; if it is true, check whether the placement has a pool
/ramdisk/project does not existIt exists only when ramdisk_scope is project, which is refused for nowShare files through persistent storage instead: share beyond one server
/ramdisk/project missing although the computer already holds scope: projectThe expected project mount is unavailableComputers 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 memoryThe shared pool is full, often filled by one of your other computers on that serverDebug 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 missingThe 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