Hermetic
Documentation
Hermetic runs scripts in isolated cloud VMs. Pipe any script to the CLI and it executes on a fresh EC2 instance, streaming logs back in real time.
Quick Start
Install
curl -fsSL https://hermetic.sh/install.sh | bash
Login
hermetic login
Run a command
echo "python3 -c 'print(1+1)'" | hermetic
CLI Reference
hermetic login
Authenticate via browser-based device flow. Opens your browser to approve the CLI.
| Flag | Default | Description |
|---|---|---|
| --endpoint | — | Custom server endpoint URL |
| --token | — | Manually set an API token instead of browser login |
hermetic run
Execute a script on a cloud VM. Reads from stdin, uploads inputs, runs the script, and streams logs back.
| Flag | Default | Description |
|---|---|---|
| --cloud | aws | Cloud provider for the VM |
| --instance | t3.micro | EC2 instance type |
| --timeout | — | Max job duration in seconds (default: server-side timeout) |
| --snapshot | — | Create a snapshot after the run, or use an existing snapshot ID |
| --sync | — | Sync a local directory to the VM — available as a relative path in $HERMETIC_SYNC_DIR (repeatable) |
| --endpoint | — | Custom server endpoint URL |
| --token | — | API token (overrides config file) |
| --verbose | false | Enable debug output |
When no subcommand is given, hermetic defaults to run with --cloud aws --instance t3.micro.
hermetic interactive
Launch an interactive SSH session on a cloud VM for debugging or exploratory work.
| Flag | Default | Description |
|---|---|---|
| --cloud | aws | Cloud provider for the VM |
| --instance | t3.micro | EC2 instance type |
| --max-duration | 3600 | Max session duration in seconds |
| --endpoint | — | Custom server endpoint URL |
| --token | — | API token (overrides config file) |
Environment Variables
| Variable | Purpose | Overrides |
|---|---|---|
| HERMETIC_BASE_URL | Server endpoint URL | Config file endpoint |
| HERMETIC_API_TOKEN | API auth token | Config file token |
Config files are stored at ~/.config/hermetic/ (token, endpoint).
Full Help Output
Show hermetic --help
Hermetic CLI
Usage: hermetic-linux-amd64 [OPTIONS] [COMMAND]
Commands:
login Login via browser
run Run a script from stdin
interactive Launch an interactive cloud session
help Print this message or the help of the given subcommand(s)
Options:
--verbose Enable debug output
-h, --help Print help
-V, --version Print version
Examples
Pipe a script
echo "apt-get update && echo done" | hermetic
Run a script file
cat train.sh | hermetic run --instance g4dn.xlarge --timeout 3600
Sync local directories
Upload local directories to the remote VM before your script runs. Your script's working directory is automatically set to a temp folder containing the synced directories. Reference them by name:
# Sync one directory — script starts in the sync folder echo "ls myproject/" | hermetic run --sync ./myproject # Sync multiple directories echo "cd src && make test" | hermetic run --sync ./src --sync ./config --instance t3.large
How it works: Synced directories are extracted into $HERMETIC_SYNC_DIR/ (a temp directory), and your script's cwd is set there automatically. So --sync ./myproject means myproject/ is available as a relative path. Do not use ~/myproject — the files are not placed in the home directory.
Snapshots
Create a snapshot of the VM state after a run, then reuse it for subsequent jobs:
# Create a snapshot (installs deps, saves state) echo "pip install torch numpy" | hermetic run --snapshot # Reuse the snapshot for a fast follow-up run echo "python3 train.py" | hermetic run --snapshot snap_abc123
Combine sync + snapshots
Sync your code and snapshot the environment for iterative development:
# First run: sync code + create snapshot with deps installed echo "cd src && pip install -r requirements.txt && python train.py" | hermetic run --sync ./src --snapshot # Subsequent runs: sync updated code + reuse snapshot (skip pip install) echo "cd src && python train.py" | hermetic run --sync ./src --snapshot snap_abc123
Interactive sessions
hermetic interactive --instance t3.medium --max-duration 7200