> ## Documentation Index
> Fetch the complete documentation index at: https://www.1password.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Use 1Password's agent hook to validate local .env files from 1Password Environments (beta)

You can use the [1Password local `.env` file validation hook <Icon icon="arrow-up-right-from-square" />](https://github.com/1Password/agent-hooks/blob/main/hooks/1password-validate-mounted-env-files/README.md) with supported IDEs and agents to validate that [locally mounted `.env` files](/environments/local-env-file/) 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

* [1Password subscription](https://1password.com/pricing/password-manager)
* 1Password for [Mac](https://1password.com/downloads/mac) or [Linux](https://1password.com/downloads/linux)
* [`sqlite3` <Icon icon="arrow-up-right-from-square" />](https://sqlite.org/index.html) installed and available in your PATH
* [Claude Code <Icon icon="arrow-up-right-from-square" />](https://code.claude.com/docs/en/overview), [Cursor <Icon icon="arrow-up-right-from-square" />](https://cursor.com/home), [GitHub Copilot <Icon icon="arrow-up-right-from-square" />](https://github.com/features/copilot), or [Windsurf <Icon icon="arrow-up-right-from-square" />](https://windsurf.com/)

<Info>
  **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.
</Info>

## Step 1: Set up your Environments

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

1. [Create one or more Environments](/environments) in 1Password to store your project secrets.
2. [Configure locally mounted `.env` files](/environments/local-env-file) for them.

## Step 2: Install the hook in your project

<Tabs groupId="supported-agents">
  <Tab title="Claude Code">
    To install the 1Password hook for Claude Code, you'll need to:

    1. Clone the [1Password Agent Hooks repository. <Icon icon="github" />](https://github.com/1Password/agent-hooks)
    2. Follow the instructions to [run the install script. <Icon icon="github" />](https://github.com/1Password/agent-hooks/blob/main/README.md#initial-setup)
  </Tab>

  <Tab title="Cursor">
    The 1Password hook is available as a plugin in the Cursor marketplace. To install it:

    1. Open the [Cursor marketplace <Icon icon="arrow-up-right-from-square" />](https://cursor.com/marketplace/1password).
    2. Either select **Sign In To Add** (or **Add** if you're already signed in), or copy `/add-plugin 1password` from the marketplace page and run it in Cursor Agent window to install the 1Password plugin.

    After you install the plugin, restart Cursor and tell the Cursor Agent to perform a task that requires running a shell command. If your `.env` files are properly configured, the command will proceed. Otherwise the Agent will guide you through fixing the issue.

    To confirm the hook worked as expected, open Cursor, then navigate to **Settings** > **Hooks** > **Execution Log**.

    You can also install the hook from the [1Password Agent Hooks repository <Icon icon="github" />](https://github.com/1Password/agent-hooks/).
  </Tab>

  <Tab title="GitHub Copilot">
    To install the 1Password hook for GitHub Copilot, you'll need to:

    1. Clone the [1Password Agent Hooks repository. <Icon icon="github" />](https://github.com/1Password/agent-hooks)
    2. Follow the instructions to [run the install script. <Icon icon="github" />](https://github.com/1Password/agent-hooks/blob/main/README.md#initial-setup)
  </Tab>

  <Tab title="Windsurf">
    To install the 1Password hook for Windsurf, you'll need to:

    1. Clone the [1Password Agent Hooks repository. <Icon icon="github" />](https://github.com/1Password/agent-hooks)
    2. Follow the instructions to [run the install script. <Icon icon="github" />](https://github.com/1Password/agent-hooks/blob/main/README.md#initial-setup)
  </Tab>
</Tabs>

## 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:

```toml .1password/environments.toml theme={null}
mount_paths = ["application.env", "billing.env"]
```

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 <Icon icon="arrow-up-right-from-square" />](https://cursor.com/docs/agent/hooks#hook-events), while in GitHub Copilot it works with the [`preToolUse` event <Icon icon="arrow-up-right-from-square" />](https://docs.github.com/en/copilot/tutorials/copilot-cli-hooks#5-enforce-policies-with-pretooluse).

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

```toml .1password/environments.toml theme={null}
mount_paths = [".env"]
```

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

#### Multiple `.env` files

```toml .1password/environments.toml theme={null}
mount_paths = [".env", "billing.env", "database.env"]
```

Only the three declared `.env` files are validated.

#### No validation

```toml .1password/environments.toml theme={null}
mount_paths = []
```

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](https://github.com/1Password/agent-hooks/tree/main/hooks/1password-validate-mounted-env-files#debugging). <Icon icon="github" />

## Learn more

* [Access secrets from 1Password through local `.env` files](/environments/local-env-file)
* [1Password Agent Hooks repository <Icon icon="github" />](https://github.com/1Password/agent-hooks/)
* [Cursor Hooks <Icon icon="arrow-up-right-from-square" />](https://cursor.com/docs/agent/hooks)
* [GitHub Copilot hooks <Icon icon="arrow-up-right-from-square" />](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/coding-agent/use-hooks)