Skip to main content

​
Usage

koava encrypt <MODEL_PATH> [OPTIONS]
Aliases: 
koava enc <MODEL_PATH> [OPTIONS]
For help: 
koava encrypt -h

​
Description

The encrypt command:
  • converts standard safetensors files to cryptotensors format (i.e, KoalaVault’s encrypted format). See CryptoTensors File Format for detailed information about the encrypted format.
  • inserts compliance block into README.md and adds LICENSE.KOALAVAULT to clearly state the model is encrypted and license-gated via KoalaVault. See Hugging Face Compliance for more details.
Important: After encryption, you must create a model on Hugging Face, upload the complete encrypted model files, and then update the KoalaVault model page with the Hugging Face URL. You can use the koava push command to do this complete workflow in one step.
Currently, KoalaVault only supports safetensors format files.

​
Prerequisites

Before running encrypt, you must ensure that a model has been created on KoalaVault (either manually or using koava create). This is required because KoalaVault generates model-specific encryption and user-specific signing keys for each publisher and model only after a model is created. The encrypt command needs to retrieve these keys to encrypt and sign your model files.

​
Backup Process

When encrypting in-place (without specifying --output), the encrypt command automatically creates a backup of your original files before encryption. The backup is stored in a .backup directory within your model folder, ensuring your original files are preserved in case you need to restore them later.

​
README & License Handling

This section explains how encrypt updates documentation to ensure compliance while preserving your originals.
  • README
    • Duplicate-safe insertion: the tool uses an invisible marker to ensure the compliance block is inserted at most once.
    • In-place (default): inserts a short compliance block into <MODEL_PATH>/README.md (after the first title). If no README exists, a minimal README is created.
    • With --output: the source README is never modified. A README.md is written to the output directory: if a source README exists, the block is inserted into that content; otherwise, a minimal README is created in the output.
    • Restore behavior: if no README backup is present but the current README contains the marker, koava restore removes the tool-inserted README (in in-place scenarios).
  • License
    • The original LICENSE is never modified.
    • A parallel LICENSE.KOALAVAULT is created alongside the encrypted model files to clarify redistribution and execution rights for encrypted artifacts.
    • koava restore removes LICENSE.KOALAVAULT.

​
Examples

​
Basic Encryption Workflow

# 1. Preview what will be encrypted
koava encrypt ./my-model --dry-run

# 2. Encrypt the model
koava encrypt ./my-model -n "my-awesome-model"

# 3. Verify encryption was successful
ls ./my-model/

​
Custom Output Workflow

# 1. Encrypt to separate directory
koava encrypt ./my-model --output ./encrypted-models --name "my-llm"

# 2. Verify output
ls ./encrypted-models/

​
Advanced

​
Arguments

​
MODEL_PATH

Directory containing safetensors files to encrypt (required).

​
Options

​
—name, -n

Model name for encryption key retrieval, must match the model name on KoalaVault. Default resolution order when not provided:
  • If --output/-o is specified: use the basename of the output directory
  • Otherwise: use the basename of <MODEL_PATH>
# Explicitly set name
koava encrypt ./my-model --name "llama-7b-chat"

# Defaults to output directory basename (my-aws-model)
koava encrypt ./qwen3-0.6b --output ./my-aws-model

# Defaults to model path basename (my-model)
koava encrypt ./my-model

​
—output, -o

Output directory for encrypted files (defaults to in-place encryption). When specified, the encrypted model will be saved in the specified directory. 
koava encrypt ./my-model --output ./encrypted-models

​
—no-backup

Skip automatic backup (only works when --output is not specified, i.e. when encrypting in-place). When not specified, a backup directory .backup will be created in the same directory as the model. The original model files will be copied to the backup directory before encryption. 
koava encrypt ./my-model --no-backup
Warning: Skipping backup is not recommended. If encryption fails, you may lose your original files.

​
—files

Only encrypt specific model files (comma-separated, only includes model files, not configuration files). When not specified, all model files will be encrypted. 
koava encrypt ./my-model --files "model1.safetensors,model2.safetensors"

​
—exclude

Exclude specific model files from encryption (comma-separated, only includes model files, not configuration files). When not specified, all model files will be encrypted. 
koava encrypt ./my-model --exclude "model1.safetensors,model2.safetensors"

​
—dry-run

Preview what would be encrypted without making changes. 
koava encrypt ./my-model --dry-run

​
—force

Force encryption even if backup directory exists. When a backup directory already exists with unencrypted files:
  • Without --force: Encrypts from the existing backup files
  • With --force: Overwrites the backup directory with current files, then encrypts
This flag only affects in-place encryption when a backup directory already exists. 
koava encrypt ./my-model --force

​
Restore Original Files

To restore original files: 
koava restore ./my-model
See koava restore for details.

​
Related Commands

​
See also