Container Storage

Every container gets a full filesystem when it is created. That filesystem persists across restarts, snapshots, and copy operations.

---

API Endpoints Summary

Container management:

• POST /api/v1/projects/{id}/containers - Create container (storage allocated automatically)
• GET /api/v1/containers/{id} - View container details
• Storage Shares API - Share directories between containers

File access:

• Hoody Files API - HTTP-based filesystem access
• Mount Locally - SFTP (Hoody API SSH proxy) / WebDAV (hoody-files) for local mounting

---

Automatic allocation

Storage is not adjustable at the container level yet. The system allocates it when you create the container, and no API parameter sets a storage size per container.

Note

Per-container storage allocation is planned but not available yet. Storage is managed at the host and server level.

Each container starts with:

• Full Linux filesystem (root directory /)
• Persistent across container restarts
• Survives snapshots and restores
• Maintained during copy operations
• Standard Linux filesystem with full POSIX support

---

The /hoody/storage directory

When you create a container with hoody_kit: true, Hoody Kit services that keep state on disk use /hoody/storage as their data directory. Exact layout is service-dependent; a typical tree looks like:

/hoody/storage/
├── hoody-terminal/        # terminal session data, screenshots
├── hoody-display/         # display configs and screenshots
├── hoody-files/           # hoody-files backend configurations
├── hoody-exec/            # exec scripts and cache
├── hoody-sqlite/          # sqlite database metadata
├── hoody-browser/         # browser profiles, chrome, cache
├── hoody-code/            # hoody-code workspace settings
├── hoody-curl/            # hoody-curl job storage
├── hoody-run/             # hoody-run app data
├── hoody-agent/           # agent service state
├── hoody-daemon/          # hoody-daemon configs
├── hoody-notifications/   # hoody-notifications data
├── hoody-tunnel/          # hoody-tunnel configs
├── logs/                  # aggregated service logs
└── ...                    # plus any service-specific subdirectories

Stateless services (pipe, ssh, dynamic http/https ports) don’t create a dedicated directory here. hoody-pipe, for instance, is a pure streaming relay with no on-disk state.

You don’t create or configure /hoody/storage. Creating a container with Hoody Kit establishes it.

That convention has practical consequences:

• All service data sits in one predictable location.
• Backups are a copy of one directory, or an instant ZIP download from hoody-files (folder-as-zip works on both the WebDAV-style root path and the /api/v1/files REST surface via ?zip).
• Service state is simple to inspect.
• The layout is the same in every container.

---

Storage architecture

Container filesystem

Container Root (/)
├── /home/              # User directories (writable)
├── /hoody/
│   ├── /hoody/storage/     # Hoody Kit service data (yours)
│   ├── /hoody/databases/   # SQLite concurrent-write mount (yours)
│   ├── /hoody/shares/      # Mounted shared storage (if any)
│   ├── /hoody/mounts/      # Remote backends mounted by hoody-files
│   ├── /hoody/plugins/     # Kit binaries (platform-managed)
│   └── /hoody/secrets/     # Service credentials (platform-managed)
├── /ramdisk/           # RAM-backed storage (if enabled)
├── /tmp/               # Temporary files (cleared on restart)
└── ... (standard Linux filesystem)

Platform-managed paths

/hoody/plugins and /hoody/secrets belong to the Kit itself: the service binaries and the credentials they use. Read them if you’re curious; don’t build on them. Their layout, ownership, and permissions are refined regularly while Hoody is in beta, and a container update can change them.

Everything else is yours: put application data in /hoody/storage, databases in /hoody/databases, and anything else wherever a normal Linux filesystem allows.

Three locations behave specially:

1. /hoody/storage - Hoody Kit service data (automatic)
2. /hoody/databases - Concurrent-write-safe SQLite (automatic FUSE mount)
3. /ramdisk - Optional RAM-backed storage (capacity drawn from a shared per-server RAM pool: 512 MiB by default, capped at 50% of server memory)

See dedicated pages for details on /hoody/databases and /ramdisk.

---

Persistence guarantees

What survives each operation:

Container Restart

POST /api/v1/containers/{id}/restart

All filesystem data persists:

• /hoody/storage - intact
• /hoody/databases - intact
• /ramdisk - intact
• User files - intact
• Installed packages - intact

Container Stop/Start

POST /api/v1/containers/{id}/stop
POST /api/v1/containers/{id}/start

All filesystem data persists:

• Same as restart
• /ramdisk also survives

Snapshot/Restore

POST /api/v1/containers/{id}/snapshots
PUT /api/v1/containers/{id}/snapshots/{name}

The complete disk state is captured:

• Entire disk state frozen
• All on-disk data in the snapshot
• A restore returns the disk to that exact state
• /ramdisk is not captured, because it is RAM rather than disk. A restore never brings /ramdisk contents back to the snapshot moment

Host Reboot

When the physical host server reboots:

Persists:

• /hoody/storage - intact
• /hoody/databases - intact
• All user files - intact

Lost:

• /ramdisk - cleared (RAM storage)
• /tmp - cleared (standard Linux behavior)

/ramdisk is the exception: it is RAM-based, survives container stop, start, and restart, and is cleared on host reboot. See /ramdisk for details.

---

Create a container

The system allocates storage as part of container creation:

CLI

# Create a container; storage is allocated automatically
hoody containers create --project $PROJECT_ID --server-id $SERVER_ID --name "my-app" --hoody-kit

SDK

import { HoodyClient } from 'hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.com', token: TOKEN });

const container = await client.api.containers.create(
  PROJECT_ID,
  { name: 'my-app', server_id: SERVER_ID, hoody_kit: true }
);
console.log(container.data); // Storage ready, /hoody/storage populated

HTTP

curl -X POST "https://api.hoody.com/api/v1/projects/$PROJECT_ID/containers" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-app", "server_id": "'$SERVER_ID'", "hoody_kit": true}'

URL

?

One request, one link

cURL runs inside your container and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.

Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials.

Slashes, colons and braces pass through as they are. The one character you must encode is an & inside a value, which happens when the wrapped URL carries its own query string. Left raw it ends the value early, and the rest is read as cURL's own parameters, so you get a 200 on a request you did not make.

How the wrapping works Chaining calls into one link Turning a link into a shortcut

Runs through an already-running container’s curl-1, so a project’s first container still has to come from one of the other tabs. There is no size field to set: the host allocates the storage.

Copy

https://PROJECT_ID-OTHER_CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/projects/PROJECT_ID/containers&method=POST&bearer_token=TOKEN&json={"name":"my-app","server_id":"SERVER_ID","hoody_kit":true}&response=transparent

The link carries a credential and executes with it, so it is as sensitive as the credential itself — and it passes through the cURL service's request log on the way, not just the target's. Share it only where you would share the secret, and prefer a delegated token with minimal permissions and an expiry: see API tokens.

There is no storage-size parameter to send. The system allocates storage at the host level.

---

Storage access methods

You can reach container storage in several ways:

HTTP API

Hoody Files - Direct HTTP access to filesystem

GET /api/v1/files/hoody/storage/hoody-exec/scripts/default/1/hello.ts

• Read/write files via HTTP
• Download with SHA256 verification
• List directories with JSON/HTML output
• Stream large files

Local mounting

Mount Locally - SFTP (Hoody API SSH proxy) / WebDAV (hoody-files)

Mount container filesystem on your local machine:

• macOS Finder / Windows Explorer
• FileZilla, Cyberduck, WinSCP
• Command-line SFTP/WebDAV clients

WebDAV is served by hoody-files; SFTP comes from the Hoody API’s SSH proxy.

Terminal access

Hoody Terminal - Web-based shell

ls -la /hoody/storage/
cat /hoody/databases/app.db
echo "data" > /ramdisk/cache.txt

Full shell access via browser.

SSH access

SSH - Secure shell

ssh root@{projectId}-{containerId}-ssh.{serverName}.containers.hoody.com   # same shape as every other service, minus the instance number
cd /hoody/storage

Optional - terminal access works without SSH.

---

Storage use cases

Development containers

# Code, dependencies, build artifacts
/home/user/projects/          # Your code
/hoody/storage/hoody-exec/scripts/default/1/   # HTTP-callable scripts
/ramdisk/build/               # RAM-backed build cache

Use /ramdisk for build artifacts and the regular filesystem for source code, which has to persist.

Database containers

# Concurrent-write-safe SQLite
/hoody/databases/production.db    # Automatic concurrent write safety
/hoody/databases/staging.db       # No replication, just safe writes

Store every SQLite database in /hoody/databases/ for automatic concurrent-write protection. See SQLite Driver.

File storage containers

# User uploads, media files
/hoody/storage/uploads/       # Persistent user data
/ramdisk/processing/          # Temporary file processing

Accept uploads into regular storage and use /ramdisk for temporary processing such as image resizing or video transcoding.

---

Manage storage

Check storage usage

CLI

# Container resource stats (includes disk usage)
# The id is positional here - the global -c/--container does not work on this command
hoody containers stats $CONTAINER_ID -o json

SDK

const stats = await client.api.containers.getStats(CONTAINER_ID);
console.log(stats.data.disk); // { root: { total, usage } } in bytes

HTTP

# Get container resource stats
curl "https://api.hoody.com/api/v1/containers/$CONTAINER_ID/stats" \
  -H "Authorization: Bearer $TOKEN"
# data.disk.root.usage / data.disk.root.total (bytes)

# List files with sizes via hoody-files
curl "https://$PROJECT-$CONTAINER-files-1.$SERVER.containers.hoody.com/?json"

URL

?

One request, one link

cURL runs inside your container and can wrap any HTTP request into a single GET URL. The call stops being something you need a client for and becomes something you can paste into a browser, send in a chat, bookmark, schedule with cron, or drop into a no-code tool.

Nothing is installed on the machine that opens it. The link does carry whatever credentials the call needs, so treat it as you would treat those credentials.

Slashes, colons and braces pass through as they are. The one character you must encode is an & inside a value, which happens when the wrapped URL carries its own query string. Left raw it ends the value early, and the rest is read as cURL's own parameters, so you get a 200 on a request you did not make.

How the wrapping works Chaining calls into one link Turning a link into a shortcut

Two links: disk usage from the container stats endpoint, and a JSON file listing with sizes from hoody-files.

Copy

# Container stats
https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/containers/CONTAINER_ID/stats&method=GET&bearer_token=TOKEN&response=transparent

# List files (hoody-files)
https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://PROJECT_ID-CONTAINER_ID-files-1.SERVER.containers.hoody.com/?json&method=GET&response=transparent

The link carries a credential and executes with it, so it is as sensitive as the credential itself — and it passes through the cURL service's request log on the way, not just the target's. Share it only where you would share the secret, and prefer a delegated token with minimal permissions and an expiry: see API tokens.

From inside the container, via hoody-terminal:

df -h
# Shows filesystem usage

du -sh /hoody/storage/*
# Shows Hoody Kit service data sizes

du -sh /hoody/databases/*
# Shows database sizes

Clean up storage

Remove unused data:

# Clear package manager cache
apt-get clean

# Remove old logs
rm -rf /hoody/storage/*/logs/*.old

# Clear ramdisk (frees server memory immediately)
rm -rf /ramdisk/*

Migrate to larger storage

Storage is not adjustable per container today. The workaround is to create a new container and move the data across:

1. Create snapshot of old container
2. Create new container (receives system-allocated storage)
3. Transfer data via storage shares
4. Verify migration
5. Delete old container

---

Best Practices

Use /hoody/storage for application data

Store your app’s persistent data in /hoody/storage/myapp/ to keep it organized with Hoody Kit services:

mkdir -p /hoody/storage/myapp/data
mkdir -p /hoody/storage/myapp/configs
mkdir -p /hoody/storage/myapp/logs

Keep SQLite databases in /hoody/databases/

Always store SQLite databases in /hoody/databases/ for automatic concurrent-write safety:

# Correct - concurrent write safe
sqlite3 /hoody/databases/app.db

# Wrong - risk of database corruption
sqlite3 /hoody/storage/app.db

Use /ramdisk for temporary data

Use it for caches, build artifacts, and temporary processing:

# RAM-backed temporary storage
/ramdisk/npm-cache/
/ramdisk/build-output/
/ramdisk/image-processing/

/ramdisk is cleared on host reboot, not on container restart.

Snapshot before major changes

Before modifying large amounts of data or testing destructive operations:

POST /api/v1/containers/{id}/snapshots
{"alias": "before-cleanup-2025-11-10"}

Storage is persistent but not immune to accidental deletion.

Monitor storage usage

Set up monitoring for storage capacity:

# Check if storage >80% full
df -h / | awk 'NR==2 {print $5}' | sed 's/%//'

Integrate with hoody-notifications for alerts.

---

Useful Questions

Can I change storage size after creating a container?

No. Storage allocation is not adjustable at the container level. The host allocates it automatically when the container is created.

The workaround is to create a new container and migrate the data through storage shares or a manual copy.

What happens to /hoody/storage if I disable Hoody Kit?

The directory remains (it’s just a directory), but services won’t write to it since they’re not installed. Existing data persists.

Is /hoody/storage a special mount or just a directory?

Just a regular directory with a specific purpose: Hoody Kit services use it by convention. It has no special filesystem characteristics.

How is /hoody/storage different from /hoody/databases/?

• /hoody/storage = Regular directory where Hoody Kit stores service data
• /hoody/databases/ = Special FUSE mount with concurrent-write safety for SQLite

See SQLite Driver for /hoody/databases/ details.

Can I share /hoody/storage between containers?

Yes. Use Storage Shares:

POST /api/v1/containers/{id}/storage/shares
{
  "source_path": "/hoody/storage/myapp",
  "target_project_id": "{project}",
  "mode": "readonly"
}

Does /hoody/storage count toward storage quota?

Yes. All on-disk usage (including /hoody/storage) counts toward your container’s total storage. The one exception is /ramdisk, which is memory rather than disk and counts toward no disk total. The per-container allocation is system-managed: there is no storage-size parameter on the create or update endpoints, so you can’t resize it directly from the client.

---

Troubleshooting

Storage full errors

Problem: “No space left on device” errors

Solutions:

1. Check storage usage:

   df -h
   du -sh /* | sort -h

2. Clean package cache:

   apt-get clean
   apt-get autoremove

3. Remove old logs:

   find /hoody/storage -name "*.log" -mtime +30 -delete

4. Clear /ramdisk if full:

   rm -rf /ramdisk/*

Cannot write to /hoody/storage

Problem: Permission denied writing to /hoody/storage

Solution: Containers run as root - this shouldn’t happen. Check:

ls -la /hoody/
# Should show: drwxr-xr-x root root

If permissions are wrong, fix them:

chown -R root:root /hoody/storage
chmod -R 755 /hoody/storage

/hoody/storage missing after creation

Problem: Directory doesn’t exist in new container

Cause: Container created with hoody_kit: false

Solution: /hoody/storage is only created when Hoody Kit is installed. If you need it:

mkdir -p /hoody/storage

But services won’t use it without Hoody Kit enabled.

---

What’s Next

Storage ecosystem:

• Mount Locally → - Access container files via SFTP/WebDAV on your local machine
• SQLite Driver → - Concurrent-write-safe database storage in /hoody/databases/
• Cloud Storage → - Connect 62 cloud providers via hoody-files
• Shared Storage → - Share directories between containers
• /ramdisk → - RAM-backed storage for caches and temporary files

File access methods:

• Hoody Files API → - HTTP-based filesystem operations
• Hoody Terminal → - Web-based shell access
• SSH Access → - Secure shell (optional)