Shared Storage

Share a directory from one container to others, including containers on a different physical server. That covers multi-service applications, team collaboration, and data exchange without duplicating files.

Tip

Cross-server shares: storage shares work between containers on different physical servers. POSIX semantics, including file locks, are preserved across the mount.

---

API Endpoints Summary

Storage shares API:

Create and manage 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

Receive and mount 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:

The source decides what is shared

The share creator sets:

• 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

The target decides whether to mount

The share receiver controls:

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

Key principle: the source controls what is shared; the target controls whether it is mounted.

---

Share types

1-to-1 container share

Share one directory with a single target 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.com/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"
  }'

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

Creates the 1-to-1 share described above as a single GET link.

Copy

https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/containers/SOURCE_ID/storage/shares&method=POST&bearer_token=TOKEN&json={"source_path":"/hoody/storage/shared-assets","target_container_id":"TARGET_ID","mode":"readonly","description":"Static%20assets%20for%20frontend%20container"}&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.

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 a directory with every container 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.com/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"
  }'

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

Creates the project-wide share described above as a single GET link.

Copy

https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/containers/SOURCE_ID/storage/shares&method=POST&bearer_token=TOKEN&json={"source_path":"/hoody/storage/config","target_project_id":"PROJECT_ID","mode":"readonly","description":"Shared%20configuration%20for%20all%20services"}&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.

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 the project mounts this share by default.

Tip

Why automatic mounting is safe: containers are identified by IDs that are unique across all users and servers. When a project-wide share is created, each container gets its own mount point at /hoody/shares/{alias}/, so mount points do not collide.

You do not need to accept the share. Ignore the mount if you do not need it, or unmount it explicitly:

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

Future feature: blacklist specific shares by default, making mounting opt-in instead of opt-out. For now, shares auto-mount and you can ignore or unmount them 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

Suited to:

• 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

Suited to:

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

---

Share workflow

Create a share

1. Create the 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 the 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 it

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 the 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, the 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. Hoody’s infrastructure determines the exact mount path, and the caller cannot set it directly.

---

Common use cases

Multi-service application

A backend shares its upload directory with several 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

A config container shares settings with all services in readonly mode:

# 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

Two developers share a workspace between their 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 containers read and write the same files
# A write from one is visible to the other

Log aggregation

Services share their logs with a monitoring container in readonly mode:

# 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. This is 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.

Enable and disable a share

The source container can disable a share without deleting it:

# 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, and gradual rollouts.

Expire a share

Set an expiration timestamp at creation:

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

Suited to: temporary access, demo environments, and time-limited shares.

---

Manage shares

List the shares you created

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.com/api/v1/containers/$SOURCE_ID/storage/shares" \
  -H "Authorization: Bearer $TOKEN"

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

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

Lists the shares you created, either from one source container or across all of them.

Copy

# From one container
https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/containers/SOURCE_ID/storage/shares&method=GET&bearer_token=TOKEN&response=transparent

# All shares you created
https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/storage/shares&method=GET&bearer_token=TOKEN&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.

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.com/api/v1/containers/$TARGET_ID/storage/incoming" \
  -H "Authorization: Bearer $TOKEN"

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

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

Lists shares offered to you, either for one target container or across all of them.

Copy

# For one container
https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/containers/TARGET_ID/storage/incoming&method=GET&bearer_token=TOKEN&response=transparent

# All incoming shares
https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/storage/incoming&method=GET&bearer_token=TOKEN&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.

Update a share’s 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.com/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"}'

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

Upgrades the share to readwrite as a single GET link.

Copy

https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/containers/SOURCE_ID/storage/shares/SHARE_ID&method=PATCH&bearer_token=TOKEN&json={"mode":"readwrite","description":"Now%20allows%20writes"}&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.

Target containers must remount to pick up the new mode.

Delete a 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.com/api/v1/storage/shares/$SHARE_ID" \
  -H "Authorization: Bearer $TOKEN"

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

Deletes the share as a single GET link, unmounting it from every target container.

Copy

https://PROJECT_ID-CONTAINER_ID-curl-1.SERVER.containers.hoody.com/api/v1/curl/request?url=https://api.hoody.com/api/v1/storage/shares/SHARE_ID&method=DELETE&bearer_token=TOKEN&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.

---

Cross-server sharing

Storage shares 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:

• Cross-server mounting: works whether the containers sit on the same server or different ones
• Full POSIX compliance: all filesystem operations behave normally
• File locks respected: concurrent access is 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: file locks are respected, but storing SQLite databases in shared storage for cross-container access is not recommended. 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

Instead: store SQLite in /hoody/databases/ (a concurrent-write-safe FUSE mount), or use the hoody-sqlite HTTP API for cross-container database access.

---

Useful Questions

What happens when the source container is stopped?

The 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: do not rely on shares from containers that stop frequently.

Can I share the same directory to multiple containers?

Yes. Create multiple shares from the 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. You can share /hoody/databases/ directories, but doing so 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 is not designed for network filesystems

Better solutions:

• Same server: each container accesses /hoody/databases/ directly (concurrent-write-safe)
• Cross-server: use the 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: the share remains
• Target container restart: the mount point is 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 the new alias. The old mount point /hoody/shares/old-alias/ becomes invalid.

Do storage shares count toward quota?

Source container: the files count toward the source’s storage.

Target containers: mounted shares do not count toward the target’s storage quota, because they are references rather than 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.

Mounted share directory is empty

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

Solutions:

1. Verify the 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 will not 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

Share subdirectories, not /hoody/storage itself

# 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

Use project-wide shares 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

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 (for example, a different directory per container).

For SQLite databases, use /hoody/databases/, which is concurrent-write safe.

Snapshot before deleting a share

Deleting a share unmounts it from every target:

# 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}

Describe what the share is for

# 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"
}

This matters once you are 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 → - RAM-backed storage

Related features:

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

Summary:

• The source container controls what is shared
• The target container controls whether it mounts the share
• Two modes: readonly, readwrite
• Two types: 1-to-1, project-wide
• Works cross-server
• Combine with /hoody/databases/ for shared SQLite databases