---
title: AI Tools
description: Varlock is purpose-built for the AI era — your schema gives agents full context, your secrets never touch AI servers
---
import { TabItem, Tabs } from "@astrojs/starlight/components";

Varlock is purpose-built for the AI era. Your `.env.schema` gives AI agents full context on your configuration — variable names, types, validation rules, descriptions — while your secret values never leave your machine or touch AI servers.

This solves two critical problems with AI-assisted development:

1. **Secret exposure** — AI tools read your project files, including `.env` files. With varlock, secrets are never stored in plain text — they're fetched at runtime from secure providers.
2. **AI-generated leaks** — AI agents may hardcode secrets or log sensitive values in generated code. `varlock scan` catches these leaks before they're committed, and runtime protection redacts secrets from logs and responses.

## Securely inject secrets into AI CLI tools

Many AI coding assistants offer CLI tools that require API keys and other secrets. Instead of storing these secrets in plain text `.env` or `.json` files or exposing them in your shell history, use `varlock` to inject them securely at runtime. This applies both to config that might be required to bootstrap the tool itself, as well as things like [MCP servers](/guides/mcp/) that require API keys.

### 1. Install varlock

If you haven't already, [install varlock](/getting-started/installation/) on your system.

### 2. Create an environment schema

Define your API keys and secrets in your `.env.schema` file. Mark sensitive values appropriately:

```env-spec title=".env.schema"
# @sensitive @required
OPENAI_API_KEY=exec('op read "op://api-local/openai/api-key"')

# @sensitive @required
ANTHROPIC_API_KEY=exec('op read "op://api-local/anthropic/api-key"')

# @sensitive @required
GOOGLE_API_KEY=exec('op read "op://api-local/google/api-key"')
```

Store the actual secret values in your preferred [secrets provider](/guides/secrets-providers) like 1Password (as shown above), AWS Secrets Manager, or any other provider with a CLI to fetch invidual secrets.

:::tip
You can use any secrets provider you want, but we like 1Password since it uses biometric authentication for local access. All the examples in this guide use 1Password as a means of showing more real world examples.
:::

### 3. Run your tool via `varlock run`

Execute your AI CLI tool through `varlock` to securely inject the environment variables:

```bash
varlock run -- <your-cli-command>
```

### Popular AI CLI tool examples

Here's how to configure and run popular AI coding CLI tools with varlock:

<Tabs>
  <TabItem label="Claude">
    [Claude Code](https://docs.claude.com/en/docs/claude-code/overview) is Anthropic's CLI tool for AI-assisted coding.

    **Environment variable:**
    - `ANTHROPIC_API_KEY` - Your Anthropic API key

    **Add to `.env.schema`:**
    ```env-spec
    # @sensitive @required
    ANTHROPIC_API_KEY=exec('op read "op://api-local/anthropic/api-key"')
    ```

    **Run with varlock:**
    ```bash
    varlock run -- claude
    ```

    See supported env variables [here](https://docs.claude.com/en/docs/claude-code/settings#environment-variables).
  </TabItem>

  <TabItem label="Opencode">
    [Opencode](https://opencode.ai/) is a provider-agnostic AI coding assistant that works in your terminal.

    **Environment variables:**
    - `ANTHROPIC_API_KEY` - For Claude models
    - `OPENAI_API_KEY` - For OpenAI models
    - `OPENCODE_CONFIG` - Path to custom config file (optional)

    **Add to `.env.schema`:**
    ```env-spec
    # @sensitive @required
    ANTHROPIC_API_KEY=exec('op read "op://api-local/anthropic/api-key"')
    
    # @sensitive
    OPENAI_API_KEY=exec('op read "op://api-local/openai/api-key"')
    ```

    **Add an auth configuration:**
    ```bash
    opencode auth login
    ```
    It will ask you to paste your API key. Instead, paste in an `env reference` like this:

    `{"env:ANTHROPIC_API_KEY"}`

    Your config file (`~/.local/share/opencode/auth.json`) should now look like this:

    ```json title="~/.local/share/opencode/auth.json"
    {
      "anthropic": {
        "type": "api",
        "key": "{env:ANTHROPIC_API_KEY}"
      }
    }
    ```
    **Run with varlock:**
    ```bash
    varlock run -- opencode
    
    # or with specific model
    varlock run -- opencode --model claude-3-5-sonnet
    ```

    See the [Opencode docs](https://opencode.ai/docs/) for more information.
  </TabItem>

  <TabItem label="Gemini">
    [Gemini CLI](https://github.com/google-gemini/gemini-cli) is Google's open source AI agent.

    **Environment variable:**
    - `GOOGLE_API_KEY` or `GEMINI_API_KEY` - Your Google AI API key

    **Add to `.env.schema`:**
    ```env-spec
    # @sensitive @required
    GOOGLE_CLOUD_PROJECT=exec('op read "op://api-local/google/cloud-project"')
    
    # @sensitive @required
    GOOGLE_API_KEY=exec('op read "op://api-local/google/api-key"')
    ```

    **Run with varlock:**
    ```bash
    varlock run -- gemini
    ```

    See the [Gemini CLI auth docs](https://github.com/google-gemini/gemini-cli/blob/main/docs/get-started/authentication.md) for more information.
  </TabItem>
</Tabs>

---

## Allowing schema files for AI tools

Most AI tools ignore `.env.*` files by default. To ensure your AI tool can access your environment schema, add the following to your `.gitignore`:

```txt
!.env.schema
```

If you use a tool with its own ignore file, check that tool's documentation to see how it handles ignore files and make sure `.env.schema` is allowed.

## Custom instructions and rules

To give your AI tool full context about `varlock`, you can provide it with the [full Varlock `llms.txt`](https://varlock.dev/llms-full.txt). In Cursor, this is accomplished via 'Add New Custom Docs'. 

If your tool supports custom rules, you can use our own varlock [Cursor rule file from this repo](https://github.com/dmno-dev/varlock/blob/main/.cursor/rules/varlock.mdc) as a starting point to create your own that is most suited to your workflow. 

## Scan for leaked secrets

AI agents can sometimes hardcode secret values or leak them into generated code. Use `varlock scan` to proactively detect leaked secrets in your codebase:

```bash
# Scan the current directory for leaked secret values
varlock scan

# Scan specific paths
varlock scan ./src ./config
```

You can also set up `varlock scan` as a git pre-commit hook to automatically catch leaks before they're committed:

```bash
# Add to your .git/hooks/pre-commit or use a hook manager like husky/lefthook
varlock scan --staged
```

This is especially valuable when working with AI coding tools — the scan command compares your resolved secret values against your codebase to find any that may have been accidentally included in plain text.

## Varlock Docs MCP

We also have a docs MCP server that allows you to search the Varlock docs. See more details [here](/guides/mcp/#docs-mcp).

