Vault dev mode server with launchd

vault-dev-mode-launchd.md

Vault dev mode server with launchd

Here's how to control the Vault binary on macOS using native process management provided by launchd and launchctl.

Tip

Apple advises against using deprecated load and unload verbs in launchctl, and you can encounter warnings or errors when you use them.

Create a property list

To run a process under launchd, you must first create a property list or .plist file that describes the process, arguments, and so on.

Create the property list that defines launching a Vault dev mode server in your user's Library/LaunchAgents folder, and name it com.hashicorp.vault.plist.

Note

This example uses the default vault binary location for an Apple Silicon Mac and Vault installed with HomeBrew. If your vault binary lives somewhere else, then update the <string>/opt/homebrew/bin/vault</string> line with the full path to the binary file.

cat > "$HOME"/Library/LaunchAgents/com.hashicorp.vault.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.hashicorp.vault</string>
    <key>ProgramArguments</key>
    <array>
        <string>/opt/homebrew/bin/vault</string>
        <string>server</string>
        <string>-dev</string>
        <string>-dev-root-token-id=root</string>
        <string>-dev-tls</string>
    </array>
    <key>RunAtLoad</key>
    <false/>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/tmp/vault.startup.log</string>
    <key>StandardErrorPath</key>
    <string>/tmp/vault.operations.log</string>
</dict>
</plist>
EOF

Bootstrap and launch Vault dev mode service

Before you can launch the service, you must bootstrap the service property list with launchctl.

launchctl bootstrap ~/Library/LaunchAgents/com.hashicorp.vault.plist

Launch the service.

launchctl start com.hashicorp.vault

When the Vault dev mode server launches, the server operates with the following important environment details:

• Initial root token value: root
• Server startup log messages: /tmp/vault.startup.log.
• Server operational log messages: /tmp/vault.operations.log.

1. Check the Vault server startup messages for important environment variables.

   tail -n 15 /tmp/vault.startup.log | head -n 5

2. Export the environment variables suggested by the startup message output.

   export VAULT_ADDR='https://127.0.0.1:8200' \
   VAULT_CACERT='/var/folders/4_/_c0ff33n3rd80q2q_nqj_8675309gn/T/vault-tls977551709/vault-ca.pem'

3. Get the Vault server status.

   vault status

   Example output:

   Key             Value
   ---             -----
   Seal Type       shamir
   Initialized     true
   Sealed          false
   Total Shares    1
   Threshold       1
   Version         1.21.0
   Build Date      2025-10-21T19:33:18Z
   Storage Type    inmem
   Cluster Name    vault-cluster-1ed832c8
   Cluster ID      7392bf0d-f5c6-8440-fb69-6842b18c96bd
   HA Enabled      false
   

If you need to check the operational log message at any time:

tail /tmp/vault.operations.log

When you finish running the Vault service, you can stop it.

launchctl stop com.hashicorp.vault

Make it super handy

You can create a shell function named devmode that launches the Vault dev mode server service and prints the environment variables; this is a zsh example:

devmode() {
    case "$1" in
        start)
            launchctl start com.hashicorp.vault
            tail -n 15 /tmp/vault.startup.log | head -n 5
            ;;
        stop)
            launchctl stop com.hashicorp.vault
            echo "Vault stopped."
            ;;
        *)
            # Default to start if no argument or invalid argument
            launchctl start com.hashicorp.vault
            tail -n 15 /tmp/vault.startup.log | head -n 5
            ;;
    esac
}

Then you can just devmode start and devmode stop to manage the server.

Removal

If you need to remove the service, stop it first, and remove it with:

launchctl bootout ~/Library/LaunchAgents/com.hashicorp.vault.plist

References

• Script management with launchd in Terminal on Mac