Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -67,6 +67,7 @@ Docs content lives in `packages/varlock-website/src/content/docs/` (`.mdx`). Whe
- No em dashes (`—`). Rewrite into separate sentences, commas, colons, or parentheses instead. Do not swap in a spaced hyphen (` - `). (En dashes for genuine numeric ranges like `15.0–15.4` are fine.)
- Avoid marketing and AI-flavored filler: `seamless`, `comprehensive`, `powerful`, `robust`, `leverage`, `out of the box`, `by design`, `effortless`, `unlock` (metaphorical), "whether you need X, Y, or Z", "instead of wrestling with", and similar. Say what the thing does plainly.
- Be concise, but never at the cost of completeness. Keep every flag, command, caveat, and link a user or their agent needs to stay unblocked.
- Example secret and placeholder values must look like the real thing: keep the provider's real prefix and pad with zeros to a plausible length (`sk-ant-api03-000000000000000000000000`, `sk_test_00000000000000000000000000`). Never truncate them with `...` or an ellipsis. When mentioning varlock's generated fallback placeholder, write its full shape (`vlk_placeholder_<KEY>_<hash>`), not a truncated form.
- Never edit code fences, `ansi`/`diff` blocks, generated fixtures, frontmatter structure, or MDX component markup for tone. Prose only.
- Run `bun run --filter varlock-website astro build` to confirm the docs still build after non-trivial edits.

Expand Down
6 changes: 3 additions & 3 deletions packages/varlock-website/src/content/docs/guides/proxy.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ STRIPE_SECRET_KEY=yourPreferredPlugin() # from a plugin or built-in encryption
varlock proxy run -- claude
```

The agent launched above sees `STRIPE_SECRET_KEY=sk_test_0000…`, a placeholder shaped like a real key. When it makes a request to `api.stripe.com`, the proxy swaps the placeholder for the real key on the wire. If the agent prints the variable, exfiltrates its env, or sends it anywhere else, all it has is a useless placeholder.
The agent launched above sees `STRIPE_SECRET_KEY=sk_test_00000000000000000000000000`, a placeholder shaped like a real key. When it makes a request to `api.stripe.com`, the proxy swaps the placeholder for the real key on the wire. If the agent prints the variable, exfiltrates its env, or sends it anywhere else, all it has is a useless placeholder.

The `@placeholder` keeps the placeholder valid-looking so the Stripe SDK's client-side key-format check passes. See [Placeholders](/guides/proxy/rules/#placeholders) for when you need it.

Expand Down Expand Up @@ -102,7 +102,7 @@ GITHUB_TOKEN=yourPreferredPlugin()

`@proxy` already implies [`@sensitive`](/reference/item-decorators/#sensitive) (and varlock treats items as sensitive by default), so the `@sensitive` line is optional. We show it explicitly here because being clear about what is a secret is good practice.

The `@placeholder` on `STRIPE_SECRET_KEY` makes the placeholder the agent sees look like a real key, so SDK key-format checks pass. Leave it off (like `GITHUB_TOKEN` above) and the item gets a generic `vlk_placeholder_`, which varlock warns about because it can fail a client-side key-format check (see [Placeholders](/guides/proxy/rules/#placeholders)).
The `@placeholder` on `STRIPE_SECRET_KEY` makes the placeholder the agent sees look like a real key, so SDK key-format checks pass. Leave it off (like `GITHUB_TOKEN` above) and the item gets a generic `vlk_placeholder_<key>_<hash>`, which varlock warns about because it can fail a client-side key-format check (see [Placeholders](/guides/proxy/rules/#placeholders)).

That is all the proxy needs: there is no separate "enable" step. It runs in **permissive** mode by default (hosts that don't match a rule pass through untouched). Add [`@proxyConfig={egress="strict"}`](/guides/proxy/rules/#egress-modes) to your schema header only when you want to block everything that isn't explicitly routed.

Expand All @@ -124,7 +124,7 @@ varlock proxy run -- python tool.py
That's it. The child inherits everything it needs (proxy address + CA trust) automatically.

:::note[Using the proxy with Claude Code]
Wire Claude Code's credential as [`ANTHROPIC_API_KEY`](/guides/ai-tools/claude/) (an `sk-ant-api…` key). `CLAUDE_CODE_OAUTH_TOKEN` (a subscription token from `claude setup-token`) only works for headless `claude -p` requests: the interactive TUI rejects a static token, so through the proxy it fails with a `401` regardless of your egress setting.
Wire Claude Code's credential as [`ANTHROPIC_API_KEY`](/guides/ai-tools/claude/) (a key with the `sk-ant-` prefix). `CLAUDE_CODE_OAUTH_TOKEN` (a subscription token from `claude setup-token`) only works for headless `claude -p` requests: the interactive TUI rejects a static token, so through the proxy it fails with a `401` regardless of your egress setting.
:::

:::caution[Put `@proxy` on the item, not in the header]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -142,8 +142,8 @@ You don't have to define placeholders. If you don't set one, varlock generates a
The placeholder the agent sees is chosen in priority order:

1. An explicit [`@placeholder`](/reference/item-decorators/#placeholder) value (always wins).
2. A valid-and-unique value derived from the item's [`@type`](/reference/item-decorators/#type): e.g. `@type=url` → `https://vlk-placeholder-invalid/`, `@type=email` / `uuid` / `md5` likewise, and `@type=string(startsWith=sk-, isLength=20)` yields an `sk-`-shaped placeholder.
3. A generic fallback (`vlk_placeholder_<KEY>_`). For a `@proxy`-routed item varlock **warns** about this one, since it's the case that can fail an SDK's format check; if your client doesn't validate the format, it's harmless.
2. A valid-and-unique value derived from the item's [`@type`](/reference/item-decorators/#type): e.g. `@type=url` → `https://vlk-placeholder-<key>-<hash>.invalid/`, `@type=email` / `uuid` / `md5` likewise, and `@type=string(startsWith=sk-, isLength=20)` yields an `sk-`-shaped placeholder.
3. A generic fallback (`vlk_placeholder_<KEY>_<hash>`). For a `@proxy`-routed item varlock **warns** about this one, since it's the case that can fail an SDK's format check; if your client doesn't validate the format, it's harmless.

Every placeholder is unique per item, so two different secrets can never collide on the wire.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -317,7 +317,7 @@ CI_DEPLOY_TOKEN=

Sets an explicit placeholder string for the item, used in place of the real value when the item is routed through the [credential proxy](/guides/proxy/). A placeholder is what an untrusted child process (e.g. an AI agent) sees instead of the secret.

Without an explicit `@placeholder`, varlock derives one from the item's [`@type`](#type) format, falling back to a generic value. Set this when a generic placeholder would fail a client's key-format validation (e.g. an `sk-` prefix check).
Without an explicit `@placeholder`, varlock derives one from the item's [`@type`](#type) format, falling back to a generic value. Set this when a generic placeholder would fail a client's key-format validation (e.g. an `sk-` prefix check).

```env-spec
# @proxy(domain="api.openai.com")
Expand Down
Loading
Loading