Shared Storage

Share directories from one container to others—automatically works across servers. Perfect for multi-service applications, team collaboration, and data exchange without duplicating files.

Tip

Cross-Server Magic: Storage shares automatically work between containers on different physical servers. Hoody handles all the complexity—full POSIX compliance including file locks is maintained transparently.

---

API Endpoints Summary

Complete Storage Shares API:

Creating & Managing Shares:

• POST /api/v1/containers/{id}/storage/shares - Create new share
• GET /api/v1/containers/{id}/storage/shares - List your created shares
• PATCH /api/v1/containers/{id}/storage/shares/{shareId} - Update share config
• DELETE /api/v1/storage/shares/{shareId} - Delete share

Receiving & Mounting Shares:

• GET /api/v1/containers/{id}/storage/incoming - List incoming shares
• PATCH /api/v1/containers/{id}/storage/incoming/{shareId}/mount - Accept/reject share
• GET /api/v1/storage/incoming - All incoming shares (all containers)

---

Core Architecture

Storage shares use a two-party system:

Source Container Decides WHAT

Share Creator Controls:

• Which directory to share (source_path)
• Access mode (readonly or readwrite)
• Who can access (1-to-1 or project-wide)
• When it expires (optional)
• Enable/disable anytime

Target Container Decides IF

Share Receiver Controls:

• Whether to mount the share
• Can reject shares they don’t need
• Can unmount anytime
• Independent of share status

Key principle: Source controls WHAT. Target controls IF.

---

Share Types

1-to-1 Container Share

Share specific directory with ONE container:

CLI

# Create 1-to-1 container share (readonly)
hoody storage create --container $SOURCE_ID \
  --source-path "/hoody/storage/shared-assets" \
  --target-container-id $TARGET_ID \
  --mode readonly \
  --description "Static assets for frontend container"

SDK

const share = await client.api.storageShares.create(SOURCE_CONTAINER_ID, {
  source_path: '/hoody/storage/shared-assets',
  target_container_id: TARGET_CONTAINER_ID,
  mode: 'readonly',
  description: 'Static assets for frontend container'
});
console.log(share.data.id); // Share ID for mounting

HTTP

curl -X POST "https://api.hoody.icu/api/v1/containers/$SOURCE_ID/storage/shares" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_path": "/hoody/storage/shared-assets",
    "target_container_id": "'$TARGET_ID'",
    "mode": "readonly",
    "description": "Static assets for frontend container"
  }'

POST Create 1-to-1 container share

/api/v1/containers/{source_id}/storage/shares

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Use when:

• Backend sharing data with frontend
• Database container sharing with API container
• Specific service-to-service integration

Project-Wide Share

Share directory with ALL containers in a project:

CLI

# Create project-wide share — all containers in project can access
hoody storage create --container $SOURCE_ID \
  --source-path "/hoody/storage/config" \
  --target-project-id $PROJECT_ID \
  --mode readonly \
  --description "Shared configuration for all services"

SDK

const share = await client.api.storageShares.create(SOURCE_CONTAINER_ID, {
  source_path: '/hoody/storage/config',
  target_project_id: PROJECT_ID,
  mode: 'readonly',
  description: 'Shared configuration for all services'
});
// Every container in the project automatically mounts this share

HTTP

curl -X POST "https://api.hoody.icu/api/v1/containers/$SOURCE_ID/storage/shares" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "source_path": "/hoody/storage/config",
    "target_project_id": "'$PROJECT_ID'",
    "mode": "readonly",
    "description": "Shared configuration for all services"
  }'

POST Create project-wide share

/api/v1/containers/{source_id}/storage/shares

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Every container in project automatically mounts this share (by default).

Tip

Why automatic mounting is safe: Containers are uniquely identified by their IDs, which are guaranteed unique across all users and servers. When a project-wide share is created, each container automatically gets a unique mount point at /hoody/shares/{alias}/. There’s zero risk of conflicts or ambiguity.

You don’t need to accept - just ignore the mount if you don’t need it, or explicitly unmount:

PATCH /api/v1/containers/{id}/storage/incoming/{share_id}/mount
{"mount": false}

Future feature: Blacklist specific shares by default (opt-in instead of opt-out). For now, shares auto-mount and you can ignore/unmount as needed.

Use when:

• Shared configuration across all services
• Common assets or libraries
• Team-wide resources

---

Access Modes

readonly

{
  "mode": "readonly"
}

Target containers can:

• Read files
• List directories
• Check metadata
• Cannot create files
• Cannot modify files
• Cannot delete files

Perfect for:

• Static assets (images, CSS, JS)
• Configuration files
• Reference data
• Logs (share read-only for monitoring)

readwrite

{
  "mode": "readwrite"
}

Target containers can:

• Read files
• Create new files
• Modify existing files
• Delete files
• Create/delete directories

Changes visible to:

• Source container (immediately)
• All other containers with share mounted

Perfect for:

• Collaborative multi-user projects
• Shared databases (use with /hoody/databases/)
• Upload directories
• Multi-writer data pipelines

Read-write can be paused without failing the share. A cross-server readwrite share remains active when read-write publication is paused, but do not assume reads remain available: an already-live share may remain readable, whereas a share degraded during initial publication is not mounted for consumers. The share still returns 201. After creation, retrieve it with GET /api/v1/containers/{id}/storage/shares/{shareId} and check status_message first; for a newly paused publication it gives the required action: set a disk size limit when the owner container has no enforced quota; remove a nested subvolume that escapes the quota; wait for the owner host to regain enforced disk quotas when the host itself cannot enforce them. Read-write publication resumes automatically after any of those conditions is fixed. During reconciliation of an already-published share, an owner-host quota-enforce capability miss can instead leave status_message null or unchanged even though the live export is rendered read-only.

Cross-server read-write behavior is conditional. When CROSS_HOST_NFS_ENABLED=true but CROSS_HOST_NFS_ALLOW_RW is not exactly true, creating a readwrite share that would span hosts is rejected with HTTP 422 before the share is created; same-host read-write shares are unaffected. When cross-server read-write is enabled, quota enforcement can instead pause publication without failing the share.

---

Complete Share Workflow

Creating a Share

1. Create Directory

# In source container
mkdir -p /hoody/storage/team-assets

# Add files
cp logo.png /hoody/storage/team-assets/
cp styles.css /hoody/storage/team-assets/

2. Create Share

POST Create storage share for team assets

/api/v1/containers/{source_id}/storage/shares

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Response (201) returns the full share object, including id (the new share’s ID) needed for mounting.

3. Target Mounts

GET List incoming shares for target container

/api/v1/containers/{target_id}/storage/incoming

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

PATCH Mount the share

/api/v1/containers/{target_id}/storage/incoming/{share_id}/mount

Fetch cURL PowerShell

▶ Run

Response

Click "Run" to execute the request

Share now accessible in /hoody/shares/{share_alias}/.

4. Access Files

# In target container
ls /hoody/shares/shared-assets/
# logo.png  styles.css

# Files from source container, accessible in target
cat /hoody/shares/shared-assets/styles.css

---

Mount Points

When a target container mounts a share, files appear at:

/hoody/shares/{share-alias}/

Example:

# Source creates share with alias "config"
POST /storage/shares
{
  "source_path": "/hoody/storage/app-config",
  "alias": "config"
}

# Target mounts share
PATCH /api/v1/containers/{target_id}/storage/incoming/{share_id}/mount
{"mount": true}

# Files now accessible at:
/hoody/shares/config/
├── app.yaml
├── database.json
└── secrets.env

The alias is reflected in the mount point name. The exact mount path is determined by Hoody’s infrastructure and cannot be set directly by the caller.

---

Common Use Cases

Multi-Service Application

Backend shares upload directory with multiple frontends:

# Backend Container (source)
POST /containers/{backend_id}/storage/shares
{
  "source_path": "/hoody/storage/user-uploads",
  "target_project_id": "{project_id}",
  "mode": "readwrite",
  "alias": "uploads"
}

# Frontend Container 1 (accepts)
PATCH /containers/{frontend_1}/storage/incoming/{share_id}/mount
{"mount": true}

# Frontend Container 2 (accepts)
PATCH /containers/{frontend_2}/storage/incoming/{share_id}/mount
{"mount": true}

# Now all three containers see same /hoody/shares/uploads/
# Upload from any frontend → visible to backend and other frontends

Shared Configuration

Config container shares settings with all services (readonly):

# Config Container
POST /containers/{config_id}/storage/shares
{
  "source_path": "/hoody/storage/production-config",
  "target_project_id": "{project_id}",
  "mode": "readonly",
  "alias": "config"
}

# All service containers mount it
# Services read from /hoody/shares/config/
# Only config container can update (others readonly)

Collaborative Development

Developers share workspace between containers:

# Developer A's container
POST /containers/{dev_a}/storage/shares
{
  "source_path": "/home/user/project",
  "target_container_id": "{dev_b_container}",
  "mode": "readwrite",
  "alias": "shared-project"
}

# Developer B mounts in their container
# Both edit files in real-time
# Changes sync instantly

Log Aggregation

Services share logs with monitoring container (readonly):

# Service 1
POST /storage/shares
{
  "source_path": "/hoody/storage/service1/logs",
  "target_container_id": "{monitor_container}",
  "mode": "readonly"
}

# Service 2
POST /storage/shares
{
  "source_path": "/hoody/storage/service2/logs",
  "target_container_id": "{monitor_container}",
  "mode": "readonly"
}

# Monitor container sees all logs
/hoody/shares/service1-logs/
/hoody/shares/service2-logs/

---

Share Lifecycle

Share Statuses

A share reports one of these statuses:

Status	Description	Next Steps
active	The share specification is retained — not proof that it is enabled, unexpired, mounted, or writable	Check enabled, expires_at, and status_message
failed	Mount failed (see status_message)	Check errors, fix, retry

active means “this share specification is retained”, not “everything landed”. A share stays active while cross-server read-write publication is paused or provisioning is deferred to the background reconciler; those conditions are explained in status_message. It can also stay active while a consumer is unmounted, but status_message does not report per-consumer mount state.

Check status:

GET /api/v1/containers/{id}/storage/shares/{shareId}

# Response includes: "status": "active" AND "status_message"
# status_message is null when nothing is degraded. Read it, not just status.

Enabling/Disabling Shares

Source container can disable without deleting:

# Disable share temporarily
PATCH /api/v1/containers/{source_id}/storage/shares/{share_id}
{
  "enabled": false,
  "description": "Temporarily disabled for maintenance"
}

# Files unmount from target containers
# Share configuration preserved

# Re-enable later
PATCH /api/v1/containers/{source_id}/storage/shares/{share_id}
{
  "enabled": true
}

Use for: Maintenance windows, testing, gradual rollouts.

Expiring Shares

Set automatic expiration:

POST /api/v1/containers/{id}/storage/shares
{
  "source_path": "/hoody/storage/temp-files",
  "target_container_id": "{target}",
  "mode": "readonly",
  "expires_at": 1735689600  # Unix timestamp: 2025-01-01
}

# Share auto-unmounts and notifies before expiry

Perfect for: Temporary access, demo environments, time-limited shares.

---

Managing Shares

List All Your Created Shares

CLI

# Shares you created from specific container
hoody storage list --container $SOURCE_ID

# All shares you created (across all containers)
hoody storage list-all

SDK

// Shares from specific container
const shares = await client.api.storageShares.list(SOURCE_CONTAINER_ID);
console.log(shares.data); // Array of shares you created

// All shares across all containers
const allShares = await client.api.storageShares.listGlobalIterator();

HTTP

# Shares you created from specific container
curl "https://api.hoody.icu/api/v1/containers/$SOURCE_ID/storage/shares" \
  -H "Authorization: Bearer $TOKEN"

# All shares you created (across all containers)
curl "https://api.hoody.icu/api/v1/storage/shares" \
  -H "Authorization: Bearer $TOKEN"

List Incoming Shares

CLI

# Incoming shares for specific container
hoody storage incoming list --container $TARGET_ID

# All incoming shares (all your containers)
hoody storage incoming list-all

SDK

// Incoming shares for specific container
const incoming = await client.api.storageShares.listIncoming(TARGET_CONTAINER_ID);
console.log(incoming.data); // Shares offered to this container

// All incoming shares across all containers
const allIncoming = await client.api.storageShares.listIncomingGlobalIterator();

HTTP

# Incoming shares for specific container
curl "https://api.hoody.icu/api/v1/containers/$TARGET_ID/storage/incoming" \
  -H "Authorization: Bearer $TOKEN"

# All incoming shares (all your containers)
curl "https://api.hoody.icu/api/v1/storage/incoming" \
  -H "Authorization: Bearer $TOKEN"

Update Share Configuration

CLI

# Upgrade share from readonly to readwrite
hoody storage update --container $SOURCE_ID --share-id $SHARE_ID \
  --mode readwrite --description "Now allows writes"

SDK

await client.api.storageShares.update(SOURCE_CONTAINER_ID, SHARE_ID, { mode: 'readwrite', description: 'Now allows writes' });

HTTP

curl -X PATCH "https://api.hoody.icu/api/v1/containers/$SOURCE_ID/storage/shares/$SHARE_ID" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"mode": "readwrite", "description": "Now allows writes"}'

Target containers must remount to get updated mode.

Delete Share

CLI

# Delete share — unmounts from all target containers
hoody storage delete $SHARE_ID --yes

SDK

await client.api.storageShares.delete(SHARE_ID);
// Unmounts from all target containers, configuration deleted permanently

HTTP

curl -X DELETE "https://api.hoody.icu/api/v1/storage/shares/$SHARE_ID" \
  -H "Authorization: Bearer $TOKEN"

---

Cross-Server Sharing (Automatic)

Storage shares automatically work across different physical servers with full POSIX compliance:

┌──────────────────────────────┐
│   Server US-West-1           │
│   ┌──────────────────────┐   │
│   │  Source Container    │   │
│   │  /shared/data/       │   │
│   └──────────────────────┘   │
│            ↓ Hoody handles    │
└──────────────────────────────┘
              ↓ cross-server
┌──────────────────────────────┐
│   Server EU-Central-1        │
│   ┌──────────────────────┐   │
│   │  Target Container    │   │
│   │  /hoody/shares/data/ │   │
│   └──────────────────────┘   │
└──────────────────────────────┘

What you get automatically:

• Cross-server mounting - Works whether containers on same or different servers
• Full POSIX compliance - All filesystem operations work normally
• File locks respected - Concurrent access properly coordinated
• No per-share setup for supported modes - Once CROSS_HOST_NFS_ENABLED=true, cross-server read-only shares use the normal share workflow; cross-server readwrite also requires CROSS_HOST_NFS_ALLOW_RW=true
• Same API, conditional capability - The share API is the same for same-server and cross-server targets, but cross-server read-write creation is rejected unless read-write is enabled

Caution

SQLite Databases: While file locks ARE respected, we don’t recommend storing SQLite databases in shared storage for cross-container access. Use /hoody/databases/ instead.

Why: SQLite’s file locking is designed for local filesystems. Network-shared SQLite can experience:

• Lock timeouts under high load
• Potential corruption on network interruptions
• Performance degradation compared to local access

Better solution: Store SQLite in /hoody/databases/ (concurrent-write-safe FUSE mount) or use hoody-sqlite HTTP API for cross-container database access.

---

Useful Questions

What happens when source container is stopped?

Share remains mounted but inaccessible.

• Target containers see mount point: /hoody/shares/{alias}/
• Attempting to read files: Stale file handle error
• When source restarts: Access restored automatically

Best practice: Don’t rely on shares from containers that stop frequently.

Can I share the same directory to multiple containers?

Yes! Create multiple shares from same source_path:

# Share /hoody/storage/assets with 3 containers
POST /storage/shares {"source_path": "/hoody/storage/assets", "target_container_id": "A"}
POST /storage/shares {"source_path": "/hoody/storage/assets", "target_container_id": "B"}
POST /storage/shares {"source_path": "/hoody/storage/assets", "target_container_id": "C"}

# Or share once to entire project (all containers see it)
POST /storage/shares {"source_path": "/hoody/storage/assets", "target_project_id": "{project}"}

Can I share /hoody/databases/ directories?

Not recommended for SQLite databases. While you CAN share /hoody/databases/ directories, it bypasses the concurrent-write safety:

# NOT Recommended: Sharing /hoody/databases via storage shares
POST /storage/shares
{
  "source_path": "/hoody/databases",
  "mode": "readwrite"
}

# Problem: Network-shared SQLite loses local-filesystem optimizations
# Better: Each container uses /hoody/databases/ locally (same-server concurrent writes)
# Better: Use hoody-sqlite HTTP API for cross-container database access

Why not recommended:

• /hoody/databases/ concurrent-write safety is optimized for local same-server access
• Network sharing adds latency and lock timeout risks
• SQLite not designed for network filesystems

Better solutions:

• Same server: Each container accesses /hoody/databases/ directly (concurrent-write-safe)
• Cross-server: Use hoody-sqlite HTTP API to access databases remotely
• Data sharing: Share application data directories, not database files

What if target rejects the share?

Share remains available but unmounted. Target can accept later:

# Initially reject
PATCH /api/v1/containers/{target_id}/storage/incoming/{share_id}/mount
{"mount": false}

# Accept later when needed
PATCH /api/v1/containers/{target_id}/storage/incoming/{share_id}/mount
{"mount": true}

# Files appear in /hoody/shares/{alias}/

Do shares persist through container restarts?

Yes. Share configuration and mount state survive:

• Source container restart - share remains
• Target container restart - mount point restored
• Both restart - everything reconnects

Can I change the alias after creating a share?

Yes:

PATCH /api/v1/containers/{source_id}/storage/shares/{share_id}
{
  "alias": "new-alias"
}

Target containers must unmount and remount to use new alias. Old mount point /hoody/shares/old-alias/ becomes invalid.

Do storage shares count toward quota?

Source container: Files count toward source’s storage.

Target containers: Mounted shares do NOT count toward target’s storage quota (they’re references, not copies).

---

Troubleshooting

Share Status Shows “failed”

Problem: Share status is "failed" with error message

Common causes:

1. Source path doesn’t exist:

   # In source container, verify path exists
   ls -la /hoody/storage/shared-path
   
   # Create if missing
   mkdir -p /hoody/storage/shared-path
   
   # Update share to retry
   PATCH /api/v1/containers/{source_id}/storage/shares/{share_id}
   {"enabled": true}

2. Permission issues:

   # Fix permissions in source container
   chown -R root:root /hoody/storage/shared-path
   chmod -R 755 /hoody/storage/shared-path

3. Source container stopped:

   • Start source container
   • Share will automatically reactivate

4. Not failed, but degraded: a share whose read-write is paused stays active, not failed. If writes are rejected while status reads active, check status_message first. When populated, it names the required action: set a disk size limit when the owner container has no enforced quota; remove a nested subvolume that escapes the quota; wait for the owner host to regain enforced disk quotas when the host itself cannot enforce them. Read-write publication resumes automatically after any of those conditions is fixed. For an already-published share, however, an owner-host quota-enforce capability miss can render the export read-only while deliberately leaving status_message null or unchanged; restore quota enforcement on the owner host in that case.

Cannot See Mounted Share Files

Problem: Share mounted but /hoody/shares/{alias}/ is empty

Solutions:

1. Verify share is active — and read status_message:

   GET /api/v1/containers/{target_id}/storage/incoming
   # Check: "status": "active", "enabled": true
   # `status_message` can explain degraded or deferred provisioning.
   # This response does not report whether this consumer is mounted.

2. Check source container is running:

   GET /api/v1/containers/{source_id}
   # Verify: "status": "running"

3. Verify files exist in source:

   # In source container
   ls /hoody/storage/shared-path
   # Should show files

4. Unmount and remount:

   PATCH /api/v1/containers/{target_id}/storage/incoming/{share_id}/mount
   {"mount": false}
   
   PATCH /api/v1/containers/{target_id}/storage/incoming/{share_id}/mount
   {"mount": true}

“Stale file handle” Errors

Problem: Cannot access files in /hoody/shares/{alias}/

Cause: Source container restarted while target was accessing files

Solution:

# Unmount and remount
PATCH /api/v1/containers/{target_id}/storage/incoming/{share_id}/mount
{"mount": false}

PATCH /api/v1/containers/{target_id}/storage/incoming/{share_id}/mount
{"mount": true}

# Or restart target container (auto-remounts)
POST /api/v1/containers/{target_id}/restart
# (Consolidated lifecycle route: POST /api/v1/containers/{id}/{operation}
#  where {operation} is one of: start | stop | force-stop | restart | pause | resume)

Share Appears in Incoming but Won’t Mount

Problem: PATCH /mount succeeds but files don’t appear

Check:

1. Share is enabled:

   GET /api/v1/containers/{target_id}/storage/incoming
   # Find the share in the list and verify: "enabled": true

2. Share not expired:

   # Check expires_at (Unix timestamp)
   # If expired, ask source to extend or remove expiration

3. Target container has permission:

   • Verify target is in specified project (for project-wide shares)
   • Verify target_container_id matches (for 1-to-1 shares)

---

Best Practices

1. Share /hoody/storage Subdirectories, Not Root

# Good: Specific subdirectory
{"source_path": "/hoody/storage/assets"}

# Risky: Entire Hoody Kit storage
{"source_path": "/hoody/storage"}

# Sharing entire /hoody/storage exposes all service data

2. Use Project-Wide for Common Resources

One share for all containers:

# Instead of creating 10 identical 1-to-1 shares
POST /storage/shares {"target_project_id": "{project}"}

# All containers in project can mount
# Simpler management, one configuration

3. Monitor Readwrite Shares

Multiple writers can conflict:

# Container A writes /hoody/shares/data/file.txt
# Container B writes /hoody/shares/data/file.txt (same file)

# Last write wins (potential data loss)

Solution: Use application-level locking or coordinate writes (e.g., different directories per container).

Or use /hoody/databases/ for SQLite databases (automatic concurrent-write safety).

4. Snapshot Before Deleting Shares

Share deletion unmounts from all targets:

# Snapshot source container first
POST /api/v1/containers/{source_id}/snapshots
{"alias": "before-share-deletion"}

# Then delete share
DELETE /api/v1/storage/shares/{share_id}

5. Use Descriptive Descriptions

# Clear documentation
{
  "description": "Read-only access to team logo, CSS, and JS assets for frontend containers. Source: /hoody/storage/static-web-assets"
}

# Vague
{
  "description": "shared files"
}

Future you will thank present you when managing dozens of shares.

---

What’s Next

Storage ecosystem:

• Container Storage → - Understanding container filesystem
• Mount Locally → - SFTP/WebDAV for local file managers
• SQLite Driver → - Concurrent-write databases
• Cloud Storage → - Connect 62 cloud providers
• /ramdisk → - Ultra-fast RAM storage

Related features:

• Container Copy → - Duplicate entire containers
• Snapshots → - Backup container state
• Hoody Files → - HTTP filesystem access

Understanding gained:

• Source container controls WHAT is shared
• Target container controls IF they mount it
• Two modes: readonly, readwrite
• Two types: 1-to-1, project-wide
• Works cross-server automatically
• Combine with /hoody/databases/ for shared SQLite databases

---

Share directories between containers.
Readonly for safety. Readwrite for collaboration.

One share, multiple consumers. Data exchange without duplication.