Where Kānuka Stores Your Files

Kānuka creates different files depending on which features you’re using. Understanding where everything goes helps you work effectively with the tool.

Project files

Kānuka stores all project-related files in a .kanuka folder at the root of your project:

astro.config.mjs
package.json
.env your secrets (should be in .gitignore)
.env.kanuka your secrets, encrypted by Kānuka
Directory.kanuka
- config.toml project configuration
- Directorypublic_keys
  - a1b2c3d4-5678-90ab-cdef-1234567890ab.pub Alice’s key (UUID-based)
  - e5f6g7h8-1234-56cd-efgh-9876543210ab.pub Bob’s key
- Directorysecrets
  - a1b2c3d4-5678-90ab-cdef-1234567890ab.kanuka Alice’s encrypted symmetric key
  - e5f6g7h8-1234-56cd-efgh-9876543210ab.kanuka Bob’s encrypted symmetric key

Project configuration

The .kanuka/config.toml file tracks project metadata and registered users:

[project]
uuid = "proj-1234-5678-90ab-cdef"
name = "my-astro-project"

[users]
"a1b2c3d4-5678-90ab-cdef-1234567890ab" = "[email protected]"
"e5f6g7h8-1234-56cd-efgh-9876543210ab" = "[email protected]"

[devices."a1b2c3d4-5678-90ab-cdef-1234567890ab"]
name = "alice-macbook"
created_at = 2024-01-15T10:30:00Z

[devices."e5f6g7h8-1234-56cd-efgh-9876543210ab"]
name = "bob-desktop"
created_at = 2024-01-16T14:20:00Z

For more details, see Project Configuration.

UUID-based naming

Files are named using each user’s device UUID rather than usernames. This:

Prevents naming conflicts when users have similar names
Allows multiple devices per user (each device gets its own UUID)
Provides a stable identifier that doesn’t change if display names are updated

What gets committed

All files in the .kanuka directory are safe to commit to version control:

File	Safe to commit	Purpose
`.kanuka/config.toml`	Yes	Project metadata and user registry
`.kanuka/public_keys/*.pub`	Yes	Users’ public encryption keys
`.kanuka/secrets/*.kanuka`	Yes	Encrypted symmetric keys
`*.kanuka` files	Yes	Encrypted secrets files
Private keys	Never	Stored in user directory only

A core concept is that each user has their own encrypted version of the symmetric key, but the underlying symmetric key is the same for everyone. To learn more about how encryption works, see the encryption concepts.

User-specific files

To decrypt files encrypted with your public key, you need your private key. Kānuka stores user files in two locations:

Configuration (identity)

Your identity is stored in the XDG config directory:

Directory~/.config/kanuka (or equivalent)
- config.toml your identity (email, name, device UUID)

Example user config:

[user]
email = "[email protected]"
name = "Alice Smith"
uuid = "a1b2c3d4-5678-90ab-cdef-1234567890ab"
device_name = "alice-macbook"

For more details, see User Configuration.

Keys (per-project)

Private keys are stored in the XDG data directory, organized by project:

Directory~/.local/share/kanuka (or %APPDATA%\kanuka on Windows)
- Directorykeys
  - Directoryproj-1234-5678-90ab-cdef project UUID folder
    privkey your private key for this project

Each project you’re registered with has its own key pair. Kānuka automatically finds the correct private key based on the project UUID in .kanuka/config.toml.

Platform-specific paths

Platform	Config location	Data location
Linux/macOS	`~/.config/kanuka/`	`~/.local/share/kanuka/`
Windows	`%APPDATA%\kanuka\`	`%APPDATA%\kanuka\`

You can override these with the XDG_CONFIG_HOME and XDG_DATA_HOME environment variables.

Next steps

Continue reading to learn more about: