Amulet
Migration guide 日本語 GitHub
Amulet
Migration guide 日本語 GitHub ↗

Concepts & Fundamentals

v1.0.0 — archived Earlier v0.x (Zig) docs →

Amulet is an archived experiment. This page preserves its original concepts for existing users, but the security boundary and migration guide take precedence. New production use is not recommended.

1. The Terminal: A Window for Dialogue

The terminal (also known as the command line or console) is a gateway to giving direct instructions to your computer using text.

  • macOS / Linux: Terminal.app, zsh, or bash
  • Windows: PowerShell, Command Prompt, or Windows Terminal

Amulet is a CLI (Command Line Interface) tool that runs in this terminal. Instead of clicking buttons with a mouse, you interact with it by typing commands.

2. Disk vs. Memory: The Crucial Difference

To understand security, you must understand where information is stored.

Location Characteristics Security Property
Disk (SSD/HDD) Data remains after power-off (Files) Leaves a "trace". Risk of theft or unintended reading by AI/malware.
Memory (RAM) Temporary workspace used by running processes Reduces persistent storage, but privileged processes, debugging, swap, or host compromise may still expose data.

The Amulet Solution

Many tools store secrets in a .env file on the disk. This is like leaving your keys on a desk without a lock.

Amulet stores secret values in an encrypted vault on disk and emits plaintext when you unseal them. This can reduce accidental at-rest exposure, but the caller, shell, downstream process, swap configuration, or logging can still persist or expose plaintext.

3. "Standard I/O" and "Pipes"

The key to mastering Amulet lies in a traditional Unix/Linux mechanism called "Standard I/O".

  • Standard Input (stdin): The entrance where information is "poured into" a program.
  • Standard Output (stdout): The exit where a program "spits out" its results.

The Pipe |: A Digital Bucket Brigade

In the terminal, you can use the | (pipe) symbol to connect the "exit" of one program directly to the "entrance" of another.

echo -n "my-secret-key" | amulet seal MY_KEY

In this command:

  1. echo outputs the secret string.
  2. Without writing it to a file,
  3. It passes through memory (the pipe) directly into amulet.

This avoids creating a plaintext file in this specific pipeline. It is not a zero-trace guarantee.

4. Note for Windows Users

You can perform the same pipe operations in Windows PowerShell. However, PowerShell handles text encoding differently.

  • Unix-like: echo -n "value" | ...
  • PowerShell: echo "value" | ... (PowerShell may add a newline by default, but Amulet is designed to handle these cases gracefully).

Amulet provides the same stdin/stdout workflow on Windows, subject to the same host and plaintext-output limitations.

5. Amulet's Role in the AI Era

Today, AI assistants like GitHub Copilot and ChatGPT help us write code. While convenient, this introduces a major risk.

"AI models may scan your project's .env files or plaintext secrets and include them in their training data or prompts."

What Amulet Can Reduce

Keeping values encrypted in the vault can reduce accidental commits and exposure to an AI tool that only reads ordinary project files. It does not protect against an agent that can invoke Amulet, inspect the same user session, or access the unlock credential.

Next Steps

If you already use Amulet, read the security boundary and migration guide. The installation page remains only as historical and recovery documentation.