fx Docker Sandbox kit

Run the fx coding agent inside a Docker Sandbox, using a Claude model by default and either host-managed Vercel OAuth or a Vercel AI Gateway API key.

Quick start

sbx run --kit git+https://github.com/shelajev/fx-sbx-kit.git fx .

On the first run, approve the fx-vercel credential binding and choose one authentication method:

• Vercel OAuth: run fx login inside the sandbox. It prints a Vercel device-login URL and code; open the URL locally and finish the flow. Docker Sandboxes captures and stores the session on the host, while ~/.fx/auth.json contains proxy-managed sentinel tokens.
• AI Gateway API key: provide your Vercel AI Gateway key when Docker Sandboxes asks for the fx-vercel API key. The kit exposes only an AI_GATEWAY_API_KEY sentinel inside the VM and replaces it in the outbound authorization header.

When both are configured, the API key takes precedence because AI_GATEWAY_API_KEY is first in fx's credential-selection order. Remove that API-key binding to return to OAuth.

For development from a local checkout:

sbx run --kit . fx .

Claude model selection

The initial default is anthropic/claude-sonnet-4.6. Choose and persist another Vercel AI Gateway model from inside fx:

/model anthropic/claude-opus-4.8

You can also use /models to browse the catalog. The kit intentionally does not set the FX_MODEL process override, so interactive model changes remain effective on later runs.

This is Vercel OAuth, not Claude subscription OAuth. fx sends every model request through Vercel AI Gateway, including requests to Anthropic Claude models. A Claude Pro or Max login is therefore not used by fx.

Authentication design

The kit declares both supported fx authentication paths to Docker Sandboxes:

• Device authorization and sign-in use vercel.com and api.vercel.com.
• Token exchange and refresh use api.vercel.com/login/oauth/token.
• Model traffic uses ai-gateway.vercel.sh.
• OAuth tokens and AI Gateway API keys stay in the sbx host credential store.
• The VM receives sentinel values in fx's expected ~/.fx/auth.json format.
• For API-key authentication, the VM receives an AI_GATEWAY_API_KEY sentinel.

The OAuth client ID in spec.yaml is fx's public built-in client ID. If upstream fx changes that ID or its auth-file schema, update the kit to match the corresponding fx release.

Security and networking

fx runs in yolo permission mode because the Docker Sandbox is the intended security boundary. It can freely edit the mounted workspace and run commands inside the VM.

The kit only permits fx installation/update, Vercel OAuth, and Vercel AI Gateway traffic. Package registries and arbitrary web hosts are not enabled. Add those as project-specific mixin kits instead of broadly opening this base kit.

Validate and inspect

sbx kit validate .
sbx kit inspect .

After creating a named sandbox, useful smoke checks are:

sbx exec NAME -- fx --version
sbx exec NAME -- fx status --json
sbx policy log NAME

License

Apache-2.0. See LICENSE.