# /ramdisk reference **Page:** foundation/storage/ramdisk/reference [Download Raw Markdown](./foundation/storage/ramdisk/reference.md) --- # /ramdisk reference Lookup tables for [/ramdisk](/foundation/storage/ramdisk/). Every computer field is in the [Computers API](/api/computers/). ## Paths | 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}`. - `/ramdisk` and `/ramdisk/secrets` are always private to a single computer. - It cannot be shared through storage shares; see [share beyond one server](#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](/foundation/computers/create-edit-delete/#update-a-computer)). - To turn ramdisk off, send `ramdisk_scope: computer` in the same request as `ramdisk: false`, with the computer stopped or paused. ## 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](#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](#troubleshooting) | | `GET /api/v1/computers/{id}/stats` | Measured ramdisk usage per scope, reported beside `memory`, never under `disk`; see [usage stats](#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](/api/files/) | Access `/ramdisk` via HTTP | | [Hoody Terminal](/kit/terminals/) | Shell access to ramdisk | The create CLI exposes `--ramdisk` / `--no-ramdisk`. For an existing computer, `hoody computers update ` exposes `--ramdisk`, `--no-ramdisk` and `--ramdisk-scope `; `project` is refused for now. The steps with all four request forms are in [turn /ramdisk on or off](/foundation/storage/ramdisk/#turn-ramdisk-on-or-off). ## 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 | ```text # 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" ``` ## Plan capacity Keep steady-state usage well under the actual per-server shared-pool ceiling reported by `df -h /ramdisk` or the stats endpoint (512 MiB by default and clamped to 50% of server memory), across all your computers on that server, and delete aggressively when a task finishes. A computer that fills the pool and then allocates heavily is the one most likely to be killed for it. `/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](#recipes) assume a server whose reported pool ceiling is 512 MiB. ```bash # 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. `df -h /ramdisk` reports the pool, not your computer. `Size` is the actual per-server shared-pool ceiling (512 MiB by default, clamped to 50% of server memory) and `Used` counts everything your computers on that server have written. Use `sudo du -sh /ramdisk` for the tree this computer sees (shared project files included), or the stats endpoint for a per-scope breakdown. ```bash # 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 ``` ## Usage stats The `ramdisk` field of `GET /api/v1/computers/{id}/stats` sits beside `memory`, because it is memory, never disk: ```text "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. ```bash 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 ``` ## 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 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](/foundation/storage/ramdisk/#turn-ramdisk-on-or-off) 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 Budget each recipe against the actual pool ceiling reported by `df -h /ramdisk` or the stats endpoint: 512 MiB by default, clamped to 50% of server memory, and shared. Stage large data on [computer storage](/foundation/storage/) and keep only the working set in RAM. 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 ```bash # 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. ```bash # Build in ramdisk export GOCACHE=/ramdisk/go-cache export GOTMPDIR=/ramdisk/go-tmp mkdir -p "$GOTMPDIR" go build -o /ramdisk/app . # Test from ramdisk (fast startup) /ramdisk/app # Copy final binary to persistent storage cp /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. ```bash # Keep pip's download and wheel cache in ramdisk; packages install into the active Python environment 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 ``` ### Database temp space Keep the temporary b-trees of a heavy one-off query out of storage: ```bash mkdir -p /ramdisk/tmp export SQLITE_TMPDIR=/ramdisk/tmp ``` For Postgres, the equivalent is a temp tablespace pointed at a directory under `/ramdisk`. ### Application cache ```bash # 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`. ### Temporary file processing Process files without disk I/O, keeping each chunk well under the 512 MiB pool: ```bash # 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 ``` ### Video frames Work in batches. A full frame dump will overflow a 512 MiB pool long before the video ends: ```bash # 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 ``` ### Cache with fallback Try ramdisk first, fall back to disk: ```python 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 then persist Build in ramdisk, save the final output to disk: ```bash #!/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 ``` ### 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: ```javascript // 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. ``` ### 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: ```bash #!/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 ``` ### Temporary data only Never rely on `/ramdisk` for critical data. If data matters after a host reboot, do not put it only in `/ramdisk`: ```bash # 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 ``` ### Watch the pool ```bash # 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](/kit/notifications/) to get an alert. ### 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: ```markdown ## 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 To share data with another computer, copy it to persistent storage first: ```bash # 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](/foundation/storage/sharing-files/#1-to-1-computer-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](/kit/files/), or keep it in a SQLite database and let the other computer read it over the [hoody-sqlite](/kit/sqlite/) HTTP API. ## 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](/foundation/storage/ramdisk/#turn-ramdisk-on-or-off)). 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](#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](/foundation/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 |