Skip to main content
The varlock padlock mark and pixel wordmark inside the boxd card. varlock 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 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

Import varlock/auto-load (or run the orchestrator under varlock run) and pass only the values the workload needs:
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 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:
The broker’s .env.schema lists only what the agents need, with egress="strict" so requests that match no rule are blocked:
Three boxd calls on the orchestrator’s side make it work:
  • 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 --url can’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 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, 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 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