> ## Documentation Index
> Fetch the complete documentation index at: https://docs.boxd.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# varlock

> Resolve and validate a boxd machine's env vars with varlock, or run varlock's credential proxy on a broker machine so agent machines only hold placeholders.

![The varlock padlock mark and pixel wordmark inside the boxd card.](https://mintcdn.com/azin/t5ljqwhgDDnO4H9Z/images/boxd-x-varlock.png?fit=max\&auto=format\&n=t5ljqwhgDDnO4H9Z\&q=85\&s=f89259b9ad42cc3c853283725fe9b5a3)

[varlock](https://varlock.dev) adds a schema to your `.env` files. One `.env.schema` declares each variable, its type and whether it is sensitive, and varlock resolves and validates the values, from plain files or from your secret manager through plugins. Its credential proxy hands an agent placeholders and adds the real secret only to requests to hosts you allow.

A boxd machine gets its env vars from the [machine spec](https://docs.boxd.sh/guides/machine-specs.md) your orchestrator creates it with, so the orchestrator is where varlock resolves them. varlock's guide, [boxd](https://varlock.dev/sandboxes/boxd/), covers two shapes.

## Pick a shape

| Workload | Where the real values live |
| - | - |
| Code you trust with the credentials it uses | In the machine. The orchestrator runs under varlock and passes the resolved values through the spec's `env`. |
| An agent or code you don't trust | On a broker machine that runs `varlock proxy`. The agent machine holds placeholders and can reach the broker and nothing else. |

The guide's examples use varlock 1.24.0 and `@boxd-sh/sdk` 0.3.0, with Node 24 or later or Bun:

```bash theme={"theme":"github-dark"}
npm install varlock@1.24.0 @boxd-sh/sdk@0.3.0
```

`BOXD_API_KEY` in the orchestrator's environment is a [boxd API key](https://docs.boxd.sh/cli/authentication.md#api-keys). It creates and deletes machines and never goes into a machine.

## Pass resolved values

Import `varlock/auto-load` (or run the orchestrator under `varlock run`) and pass only the values the workload needs:

```ts theme={"theme":"github-dark"}
import 'varlock/auto-load';
import { Boxd, Machine } from '@boxd-sh/sdk';

const { BOXD_API_KEY, API_KEY } = process.env;
const boxd = new Boxd({ apiKey: BOXD_API_KEY });

const machine = await boxd.machines.create({
  spec: Machine.spec().isolated().env({ API_KEY }),
  deleteAfter: 900,
});
```

Spec `env` reaches every `exec` command and login shell in the machine. The real value is readable by code in the machine and is kept in the machine's spec. `isolated()` leaves out the in-machine `boxd` CLI and its credential, and `deleteAfter` makes boxd [delete the machine](https://docs.boxd.sh/guides/delete-after.md) on its own if the orchestrator dies before cleanup.

To hand over the whole resolved env at once, `varlock load --format json-full` gives one blob to pass as `__VARLOCK_ENV`. A Node app that imports varlock, or `varlock run` in the machine, reads it, so the machine needs no `.env` files.

## Keep the key on a broker machine

For an agent, one machine runs `varlock proxy start --expose` and holds the real values. Agent machines connect over its HTTPS domain with `varlock proxy run --url`:

```text theme={"theme":"github-dark"}
agent machine (isolated, egress: the broker's domain only)
  varlock proxy run --url wss://<broker-name>.boxd.sh -- <agent command>
        │  WebSocket tunnel, authenticated with VARLOCK_PROXY_TOKEN
        ▼
broker machine: varlock proxy on port 8080, holds API_KEY
        │  real value added only to requests that match a @proxy rule
        ▼
api.example.com
```

The broker's `.env.schema` lists only what the agents need, with `egress="strict"` so requests that match no rule are blocked:

```dotenv theme={"theme":"github-dark"}
# @proxyConfig={egress="strict"}
# ---

# @sensitive @required
# @proxy(domain="api.example.com", path="/v1/**", substituteIn=["header:authorization"])
# @placeholder=vlk_placeholder_api_key
API_KEY=
```

Three boxd calls on the orchestrator's side make it work:

```ts theme={"theme":"github-dark"}
// Point the broker's HTTPS domain at the proxy, and let the tunnel through.
await boxd.machines.proxies.setPort(brokerId, 8080);
await boxd.machines.setBotProtection(brokerId, 'off');

// After the agent is set up: it can reach the broker and nothing else.
await boxd.machines.setEgressAllow(agentId, [brokerHost]);
```

* The machine's [HTTPS domain](https://docs.boxd.sh/guides/proxies.md) carries the tunnel. Read it from `proxies.list()` rather than building it by hand.
* [Bot protection](https://docs.boxd.sh/guides/bot-protection.md) has to be off on the broker. `proxy run --url` can't pass a browser check. The broker's domain is public, and varlock's token authenticates the tunnel.
* The [egress allowlist](https://docs.boxd.sh/guides/egress-allowlist.md) is set from outside the machine, so root inside the agent can't lift it. Allow the exact broker host, never `*.boxd.sh`. Install what the agent needs before you set it, or create agents from a [snapshot](https://docs.boxd.sh/guides/snapshots.md) that already has varlock and your agent.
* Keep agents [isolated](https://docs.boxd.sh/guides/machine-specs.md), so code in them can't use the `boxd` CLI to reach the broker.

The agent needs no `.env` files and no resolver credentials. `proxy run --url` fetches the broker's placeholder environment and CA certificates over the tunnel. Only proxy-aware clients use them: curl does, and Node 24+ `fetch` does with the `NODE_USE_ENV_PROXY=1` that `proxy run` sets. A client that ignores the proxy can't reach anything once egress is pinned.

varlock's guide has the full `orchestrate.ts` that creates both machines, installs varlock, starts the broker, checks that the agent receives the placeholder and deletes both machines. We ran it against boxd and it printed `Placeholder received`.

## varlock or boxd secrets

boxd has its own [env vars and secrets](https://docs.boxd.sh/guides/env-secrets.md), including host-bound secrets that a machine only sees as a `bxds_` placeholder. They keep a key out of a machine without a broker. If your config already lives in a varlock schema and your secret manager, keep it there.

Don't mix the two on an agent machine behind the broker. Org env vars and secrets whose [scope](https://docs.boxd.sh/guides/env-secrets.md#scope) covers a machine still reach it, `isolated()` included, so keep anything an agent should not have `unattached`. A host-bound secret's hosts stay reachable on top of the egress allowlist, so they would be a way out that skips varlock's rules.

## Read more

* [boxd](https://varlock.dev/sandboxes/boxd/) in varlock's docs, with the full broker example and its trust model
* [varlock's credential proxy](https://varlock.dev/guides/proxy/)
* [Sandboxes on boxd](https://docs.boxd.sh/use-cases/sandboxes.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.