Reference

Storage & errors

Filesystem layout, the error reporter, and how failures are handled.

Storage layout

All state lives under ~/.phelix/:

~/.phelix

~/.phelix/├── apps.json              # registry of all managed apps├── master.key             # AES-256-GCM master key for env encryption (0600)├── session.json           # auth session├── config.json            # server configuration├── proxy.sock             # proxy daemon control socket├── proxy-state.json       # persisted proxy enrollment + active targets├── logs/│   ├── phelix.log         # Phelix's own log│   ├── <app>.log          # per-app logs│   └── deploy_*.log       # deploy instance logs├── registry/<slug>.enc    # encrypted registry credentials├── matrix/│   └── runs/              # Matrix Run history: <id>.json records,│                          #   <id>.lock execution locks, <id>.manifest.json│                          #   release manifests (see Matrix runs)├── webhook/│   ├── deliveries.json    # delivery dedup ledger (512 most recent deliveries)│   ├── worktrees/         # isolated Git sources, removed after jobs / swept at startup│   └── jobs/              # durable wh_<id>.json records (200 most recent finished jobs)└── apps/<AppName>/        # per-app data    ├── versions.json      # version metadata index (incl. per-version build reports    │                      #   and per-combination matrix reports)    ├── deploy.json        # blue-green / rolling state    ├── rollback.log       # rollback audit trail    ├── rollback_history.jsonl   # structured rollback history (JSON Lines)    ├── current -> builds/vN   # symlink to the active build    ├── builds/vN/binary   # versioned binaries    └── env/vN.enc         # per-version encrypted env snapshot

Build-report metadata lives inside versions.json (the build_report field per version) - there is no separate build database, and everything works offline.

Retention

The last five versions are kept by default (configurable per plan). The active version is never pruned, even when it falls outside the configured window.

Error handling

Errors are rendered once, on stderr, with a short code, the message, and an actionable hint. Successful output stays on stdout and is never polluted with error text.

Failure	Behavior
Authentication	Prompt to run phelix auth login; build/run never require it
Build	Show the failing stage, a hint, and the wrapped root-cause chain on stderr - no --debug required
Connection	Log and retry automatically
Server communication	Handle gracefully without crashing the CLI
Deployment health	Abort and keep serving the active version

Root causes are always preserved: wrapped errors stay reachable through errors.Is / errors.As, so os.IsNotExist, exec.ExitError, and gRPC status.Code still work on the underlying cause.

Error reporter

For a small registry of known, recognizable problems, Phelix adds an explanation, a concrete suggested fix, a real command you can run yourself, and a documentation link on top of the usual error line. The error code, exit code, and root-cause chain are unchanged - the reporter only adds context.

Problem	Example guidance
Missing Go toolchain (TOOLCHAIN_NOT_FOUND)	Platform-appropriate install command (via Phelix's package-manager detection: sudo apt-get ... / sudo dnf ... / brew install go / winget ...), docs at go.dev/doc/install
Missing Rust toolchain (TOOLCHAIN_NOT_FOUND)	rustup install command, docs at rust-lang.org/tools/install
Port already in use (PORT_UNAVAILABLE)	Names the listening process and PID when the OS can tell (read-only lsof lookup), a read-only inspection command, and the --port alternative. Phelix never stops the process for you
go.mod problems (BUILD_FAILED)	go mod init for a missing go.mod, go mod tidy for go.sum drift or undeclared dependencies, manual-fix guidance for malformed go.mod, cache-clear guidance for checksum mismatches - each only for the specific condition it matches

Example (a go.mod with an unknown directive):

Output

Error: build failed  Code: BUILD_FAILED   Invalid go.mod   go.mod could not be parsed - it likely contains a syntax error or an  unsupported directive at the line named in the go tool output below.   Suggested fix:  Fix the reported line in go.mod, then build again. Once the file parses,  go mod edit -fmt reformats it.  Documentation:    https://go.dev/ref/mod   Tool output (most recent lines):    go: errors parsing go.mod:    go.mod:5: unknown directive: toolchainx

Suggested commands are informational only - Phelix never executes them for you, and every rendered string (including captured compiler output) passes through the same secret redactor as the rest of the error path.

Debugging failures

Pass --debug to any command to render the complete error chain on stderr. Normal mode bounds the chain to the first few wrapped layers; --debug lifts that cap. It never discloses secrets: every rendered string is run through secret redaction in both normal and debug mode.