Varlock

https://varlock.dev
Admin
Varlock provides AI-safe .env files, offering a single source of truth for schemas that allow AI...
Tokens:529,394
Snippets:4,525
Trust Score:7.1
Update:1 week ago
Show doc for...
Tokens:
Raw
### Run varlock init setup wizard

Source: https://varlock.dev/getting-started/installation

Run the setup wizard to help you get started with varlock.

```bash
varlock init
```

--------------------------------

### varlock install-plugin examples

Source: https://varlock.dev/reference/cli/project

Two example invocations: installing a plugin at an exact version and installing a scoped package.

```bash
# Install a plugin at an exact version
varlock install-plugin my-plugin@1.2.3


# Scoped package
varlock install-plugin @my-scope/my-plugin@2.0.0
```

--------------------------------

### varlock init

Source: https://varlock.dev/reference/cli/project

Starts an interactive onboarding process to help you get started. Will help create your .env.schema and install varlock as a dependency if necessary.

```APIDOC
## varlock init

### Description
Starts an interactive onboarding process to help you get started. Will help create your `.env.schema` and install varlock as a dependency if necessary.

### Usage
```
varlock init [options]
```

### Options
- `--agent`: Run non-interactively for agent/automation workflows. Skips confirmation prompts and uses deterministic defaults for schema generation.

### Examples
```
# Interactive setup wizard
varlock init

# Non-interactive setup for AI agents
varlock init --agent
```
```

--------------------------------

### Start the broker: create Modal sandbox, install varlock, upload schema, start proxy

Source: https://varlock.dev/sandboxes/modal

Creates a Modal sandbox running 'sleep infinity', installs varlock via curl, uploads .env.schema, and starts the proxy with --expose, --persist-ca, and --allow-reload. Uses a shared PROXY_TOKEN and a Secret for bootstrap values. Waits until the proxy port responds.

```python
import os, secrets, urllib.parse
import modal


PROXY_PORT = 8080
VARLOCK = "/root/.config/varlock/bin/varlock"
PROJ = "/root/proj"


# One data-plane token, shared by the broker and every agent; generate it
# yourself (or let the broker mint one and read it back with `varlock proxy
# token`). It is the credential to USE the broker over the tunnel, not to read
# its secrets.
PROXY_TOKEN = secrets.token_hex(16)


app = modal.App.lookup("my-agents", create_if_missing=True)
image = modal.Image.debian_slim().apt_install("curl", "ca-certificates")


broker = modal.Sandbox.create(
    "sleep", "infinity",
    app=app, image=image, workdir=PROJ,
    encrypted_ports=[PROXY_PORT],
    timeout=60 * 60,
)


broker.exec("bash", "-lc",
    f"mkdir -p {PROJ} && curl -sSfL https://varlock.dev/install.sh | sh -s").wait()


# upload the schema (plus any other .env files your project loads);
# real values arrive via secrets below instead
with open(".env.schema") as f:
    broker.filesystem.write_text(f.read(), f"{PROJ}/.env.schema")


# Schema keys resolve from the process env, so this Secret carries the
# bootstrap: usually just your plugin's secret-zero (shown: a 1Password
# service account).
broker_secrets = [modal.Secret.from_dict({
    "VARLOCK_PROXY_TOKEN": PROXY_TOKEN,
    "OP_SERVICE_ACCOUNT_TOKEN": os.environ["OP_SERVICE_ACCOUNT_TOKEN"],
})]


# start the proxy bound off-loopback so the tunnel is reachable. --persist-ca
# reuses the CA across broker restarts, so agents that already trust it keep
# working. --allow-reload lets you apply schema edits later without a restart;
# the reload channel is only reachable from inside the broker, not by agents.
broker.exec("bash", "-lc",
    f"cd {PROJ} && setsid nohup {VARLOCK} proxy start --expose --port {PROXY_PORT} "
    f"--cert-dir {PROJ}/.varlock-ca --persist-ca --allow-reload "
    f"> /root/proxy.log 2>&1 < /dev/null & echo launched",
    secrets=broker_secrets,
).wait()


# ready once the port answers (a bare GET returns 400, which is fine; we only
# need the listener up, so no -f)
broker.exec("bash", "-lc",
    f"until curl -s -o /dev/null --proxy '' http://127.0.0.1:{PROXY_PORT}; do sleep 0.3; done",
).wait()


broker_url = broker.tunnels()[PROXY_PORT].url
broker_host = urllib.parse.urlparse(broker_url).hostname

```

--------------------------------

### Install and initialize Bitwarden plugin in .env.schema

Source: https://varlock.dev/plugins/bitwarden

Shows the minimal setup: loading the plugin, initializing with an access token, and defining the token config item. The access token is marked sensitive and internal.

```plaintext
# 1. Load the plugin
# @plugin(@varlock/bitwarden-plugin)
#
# 2. Initialize the plugin - see below for more details on options
# @initBitwarden(accessToken=$BITWARDEN_ACCESS_TOKEN)
# ---


# 3. Add a machine account access token config item
# @type=bitwardenAccessToken @sensitive @internal
BITWARDEN_ACCESS_TOKEN=

```

--------------------------------

### Install and initialize Infisical plugin with machine identity credentials

Source: https://varlock.dev/plugins/infisical

Shows the complete setup: loading the plugin, initializing with project ID, environment, and client credentials, then defining the credential variables. The client secret is marked as sensitive and internal.

```plaintext
# 1. Load the plugin
# @plugin(@varlock/infisical-plugin)
#
# 2. Initialize the plugin - see below for more details on options
# @initInfisical(
#   projectId=your-project-id,
#   environment=dev,
#   clientId=$INFISICAL_CLIENT_ID,
#   clientSecret=$INFISICAL_CLIENT_SECRET
# )
# ---


# 3. Add machine identity credentials
# @type=infisicalClientId
INFISICAL_CLIENT_ID=


# @type=infisicalClientSecret @sensitive @internal
INFISICAL_CLIENT_SECRET=
```

--------------------------------

### varlock init usage

Source: https://varlock.dev/reference/cli/project

Shows the basic usage syntax for the `varlock init` command. It starts an interactive onboarding process to help create `.env.schema` and install varlock as a dependency if necessary.

```bash
varlock init [options]

```

--------------------------------

### @example example

Source: https://varlock.dev/reference/item-decorators

Shows how to provide an example value for an item, avoiding placeholder values that are not meant to be used.

```plaintext
# @example="sk-abc123"
SECRET_KEY=

```

--------------------------------

### Boot normally

Source: https://varlock.dev/integrations/elysia

Starts the server. The image needs nothing else: no `.env` files, no `node_modules`, and no varlock CLI.

```bash
bun server.js
```

--------------------------------

### Install @varlock/vite-integration with npm

Source: https://varlock.dev/llms-full.txt

First step of the Vite integration setup for TanStack Start deployments other than Cloudflare Workers. Installs the @varlock/vite-integration package using npm.

```bash
npm install @varlock/vite-integration
```

--------------------------------

### varlock init examples

Source: https://varlock.dev/reference/cli/project

Examples of running `varlock init` interactively and with the `--agent` flag for non-interactive automation workflows.

```bash
# Interactive setup wizard
varlock init


# Non-interactive setup for AI agents
varlock init --agent

```

--------------------------------

### Install @varlock/expo-integration and varlock with vlt

Source: https://varlock.dev/integrations/expo

Install the required packages using vlt. This is an alternative to npm for the first setup step.

```bash
vlt install @varlock/expo-integration varlock
```

--------------------------------

### @initPass() usage examples

Source: https://varlock.dev/plugins/pass

Shows how to initialize the pass plugin with optional arguments: storePath, namePrefix, and id. The examples are commented out, indicating they are configuration directives.

```plaintext
# Default setup
# @initPass()


# Custom store location
# @initPass(storePath=/path/to/store)


# With prefix and ID
# @initPass(id=prod, namePrefix=production/)
```

--------------------------------

### Install @varlock/expo-integration and varlock with yarn

Source: https://varlock.dev/integrations/expo

Install the required packages using yarn. This is an alternative to npm for the first setup step.

```bash
yarn add @varlock/expo-integration varlock
```

--------------------------------

### Load and initialize the Akeyless plugin

Source: https://varlock.dev/plugins/akeyless

Shows the minimal setup in a .env.schema file: load the plugin with @plugin and initialize it with @initAkeyless, referencing environment variables for credentials.

```plaintext
# 1. Load the plugin
# @plugin(@varlock/akeyless-plugin)
#
# 2. Initialize the plugin - see below for more details on options
# @initAkeyless(accessId=$AKEYLESS_ACCESS_ID, accessKey=$AKEYLESS_ACCESS_KEY)
```

--------------------------------

### Install @varlock/expo-integration and varlock with bun

Source: https://varlock.dev/integrations/expo

Install the required packages using bun. This is an alternative to npm for the first setup step.

```bash
bun add @varlock/expo-integration varlock
```

--------------------------------

### Load and initialize the plugin

Source: https://varlock.dev/plugins/hashicorp-vault

Shows the minimal setup: loading the plugin and initializing it with a Vault URL. The @initHcpVault() call accepts options for authentication and other settings.

```plaintext
# 1. Load the plugin
# @plugin(@varlock/hashicorp-vault-plugin)
#
# 2. Initialize the plugin - see below for more details on options
# @initHcpVault(url="https://vault.example.com:8200")
```

--------------------------------

### Install @varlock/expo-integration and varlock with pnpm

Source: https://varlock.dev/integrations/expo

Install the required packages using pnpm. This is an alternative to npm for the first setup step.

```bash
pnpm add @varlock/expo-integration varlock
```

--------------------------------

### Proxy rule with approval, keys, substituteIn, and rules options

Source: https://varlock.dev/llms-full.txt

Example rule configuration using the `approval`, `keys`, `substituteIn`, and `rules` options. `approval=true` holds matching requests for an interactive yes/no in the `proxy start` terminal; a one-shot `proxy run` denies them. `substituteIn` defaults to `header` and supports `header:<name>`, `path`, `query`, `query:<param>`, or `body:<path>`; `body:*` allows anywhere. `rules` entries share the rule's `domain` and may set `path`/`method`/`block`/`approval`/`substituteIn` but not `domain`/`keys`.

```text
approval=true
```

```text
keys=[OTHER_KEY]
```

```text
[header, "body:client_secret"]
```

```text
rules=[{path="/v1/**", block=true}]
```

--------------------------------

### akeylessAccessId data type example

Source: https://varlock.dev/plugins/akeyless

Define an environment variable with the akeylessAccessId type. The value must start with 'p-' to be valid.

```bash
# @type=akeylessAccessId
AKEYLESS_ACCESS_ID=
```

--------------------------------

### varlock scan examples

Source: https://varlock.dev/reference/cli/project

Examples of using `varlock scan` with various options and path arguments, including scanning staged files, including gitignored files, scanning build output, using specific schema entry points, and installing as a pre-commit hook.

```bash
# Scan all non-gitignored files in the current directory
varlock scan


# Only scan staged git files
varlock scan --staged


# Scan all files, including gitignored ones
varlock scan --include-ignored


# Scan a specific build output directory (e.g. to check for leaked secrets before publishing)
varlock scan ./dist


# Scan multiple directories
varlock scan ./dist ./public


# Scan files matching a glob pattern
varlock scan './dist/**/*.js'


# Use a specific .env file as the schema entry point
varlock scan --path .env.prod


# Use multiple schema entry points
varlock scan -p ./envs -p ./overrides


# Set up as a git pre-commit hook
varlock scan --install-hook

```

--------------------------------

### @import() basic examples

Source: https://varlock.dev/guides/import

Shows the basic syntax for importing a specific file, a directory, specific keys via pick, and a file from the home directory.

```plaintext
# @import(./.env.imported)                 # import specific file
# @import(./env-dir/)                      # import directory
# @import(./.env.partial, pick=[K1, K2])   # import specific keys
# @import(~/.env.shared)                   # import from home directory
```

--------------------------------

### .env.schema for GitHub token

Source: https://varlock.dev/guides/mcp/local

Example .env.schema file for the Docker-based GitHub MCP server. Defines GITHUB_TOKEN as sensitive, required, and validates it starts with 'ghp_'.

```dotenv
# @defaultSensitive=true
# @defaultRequired=true
# ---


# GitHub token
# @type=string(startsWith="ghp_")
GITHUB_TOKEN=op(op://devTest/myVault/github-token)
```

--------------------------------

### @dynamic and @dynamic=boot examples

Source: https://varlock.dev/reference/item-decorators

Shows a dynamic runtime flag and a boot-time port. @dynamic=boot is for values bound at process start, like PORT, and only affects varlock freeze.

```plaintext
# @dynamic
PUBLIC_RUNTIME_FLAG=


# @type=port @dynamic=boot
PORT=3000

```

--------------------------------

### Load and initialize the pass plugin in .env.schema

Source: https://varlock.dev/plugins/pass

Shows the minimal setup to load and initialize the @varlock/pass-plugin in a .env.schema file. No arguments are needed for default setup.

```plaintext
# 1. Load the plugin
# @plugin(@varlock/pass-plugin)
#
# 2. Initialize the plugin - no arguments needed for default setup
# @initPass()
```

--------------------------------

### Dockerize local MCP server with varlock

Source: https://varlock.dev/guides/mcp/local

Create a Dockerfile that installs varlock and uses varlock run to start the server, then build and run the container with docker commands.

```dockerfile
FROM node:22-alpine


# Install varlock
RUN npm install -g @varlock/cli


WORKDIR /app


# Copy package files
COPY package*.json ./
COPY pnpm-lock.yaml ./


# Install dependencies
RUN npm install -g pnpm && pnpm install


# Copy application files
COPY . .


# Build the application
RUN pnpm build


# Use varlock run to start the server
CMD ["varlock", "run", "--", "node", "dist/server.js"]

```

```bash
# Build the image
docker build -t my-mcp-server:latest .


# Run the container (for testing)
docker run --rm -it my-mcp-server:latest

```

--------------------------------

### Start the broker sandbox with varlock proxy

Source: https://varlock.dev/sandboxes/e2b

TypeScript code to create a broker sandbox, install varlock, upload the schema, start the proxy with `--expose --port 8080 --persist-ca --allow-reload`, and wait for the port to respond. Uses a shared PROXY_TOKEN and bootstrap envs like OP_SERVICE_ACCOUNT_TOKEN.

```typescript
import 'varlock/auto-load';
import { ENV } from 'varlock/env';
import { Sandbox } from 'e2b';


// One data-plane token, shared by the broker and every agent; generate it
// yourself (or let the broker mint one and read it back with `varlock proxy
// token`). It is the credential to USE the broker over the tunnel, not to read
// its secrets.
const PROXY_TOKEN = crypto.randomUUID();
const VARLOCK = '/home/user/.config/varlock/bin/varlock';


const broker = await Sandbox.create({ timeoutMs: 60 * 60 * 1000 });


await broker.commands.run('curl -sSfL https://varlock.dev/install.sh | sh -s');


// upload the schema (plus any other .env files your project loads);
// real values arrive via envs below instead
await broker.files.write('/home/user/proj/.env.schema', envSchemaContents);


// start the proxy bound off-loopback so the tunnel is reachable; the token is
// pinned via VARLOCK_PROXY_TOKEN so we already know it. --persist-ca reuses the
// CA across broker restarts, so agents that already trust it keep working.
// --allow-reload lets you apply schema edits later without a restart; the
// reload channel is only reachable from inside the broker, not by agents.
// Schema keys resolve from the process env, so envs carries the bootstrap:
// usually just your plugin's secret-zero (shown: a 1Password service account).
await broker.commands.run(
  `cd /home/user/proj && ${VARLOCK} proxy start --expose --port 8080 --cert-dir /home/user/proj/.varlock-ca --persist-ca --allow-reload > /home/user/proxy.log 2>&1`,
  {
    background: true,
    timeoutMs: 0,
    envs: {
      VARLOCK_PROXY_TOKEN: PROXY_TOKEN,
      OP_SERVICE_ACCOUNT_TOKEN: ENV.OP_SERVICE_ACCOUNT_TOKEN,
    },
  },
);
// ready once the port answers (a bare GET returns 400, which is fine; we only
// need the listener up, so no -f).
await broker.commands.run("until curl -s -o /dev/null http://127.0.0.1:8080 --proxy ''; do sleep 0.2; done", { timeoutMs: 30_000 });


const brokerHost = broker.getHost(8080); // e.g. 8080-<id>.e2b.app
```

--------------------------------

### Set up proxy environment and run a task

Source: https://varlock.dev/sandboxes/minimal

Sourcing the proxy environment from varlock and then running a task inside the sandbox. This forwards the proxy and CA trust variables to the task.

```bash
eval "$(varlock proxy env)"
minimal run claude   # or: minimal run <your-agent-task>

```

--------------------------------

### @initKubernetes() decorator example

Source: https://varlock.dev/plugins/kubernetes/reference

Initializes a Kubernetes plugin instance for k8sSecret(), k8sConfigMap(), k8sSecretBulk(), and k8sConfigMapBulk() resolvers. Accepts optional key/value args for id, namespace, context, kubeconfig, clusterServer, token, skipTlsVerify, allowMissing, defaultSecret, and defaultConfigMap.

```plaintext
# @initKubernetes(namespace=default, defaultSecret=app-secrets, defaultConfigMap=app-config)
```

--------------------------------

### Create a token for simple setups

Source: https://varlock.dev/plugins/hashicorp-vault

Creates a token with the 'varlock-reader' policy and a TTL of 24 hours, suitable for simple setups.

```bash
vault token create -policy=varlock-reader -ttl=24h
```

--------------------------------

### Start the Varlock broker with Modal sandbox (orchestrate.py)

Source: https://varlock.dev/llms-full.txt

Creates a Modal sandbox running the Varlock broker, installs it via the install script, and uploads the .env.schema file. The PROXY_TOKEN is generated locally and shared by the broker and every agent as the credential to use the broker over the tunnel. The broker listens on encrypted port 8080 and runs for up to 60 minutes.

```python
import os, secrets, urllib.parse
import modal


PROXY_PORT = 8080
VARLOCK = "/root/.config/varlock/bin/varlock"
PROJ = "/root/proj"


# One data-plane token, shared by the broker and every agent; generate it
# yourself (or let the broker mint one and read it back with `varlock proxy
# token`). It is the credential to USE the broker over the tunnel, not to read
# its secrets.
PROXY_TOKEN = secrets.token_hex(16)


app = modal.App.lookup(
```

--------------------------------

### passBulk() usage examples

Source: https://varlock.dev/plugins/pass

Shows how to fetch all entries under a directory using passBulk() with @setValuesBulk. Examples cover loading from store root, a specific path, and with an instance ID.

```plaintext
# Load all entries from the store root
# @setValuesBulk(passBulk())


# Load entries under a specific path
# @setValuesBulk(passBulk("services"))


# With instance ID
# @setValuesBulk(passBulk(team, "shared"))
```

--------------------------------

### Installation script usage

Source: https://varlock.dev/getting-started/installation

Shows the usage and options for the install.sh script, including directory, reinstall, version, force-no-brew, and skip-win-exe flags.

```bash
Usage: install.sh [options]


install varlock binary


Options:
  --dir             directory to install varlock to (defaults to $XDG_CONFIG_HOME/varlock/bin, else ~/.varlock/bin if it exists, else ~/.config/varlock/bin)
  --reinstall       reinstall even if already installed (default: false)
  --version         version of varlock to install (defaults to latest)
  --force-no-brew   force install without homebrew even when detected (default: false)
  --skip-win-exe    on WSL, skip installing the Windows encryption helper (varlock-local-encrypt.exe) (default: false)
```

--------------------------------

### package.json script for varlock run

Source: https://varlock.dev/integrations/javascript

In package.json scripts, calling `varlock` directly works because the package manager handles path issues. This example defines a `start` script that runs `node index.js` with varlock.

```json
"scripts": {
  "start": "varlock run -- node index.js"
}
```

--------------------------------

### Initialize varlock with bunx

Source: https://varlock.dev/guides/migrate-from-dotenv

Run bunx varlock init to install varlock and generate a .env.schema from existing .env files.

```bash
bunx varlock init

```

--------------------------------

### Configure @varlock/keeper-plugin in .env.schema

Source: https://varlock.dev/llms-full.txt

Loads and initializes the plugin in a .env.schema file. Requires a version specifier when loading directly from .env.schema; see the plugins guide for installation instructions. The token is read from the $KSM_CONFIG environment variable.

```env-spec
# 1. Load the plugin
# @plugin(@varlock/keeper-plugin)
#
# 2. Initialize the plugin - see below for more details on options
# @initKeeper(token=$KSM_CONFIG)
# ---


# 3. Add a config item for the Secrets Manager config token
# @type=keeperSmConfig
# @env=KSM_CONFIG
# @required=true
# @description=Keeper Secrets Manager config token
# @secret=true

```

--------------------------------

### Load and initialize the plugin in .env.schema

Source: https://varlock.dev/plugins/google-secret-manager

Shows the minimal setup to load the plugin and initialize it with a project ID. The projectId parameter is optional if the service account JSON includes project_id or GOOGLE_CLOUD_PROJECT is set, but recommended for clarity.

```dotenv
# 1. Load the plugin
# @plugin(@varlock/google-secret-manager-plugin)
#
# 2. Initialize the plugin - see below for more details on options
# @initGsm(projectId=my-gcp-project)

```

--------------------------------

### Start agent sandboxes: create pre-armed sandbox, install varlock, set network policy, run proxy

Source: https://varlock.dev/sandboxes/modal

Creates a Modal sandbox for an agent with open egress initially, installs varlock, then clamps the network policy to only allow the broker host. Runs 'varlock proxy run --url' with the token passed via a Secret to avoid command-line exposure.

```python
agent = modal.Sandbox.create(
    "sleep", "infinity",
    app=app, image=image, workdir=PROJ,
    timeout=60 * 60,
    # pre-armed so the policy can be tightened while it runs
    outbound_domain_allowlist=["*"],
    outbound_cidr_allowlist=["0.0.0.0/0"],
)


agent.exec("bash", "-lc",
    f"mkdir -p {PROJ} && curl -sSfL https://varlock.dev/install.sh | sh -s").wait()


# now clamp: the agent may reach the broker tunnel and nothing else
agent._experimental_set_outbound_network_policy(
    outbound_domain_allowlist=[broker_host],
    outbound_cidr_allowlist=[],
)


# the token rides a Secret rather than the command line, so it stays out of
# process listings
agent.exec("bash", "-lc",
    f"cd {PROJ} && {VARLOCK} proxy run --url wss://{broker_host} -- your-agent-command",
    secrets=[modal.Secret.from_dict({"VARLOCK_PROXY_TOKEN": PROXY_TOKEN})],
).wait()

```

--------------------------------

### Install and initialize the Keeper plugin in .env.schema

Source: https://varlock.dev/plugins/keeper

Shows the minimal configuration to load the plugin and initialize it with a KSM config token. The token is stored in a sensitive internal variable.

```plaintext
# 1. Load the plugin
# @plugin(@varlock/keeper-plugin)
#
# 2. Initialize the plugin - see below for more details on options
# @initKeeper(token=$KSM_CONFIG)
# ---


# 3. Add a config item for the Secrets Manager config token
# @type=keeperSmToken @sensitive @internal
KSM_CONFIG=
```

--------------------------------

### Standalone binary plugin declaration with fixed version

Source: https://varlock.dev/integrations/docker

For the standalone binary, plugins must specify a fixed version in `@plugin()`. Semver ranges require a local `node_modules` install. The example shows a plugin declaration and an init directive, followed by environment variable definitions with `@sensitive` markers.

```plaintext
# @plugin(@varlock/1password-plugin@1.2.3)
# @initOp(token=$OP_SERVICE_ACCOUNT_TOKEN)
# ---
OP_SERVICE_ACCOUNT_TOKEN= # @sensitive
DATABASE_URL=op(op://prod/db/connection-string) # @sensitive
```
Tokens:
Raw