Vortix v0.3.0

May 24, 2026 · View on GitHub

Frequently asked questions about Vortix v0.3.0. For step-by-step upgrade instructions see MIGRATION.md. For a quick overview of what changed see v0.3.0-RELEASE-NOTES.md.

Is the upgrade safe? Will I lose anything?

Yes, safe. The on-disk migration is read-only against your existing .conf / .ovpn / .auth files — vortix writes new sidecar <name>.meta.toml files next to them and never modifies the source configs. The migration is also idempotent: re-running it does nothing when sidecars already exist. If a step fails (read-only profile dir, weird permissions), vortix logs a warning and continues startup unconditionally — no panic, no aborted launch.

Rollback is one command: cargo install vortix --version 0.2.2 --force (or the equivalent for Homebrew / npm). The new sidecars are inert to v0.2.x — you can leave them or delete them.

Will my existing profiles work?

Yes, no flags to change. vortix up <profile>, down, status, list, import, show, delete, rename all behave exactly as on v0.2.x. The new sidecar files appear automatically next to your existing configs the first time you launch v0.3.0; they carry extra metadata (profile_id, display_name, protocol) that future features will use, but nothing today depends on them being there.

If you're curious what was generated:

ls ~/.config/vortix/profiles/
# corp.conf      corp.meta.toml      home.ovpn      home.meta.toml

You can delete the .meta.toml files safely; they regenerate on the next launch.

What happens to my OpenVPN .auth files?

Nothing changes unless you want it to. The OvpnTunnel still reads ${XDG_CONFIG_HOME}/vortix/auth/<profile>.auth on every vortix up exactly as before.

If you'd rather move credentials into the new encrypted secret store:

echo -n 'username:password' | vortix secrets set creds/<profile>
rm ~/.config/vortix/auth/<profile>.auth
vortix up <profile>   # pulls creds from the secret store

The store is opt-in. When you do opt in, vortix tries the OS keyring first (Keychain on macOS, Secret Service on Linux) and falls back to an AES-256-GCM + argon2id encrypted file in ~/.config/vortix/secrets.enc. See MIGRATION.md for more.

Did any of my existing CLI commands change?

No. Every pre-v0.3.0 command (up, down, status, list, import, show, delete, rename, reconnect, killswitch, release-killswitch, info, update, report, completions) is byte-for-byte identical in behavior. Their flags, JSON output keys, exit codes, and help text are unchanged.

What's new is one additional subcommand — vortix secrets {set,get, delete} for the encrypted credential store — plus one new flag, vortix show <profile> --raw --inline-secrets, for sharing a profile with credentials inlined. That's it on the CLI surface.

Internally there's a lot more (Engine FSM, JSONL session journal, layered settings, sidecar migration, layered secret store), but those all live behind existing commands. The session journal path appears in vortix info output; the migration runs at startup; settings are just ~/.config/vortix/settings.toml if you want to override something.

One subtle, additive change in --json output: every envelope now carries a schema_version: 1 field at the top. This is forward compatibility plumbing — your scripts can assert on it or ignore it, both work.

How do I roll back if something breaks?

cargo install vortix --version 0.2.2 --force

Or, depending on how you installed:

# Homebrew (after the tap publishes a pinned version)
brew uninstall vortix && brew install vortix@0.2.2

# npm
npm install -g @harry-kp/vortix@0.2.2

# Shell installer — re-run with explicit version
curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/Harry-kp/vortix/releases/download/v0.2.2/vortix-installer.sh | sh

What happens to v0.3.0 artifacts after rollback:

  • Sidecar .meta.toml files — v0.2.x ignores them entirely. Leave them or delete them.
  • secrets.enc — untouched by v0.2.x. Either keep it for the next upgrade attempt or delete it.
  • sessions/*.jsonl — pure observability data. Safe to delete the whole sessions/ directory.
  • settings.toml — ignored by v0.2.x. Your old config.toml (if any) is untouched.

No file is destructively rewritten by v0.3.0; rollback is genuinely clean.

What's the encrypted secret store and do I have to use it?

You don't have to use it. The store is empty by default and the rest of vortix doesn't touch it unless you explicitly write to it. If you never run vortix secrets set ..., everything else in v0.3.0 works exactly as if the feature didn't exist.

When you do opt in, the store has two layers:

  1. OS keyring — Keychain on macOS, Secret Service on Linux. No passphrase needed when the keyring session is unlocked (which is the normal interactive case).
  2. Encrypted file fallback — ~/.config/vortix/secrets.enc, AES-256-GCM with an argon2id-derived key. Used automatically when no keyring is available (headless Linux without libsecret). The first write prompts for a passphrase.

Typical use:

echo -n 'mypassword' | vortix secrets set creds/work-vpn
vortix secrets get creds/work-vpn    # echoes 'mypassword'
vortix secrets delete creds/work-vpn

The store is plumbed into OpenVPN's auth flow (see "What happens to my .auth files?" above) and reserved for the upcoming 2FA work — issue #191.

Why is vortix logging a "sidecar migration" message at startup?

That's the one-shot backfill creating .meta.toml files next to your existing profiles. It runs at every startup but is idempotent — the message only appears on the first launch (or whenever new .conf / .ovpn files have been added without sidecars).

If the message bothers you, or you're debugging a filesystem permission issue, set the escape-hatch env var:

export VORTIX_SKIP_MIGRATION=1
vortix up work-vpn

The legacy load path is still there; vortix works fine without sidecars. Unset the var when you're done.

Question not here? Open an issue, or — for Linux-specific things — chime in on discussion #184. vortix bug-report is journal-aware as of v0.3.0 and attaches the current session's event log automatically, so the report carries useful context out of the box.