Skip to main content

Use 1Password's agent hook to validate local .env files from 1Password Environments

You can use the 1Password local .env file validation hook with supported IDEs and agents to validate that locally mounted .env files from 1Password Environments are properly set up before the agent executes shell commands. If any required .env files are missing or invalid, the hook prevents the agent from executing and the agent provides instructions for how to fix the issue.

The hook currently supports Claude Code, Cursor, GitHub Copilot, and Windsurf.

Requirements​

Windows not supported

Local .env files for 1Password Environments are currently only supported on Mac and Linux. If you're on Windows, the hook will skip the validation checks.

Step 1: Set up your Environments​

To use the hook, you'll first need to:

  1. Create one or more Environments in 1Password to store your project secrets.
  2. Configure locally mounted .env files for them.

Step 2: Install the hook in your project​

To install the 1Password hook for Claude Code, you'll need to:

  1. Clone the 1Password Agent Hooks repository.
  2. Follow the instructions to run the install script.

Step 3: Choose how you want the hook to validate your .env files​

Default mode​

By default, the hook will check the 1Password desktop app to find .env files related to your project based on the file path destinations you configured in 1Password Environments.

Configured mode​

Alternatively, you can create a .1password/environments.toml file at the root of your project that specifies which locally mounted .env files to validate. The hook only validates the specified files.

To do this, the hook parses the TOML file to extract mount paths from the mount_paths array field. Mount paths can be relative to the project root or absolute. For example:

.1password/environments.toml

The mount_paths field must be explicitly defined in the TOML file. If the file exists but doesn't contain a mount_paths field, the hook will log a warning and fall back to default mode.

If no .env files are specified in the TOML file, all commands will be allowed to run.

How it works​

1Password hooks are custom scripts that run before or after specific stages of the agent loop. Each hook runs as a spawned process that communicates with the agent over standard input and output using JSON in both directions. Hooks can observe, block, or modify the agent’s behavior as it runs.

The 1Password local .env file validation hook is designed to be used with the event that runs before command execution in your agent. When configured, the hook prevents the agent from proceeding when required environment files are not available. For example, in Cursor the hook works with the beforeShellExecution event , while in GitHub Copilot it works with the preToolUse event .

When the agent tries to run a command, the hook first checks for a .1password/environments.toml file in the current project directory. If a TOML file exists and contains the required mount_paths field, the agent validates only the specified .env files. If no TOML file exists, the agent queries the 1Password desktop app for all .env files mounted in the project directory. The hook then confirms that each .env file discovered for the project is enabled, the mount file exists, and the file is a valid FIFO (named pipe).

If all required .env files are enabled and configured correctly, the command execution is allowed to proceed. If one or more required .env files are missing, disabled, or invalid, the hook prevents the agent from proceeding and the agent provides an error message with steps to fix the issue.

The hook uses a "fail open" approach in default mode. If it can't access the 1Password database, the hook logs a warning and allows subsequent commands to proceed. This makes sure development can proceed if the 1Password app is not installed or the database is unavailable. Similarly, if a TOML file exists but no .env files are specified, the command is allowed to proceed.

Configuration examples​

Single .env file

.1password/environments.toml

Only .env is validated. Other environment files are ignored.

Multiple .env files

.1password/environments.toml

Only the three declared .env files are validated.

No validation

.1password/environments.toml

No .env files are validated. All commands are allowed.

Default mode

No .1password/environments.toml file exists or the mount_paths field has been improperly defined. The hook discovers and validates all mounts configured in 1Password that are within the project directory.

Troubleshooting​

The hook logs information to /tmp/1password-hooks.log for troubleshooting. Check this file if you encounter issues.

Log entries include timestamps and detailed information about:

  • Database queries and results
  • Mount validation checks
  • Permission decisions
  • Error conditions

Learn more about troubleshooting agent hooks.

Learn more​

Was this page helpful?