Shared Storage

Share a directory from one container to others on the same server, and, on servers where cross-server sharing is enabled, to 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 can span different physical servers, preserving POSIX semantics including file locks. That path is a pilot feature and off by default, and while it is off a cross-server share is created and reported as successful without ever mounting. See Cross-server sharing before relying on it.

---

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 shares 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.storage.shares.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 shares 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.storage.shares.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
• Upload directories
• Multi-writer data pipelines

Not suited to SQLite database files: see the caution under Cross-server sharing.

Across servers: read-write works where cross-server sharing is enabled. While it is disabled, the share is still created and returns success without mounting. See Cross-server sharing.

---

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. Verify or change the mount state

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 creation already mounted this on its target(s); this step only changes that preference — send {"mount": false} to reject and unmount it, or {"mount": true} to remount it. Once mounted, the files are 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	Successfully synced to the server	—
failed	Mount failed (see status_message)	Check errors, fix, retry

active means the share was successfully synced to the server. failed means a sync or mount error; read status_message for the error details.

Check status:

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

# Response includes: "status": "active" AND "status_message"
# status_message carries error details when status is failed.

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
}

# At expires_at the share is auto-deleted, which unmounts it from every target

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 containers shares list --container $SOURCE_ID

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

SDK

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

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

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 containers incoming list --container $TARGET_ID

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

SDK

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

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

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 shares update --container $SOURCE_ID --share-id $SHARE_ID \
  --mode readwrite --description "Now allows writes"

SDK

await client.api.storage.shares.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 shares delete $SHARE_ID --yes

SDK

await client.api.storage.shares.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

Cross-server sharing is a pilot feature and it is off by default. Where it is on, both read-only and read-write shares are permitted across hosts. Same-server shares are plain bind mounts and always work.

A disabled cross-server share reports success without mounting

When the feature is off, a share whose target sits on another server is not rejected. The API can report success without mounting anything, and nothing in the response or the share record says so.

Do not treat the created share as proof of a mount. Look inside the target container and confirm that the mount path carries the source’s contents before you depend on it.

Once enabled, 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 once it is enabled:

• 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: cross-server shares use the normal share workflow
• Same API: the share API is the same for same-server and cross-server targets

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: keep the database on the owning container’s own filesystem, conventionally /hoody/databases/, and let other containers reach it through the hoody-sqlite HTTP API. That keeps the file on one container’s local filesystem, where SQLite’s locking works.

---

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?

You can, and you should not put SQLite database files in the shared directory:

# Do not do this with a database inside
POST /storage/shares
{
  "source_path": "/hoody/databases",
  "mode": "readwrite"
}

Why: SQLite’s safety rests on the filesystem honoring its locks. A share is a mount, and a cross-server one is NFS, where that is not guaranteed. Two containers opening the same database file through a share risk corruption, not just lock timeouts.

Better solutions:

• One writer: keep the database in the owning container and expose it through the hoody-sqlite HTTP API
• 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

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 carries error details for failed shares.
   # 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, the share is already deleted and gone from this list — create a new one

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, do not share the file at all. Keep it in one container and query it over the hoody-sqlite HTTP API.

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 → - SQLite databases in a container
• Cloud Storage → - Connect 49 remote storage backends
• /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
• Not for SQLite databases: keep them in the owning container’s /hoody/databases/ and share them through the hoody-sqlite HTTP API