sbx/claude-vertex-mixin

Verified Publisher

By Docker, Inc

•Updated about 5 hours ago

Routes Claude Code at Claude on Google Vertex AI with the Application Default Credentials stored ...

Sandbox Kit

146

Overview Tags

sbx/claude-vertex-mixin repository overview

Tag

Digest

sha256:bb3dbece957d…

Size

2.9 kB

Schema

Pushed

about 5 hours ago

Specificationspec.yaml

MIXIN

Routes Claude Code at Claude on Google Vertex AI with the Application Default Credentials stored under the vertex credential. Layer it onto the claude workload.

Arguments

Name	Required	Default	Description
`vertex_project`	Required	—	Google Cloud project that hosts the Vertex AI models
`vertex_region`	Optional	`global`	Vertex AI region

Providesclaude-vertex

CapabilitiesExpand a row to see its full configuration. See the full spec for the complete descriptor.

Type	Required	Description
`com.docker.sandbox/network-policy@1`	Required	—

`com.docker.sandbox/credential@1`	Required	Google Application Default Credentials for Vertex AI

`com.docker.sandbox/lifecycle@1`	Required	—

`com.docker.sandbox/agent-context@1`	Required	—

Requiresclaude, deb/jq

Apply this mixin to a sandbox

sbx run <agent> --kit sbx/claude-vertex-mixin:latest --set vertex_project=<vertex_project>

Make sure you have docker sbx installed

Run the following command to install sbx on your machine.

macOS

brew install docker/tap/sbx

Windows

winget install Docker.sbx

Learn more about docker sbx⁠

Note
Experimental: Sandbox Kit v3
This kit uses the experimental Sandbox Kit specification⁠, specifically v3⁠. The format and runtime behavior may change before v3 is stable.

⁠claude-vertex-mixin

Points Claude Code at Claude on Google Vertex AI, as a mixin (kind: mixin, schemaVersion: "3"). Layered on the claude⁠ workload, the sandbox talks to Vertex with the Application Default Credentials you created on the host. The real refresh token stays outside the container.

It replaces the built-in claude-vertex agent.

⁠Prerequisite

On the host, once:

gcloud auth application-default login

⁠Composing it

sbx run claude --kit docker.io/sbx/claude-vertex-mixin:latest --kit-arg vertex_project=<project-id>
sbx run claude --kit "git+https://github.com/docker/sbx-kits-contrib.git#dir=claude-vertex-mixin" --kit-arg vertex_project=<project-id>
sbx run claude --kit ./claude-vertex-mixin/ --kit-arg vertex_project=<project-id>

vertex_project is required. vertex_region defaults to global; set it with --kit-arg vertex_region=<region>. They are exported as ANTHROPIC_VERTEX_PROJECT_ID and CLOUD_ML_REGION.

The credential is required too: creation fails when no gcloud ADC is stored on the host, because Claude Code cannot log in from inside the sandbox.

It declares requires: ["claude", "deb/jq"] and provides: ["claude-vertex"]. The provides entry is unversioned because the overlay ships no binary.

⁠Engine support

The vertex credential must be honoured for any kit that declares it, not only for the built-in agent. Until an sbx release does that, the mixin composes but the token refresh and credential-file steps do not run. The release number is not known yet and will be named here once it exists.

⁠What the sandbox gets

Piece	Value
Credential	`vertex`, from gcloud ADC. Required: resolution fails when nothing is stored.
Credential file	`~/.config/gcloud/application_default_credentials.json`, with a placeholder `refresh_token`
Environment	`CLAUDE_CODE_USE_VERTEX=1`, plus the project and region args
Settings	`apiKeyHelper` is added to `~/.claude/settings.json`
Egress	`aiplatform.googleapis.com`, `oauth2.googleapis.com`

The client_id and client_secret in the credential file are gcloud's public installer values (see google-auth-library-python, google/auth/_cloud_sdk.py). They are not secret.

⁠What the allowlist leaves out

googleapis.com as a whole.
storage.googleapis.com and bigquery.googleapis.com. Vertex is here for inference.
accounts.google.com. Login happens on the host.

Region-specific Vertex hosts are not in the static list. The engine adds the ones for your region at create time; this is not verified for a mixin yet.

⁠What it deliberately leaves to the base workload

Left out	Why
Claude Code install	The `claude` workload owns it.
`~/.claude.json` and the base `settings.json`	Seeded by the workload; this kit only adds `apiKeyHelper`.
Session volumes, MCP gateway, `CLAUDE.md` profile	Workload concerns.
`ENTRYPOINT`	The base's launch command stays.
`CLAUDE_CODE_USE_VERTEX` as image `ENV` only	A mixin's `ENV` does not become the composed image's, so it also rides as a `/etc/profile.d/claude-vertex-env.sh` export.

⁠One thing to know about egress

Allow-lists union per phase across a composition. With the claude workload underneath, Anthropic's own hosts stay reachable next to Vertex, even though Claude Code is routed at Vertex.