Secret Files
Secret files deliver small sensitive files (TLS private keys, client certificates, licence files, API credentials) to devices without baking them into a container image or putting them in environment variables.
- Attach a file to a configuration to deliver it to every device running that configuration, whatever its version.
- Attach a file to a single device to give that device its own copy. A device file at the same path overrides the configuration's file.
File contents can never be read back from the dashboard or API after upload. Only metadata is shown.
Adding a Secret File
To a configuration: open the configuration editor and expand Secret Files.
To a device: open the device, select Configuration, and scroll to the Secret files card. It lists Device files and, below them, the files inherited From configuration (which can only be removed from the configuration).
In Add or replace a file:
| Field | Description |
|---|---|
| File | Up to 64 KB. Empty files are rejected. |
| Destination path | Absolute path on the device, for example /admrl/secrets/tls.key. Uploading to an existing path replaces that file. |
| Mode | Octal permissions, default 0600. |
| UID / GID | File owner, default 0 (root). |
Click Save file. Each file is listed with its path, mode, owner, size, a short SHA-256 fingerprint, when it was last updated, and its delivery status:
| Status | Meaning |
|---|---|
| On device | The device has written the file. |
| Pending | Waiting for the device to receive it. |
| Failed | The device could not write the file; the error is shown. |
| Overridden | A device file at the same path replaces this configuration file. |
Where Files Appear in the Workload
Choose the destination path based on who needs to read the file:
| Destination | Visible to the workload? | Notes |
|---|---|---|
/admrl/secrets/... | Yes, at the same path, read-only | Recommended. Mounted into every workload regardless of read-only or ephemeral root settings. Updates appear live without a restart. |
/admrl/volumes/<volume>/... | Yes, wherever that Custom Volume is mounted | Use when the application expects the file inside its data volume. |
Any other allowed path (for example /etc/myapp/key.pem) | No | Written to the host operating system only. |
Files under /admrl/secrets are stored on the device's encrypted data partition (where the hardware supports encryption, see Device Security) and mounted into the workload read-only, with no executable, setuid, or device-node permissions.
A rotated file appears in /admrl/secrets without restarting the workload. Your application must re-read the file (or watch it) to pick up the new value.
Paths That Are Not Allowed
Paths must be absolute and canonical (no .., backslashes, or control characters), up to 1,024 bytes. These locations are refused:
/proc,/sys,/dev,/boot,/app,/bin,/sbin,/lib,/lib64,/usr,/run,/tmp/etc/passwd,/etc/shadow,/etc/group,/etc/gshadow,/etc/sudoers(andsudoers.d),/etc/ld.so.*,/etc/fstab,/etc/mtab, and other system boot files- Anything under
/admrlother than/admrl/secrets/and/admrl/volumes/
The mode must let the owner read the file, must not be group- or world-writable, and must not set setuid, setgid, or sticky bits.
Delivery and Lifecycle
- Device files are pushed to the device shortly after you save them.
- Configuration files arrive with the device's next configuration update.
- Files are written atomically: if a write fails, the previous file stays intact.
- A file is only rewritten when its contents change; ownership or permission drift is corrected in place.
- Deleting a file in the dashboard removes it from the device.
- If a device rejects or rolls back a configuration, that configuration's files are not applied.
- Deleting a configuration deletes its secret files. Removing a device from your organisation deletes its device files, so a re-claimed device never receives them.
- Unpairing or factory-resetting a device wipes every secret file from it.
Security
- Secret files are encrypted at rest in Admiral Cloud and decrypted only to send them to the device they belong to.
- They travel over the device's authenticated, encrypted Admiral Mesh connection.
- Contents are never logged, never shown in the dashboard, excluded from the audit log, and excluded from configuration version history.
- Uploading or deleting requires editor access to the configuration or device; listing requires viewer access.
Limits
| Limit | Value |
|---|---|
| File size | 64 KB |
| Files per configuration or per device | 32 |
| Total size per configuration or per device | 512 KB |
API
| Endpoint | Purpose |
|---|---|
GET /v1/configurations/{configId}/secret-files | List a configuration's files (metadata only). |
POST /v1/configurations/{configId}/secret-files | Upload or replace a file. |
DELETE /v1/configurations/{configId}/secret-files/{fileId} | Delete a file. |
GET|POST /v1/devices/{deviceId}/secret-files | List or upload device files. |
DELETE /v1/devices/{deviceId}/secret-files/{fileId} | Delete a device file. |
curl -sS -X POST https://api.admrl.co/v1/devices/$DEVICE_ID/secret-files \
-H "Authorization: Bearer $ADMIRAL_TOKEN" -H "X-Organization-ID: $ADMIRAL_ORG" \
-H "Content-Type: application/json" \
-d '{"path":"/admrl/secrets/tls.key","mode":"0600","uid":0,"gid":0,"content_base64":"'"$(base64 < tls.key | tr -d '\n')"'"}'
A file over the size limit returns 413; exceeding the file-count or total-size limit returns 409.