
.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 your orchestrator creates it with, so the orchestrator is where varlock resolves them. varlock’s guide, boxd, covers two shapes.
Pick a shape
The guide’s examples use varlock 1.24.0 and
@boxd-sh/sdk 0.3.0, with Node 24 or later or Bun:
BOXD_API_KEY in the orchestrator’s environment is a boxd API key. It creates and deletes machines and never goes into a machine.
Pass resolved values
Importvarlock/auto-load (or run the orchestrator under varlock run) and pass only the values the workload needs:
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 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 runsvarlock proxy start --expose and holds the real values. Agent machines connect over its HTTPS domain with varlock proxy run --url:
.env.schema lists only what the agents need, with egress="strict" so requests that match no rule are blocked:
- The machine’s HTTPS domain carries the tunnel. Read it from
proxies.list()rather than building it by hand. - Bot protection has to be off on the broker.
proxy run --urlcan’t pass a browser check. The broker’s domain is public, and varlock’s token authenticates the tunnel. - The egress allowlist 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 that already has varlock and your agent. - Keep agents isolated, so code in them can’t use the
boxdCLI to reach the broker.
.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, including host-bound secrets that a machine only sees as abxds_ 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 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 in varlock’s docs, with the full broker example and its trust model
- varlock’s credential proxy
- Sandboxes on boxd