Container Storage

Containers get persistent storage automatically. Every container has a full filesystem that 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/WebDAV server for local mounting

Key Concepts

Storage is NOT adjustable on the container level yet. When you create a container, storage is allocated automatically by the system—there’s no API parameter to set storage size per container.

What you get automatically:

✅ 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

/hoody/storage is where Hoody Kit services store their data.

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/
├── terminals/           # hoody-terminal session data
├── displays/            # hoody-displays configs
├── files/               # hoody-files backend configurations
├── exec/                # hoody-exec scripts and cache
├── sqlite/              # hoody-sqlite database metadata
├── browser/             # hoody-browser profiles and cache
├── code/                # hoody-code workspace settings
├── curl/                # hoody-curl job storage
├── cron/                # hoody-cron schedules
├── agent/               # agent service state (via workspaces)
├── daemons/             # hoody-daemon configs
├── notifications/       # hoody-notifications data
├── tunnel/              # hoody-tunnel configs
├── logs/                # aggregated service logs
└── ...                  # plus any service-specific subdirectories

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

This is automatic. You don’t create or configure /hoody/storage—it’s established when the container is created with Hoody Kit.

Why this matters:

All service data in one predictable location
Easy to back up via copy or instant ZIP download from hoody-files (folder-as-zip is served on the WebDAV-style root path, not the /api/v1/files REST surface)
Simple to inspect service state
Consistent across all containers

Storage Architecture

Container Filesystem

Container Root (/)
├── /home/              # User directories (writable)
├── /hoody/
│   ├── /hoody/storage/     # Hoody Kit service data ⭐
│   ├── /hoody/databases/   # SQLite concurrent-write mount ⭐
│   └── /hoody/shares/      # Mounted shared storage (if any)
├── /ramdisk/           # Ultra-fast RAM storage (if enabled) ⭐
├── /tmp/               # Temporary files (cleared on restart)
└── ... (standard Linux filesystem)

Three special storage locations:

/hoody/storage - Hoody Kit service data (automatic)
/hoody/databases - Concurrent-write-safe SQLite (automatic FUSE mount)
/ramdisk - Optional RAM-based ultra-fast storage (capacity capped at 50% of container memory)

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

Persistence Guarantees

What persists:

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

✅ All filesystem data persists

/hoody/storage - intact
/hoody/databases - intact
/ramdisk - PERSISTS (special Hoody feature!)
User files - intact
Installed packages - intact

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

✅ All filesystem data persists

Same as restart
/ramdisk also survives

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

✅ Complete filesystem captured

Entire disk state frozen
All data in snapshot
Restore = exact state recovery

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)

Exception: /ramdisk is RAM-based and only survives container restarts, not host reboots. See /ramdisk for details.

Create a Container (Storage Allocated Automatically)

When you create a container, storage is allocated automatically:

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

import { HoodyClient } from '@hoody-ai/hoody-sdk';
const client = new HoodyClient({ baseURL: 'https://api.hoody.icu', 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

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-app", "server_id": "'$SERVER_ID'", "hoody_kit": true}'

No storage size parameter needed. The system allocates storage automatically at the host level.

Storage Access Methods

You have multiple ways to access container storage:

HTTP API

Hoody Files - Direct HTTP access to filesystem

GET /api/v1/files/hoody/storage/exec/scripts.json

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

Local Mounting

Mount Locally - SFTP/WebDAV server

Mount container filesystem on your local machine:

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

hoody-files acts as server for local mounting.

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@ssh.$serverName.containers.hoody.icu   # e.g. ssh.us-west-1.containers.hoody.icu
cd /hoody/storage

Optional - terminal access works without SSH.

Storage for Different Use Cases

Development Containers

# Code, dependencies, build artifacts
/home/user/projects/          # Your code
/hoody/storage/exec/          # HTTP-callable scripts
/ramdisk/build/               # Ultra-fast build cache

Pattern: Use /ramdisk for build artifacts (fast), regular filesystem for source code (persistent).

Database Containers

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

Pattern: Store all SQLite databases 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

Pattern: Accept uploads to regular storage, use /ramdisk for temporary processing (image resize, video transcode).

Managing Storage

Check Storage Usage

# Check container details (includes storage info)
hoody containers get $CONTAINER_ID

const container = await client.api.containers.get(CONTAINER_ID);
console.log(container.data); // Container details including storage status

# Get container details
curl "https://api.hoody.icu/api/v1/containers/$CONTAINER_ID" \
  -H "Authorization: Bearer $TOKEN"

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

Via hoody-terminal (in-container):

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 (regenerates on next restart anyway)
rm -rf /ramdisk/*

Migrate to Larger Storage

Currently: Storage is NOT adjustable per container.

Workaround: Create new container + transfer data:

Create snapshot of old container
Create new container (receives system-allocated storage)
Transfer data via storage shares
Verify migration
Delete old container

Best Practices

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

2. SQLite Databases Go 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

3. Use /ramdisk for Temporary Fast Storage

Perfect for caches, build artifacts, temporary processing:

# Ultra-fast temporary storage
/ramdisk/npm-cache/
/ramdisk/build-output/
/ramdisk/image-processing/

Remember: /ramdisk is cleared on host reboot (not container restart).

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

5. 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 currently not adjustable on the container level. Storage is managed automatically at the host level when containers are created.

Workaround: Create new container and migrate data via storage shares or 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. 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.

Yes! Use Storage Shares:

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

Does /hoody/storage count toward storage quota?

Yes. All filesystem usage (including /hoody/storage) counts toward your container’s total storage. The per-container allocation is system-managed — the API strips any allocated_storage field on create/update, so you can’t resize it directly from the client.

Troubleshooting

Storage Full Errors

Problem: “No space left on device” errors

Solutions:

Check storage usage:
Terminal window
```
df -h
du -sh /* | sort -h
```
Clean package cache:
Terminal window
```
apt-get clean
apt-get autoremove
```

Remove old logs:

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

Clear /ramdisk if full:
Terminal window
```
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 63 cloud providers via hoody-files
Shared Storage → - Share directories between containers
/ramdisk → - Ultra-fast RAM storage for caching and temporary files

File access methods:

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

Understanding gained:

✅ Storage is persistent (survives restarts, snapshots, copy)
✅ Storage is NOT adjustable per container (automatic allocation)
✅ /hoody/storage is where Hoody Kit services store data
✅ /hoody/databases/ and /ramdisk are special storage locations
✅ Multiple access methods (HTTP API, local mounting, terminal, SSH)

Storage is automatic, persistent, and HTTP-accessible.
No configuration needed—it just works.

Your data persists. Your services know where to store it. You access it via HTTP.