Encryption Layer

Connect storage backends through the encryption layer to wrap any existing remote with crypt (transparent encryption) or compression. The crypt overlay encrypts filenames and file data using a user-supplied password, while the compress overlay applies gzip compression on read and write. Both return a new backend identifier that you can mount like any other remote.

Connect a crypt backend

POST /api/v1/backends/crypt

Wrap an existing remote with transparent AES encryption. The crypt overlay encrypts filenames (by default), directory names, and file data using the password you provide, then forwards reads and writes to the underlying remote. The encrypted remote behaves like a normal backend once mounted.

This endpoint takes no parameters.

Request body

Name	Type	Required	Default	Description
`description`	string	No	`""`	Description of the remote.
`directory_name_encryption`	boolean	No	`true`	Encrypt directory names. Has no effect when `filename_encryption` is `off`.
`filename_encoding`	string	No	`"base32"`	Encoding for encrypted filenames. Allowed values: `base32`, `base64`, `base32768`.
`filename_encryption`	string	No	`"standard"`	Filename encryption mode. Allowed values: `standard`, `obfuscate`, `off`.
`no_data_encryption`	boolean	No	`false`	When `true`, file data is left unencrypted. Filename encryption still applies.
`pass_bad_blocks`	boolean	No	`false`	Pass unreadable blocks through as zeros. Only set this when recovering a damaged encrypted file.
`password`	string	Yes	`""`	Password or pass phrase for encryption.
`password2`	string	No	`""`	Optional salt password. Recommended and should differ from `password`.
`remote`	string	Yes	`""`	Remote to encrypt or decrypt, in the form `myremote:path/to/dir` or `myremote:bucket`.
`server_side_across_configs`	boolean	No	`false`	Allow server-side operations to work across different crypt configs pointing at the same backend.
`show_mapping`	boolean	No	`false`	Log decrypted-to-encrypted filename mappings at info level. Useful for debugging.
`strict_names`	boolean	No	`false`	Raise an error when a filename cannot be decrypted, instead of logging a notice.
`suffix`	string	No	`".bin"`	Suffix appended to encrypted files. Use `none` to disable.

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/crypt \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "s3-archive:private",
    "password": "correct horse battery staple",
    "password2": "a-different-salt-value",
    "filename_encryption": "standard",
    "filename_encoding": "base32",
    "directory_name_encryption": true,
    "suffix": ".bin"
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.backends.connectCrypt({
  remote: 's3-archive:private',
  password: 'correct horse battery staple',
  password2: 'a-different-salt-value',
  filename_encryption: 'standard',
  filename_encoding: 'base32',
  directory_name_encryption: true,
  suffix: '.bin'
});

Responses

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "backend_type": "crypt",
    "id": "c2f7a9b1e3d6",
    "type": "crypt",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "Failed to connect crypt backend: remote 's3-archive:private' not found"
}

Connect a compress backend

POST /api/v1/backends/compress

Wrap an existing remote with gzip compression. Compressed reads and writes are forwarded to the underlying remote, reducing bandwidth and storage at the cost of CPU. The compression level is configurable; the default (-1) is equivalent to level 5.

This endpoint takes no parameters.

Request body

Name	Type	Required	Default	Description
`description`	string	No	`""`	Description of the remote.
`level`	integer	No	`-1`	GZIP compression level. `-2` is Huffman only, `-1` is the default (equivalent to `5`), `0` disables compression, `1`-`9` trade speed for size (past `6` returns diminish).
`mode`	string	No	`"gzip"`	Compression mode. Allowed value: `gzip`.
`ram_cache_limit`	string	No	`"20971520"`	Size threshold in bytes. Files smaller than this are cached in RAM to determine their size before upload; larger files are cached on disk. Only relevant for remotes that do not accept uploads of unknown size.
`remote`	string	Yes	`""`	Remote to compress.

cURL
TypeScript SDK

curl -X POST https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com/api/v1/backends/compress \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "remote": "s3-cold:logs/2026",
    "mode": "gzip",
    "level": 5,
    "ram_cache_limit": "20971520",
    "description": "Compressed archive of 2026 logs"
  }'

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-files-1.{server}.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.files.backends.connectCompress({
  remote: 's3-cold:logs/2026',
  mode: 'gzip',
  level: 5,
  ram_cache_limit: '20971520',
  description: 'Compressed archive of 2026 logs'
});

Responses

{
  "success": true,
  "message": "Backend connected successfully",
  "data": {
    "backend_type": "compress",
    "id": "8d4e2c1f7a90",
    "type": "compress",
    "mount_paths": []
  }
}

{
  "success": false,
  "error": "Failed to connect compress backend: remote 's3-cold:logs/2026' not found"
}