Coding with Claude Code

Run Claude Code inside your workstation and watch the login browser open on your own Mac, even though the agent runs in the VM.

You have built a workstation, added tools to it, and learned to manage its lifecycle. Now for the payoff. You will install Claude Code, Anthropic’s AI coding agent, inside your workstation and start using it.

Here is the part that tends to surprise people. When Claude Code needs you to log in, a browser window opens on your Mac, even though Claude Code is running inside the VM. You authenticate in your own browser, as you always would, and the agent picks up the session inside the workstation. There is nothing for you to wire up.

Before you begin

  • A running workstation from the first tutorial, the my-first-box you created there. If you deleted it, recreate it before continuing.
  • A Claude account. The free tier is enough to try this.

Step 1: Give the workstation a label

If you followed the previous tutorials, your workstation already carries the role: tutorial label and you can skip straight to Step 2. If you are starting from a fresh workstation, add the label now so the configuration below can find it.

A configuration finds the workstations it applies to by matching labels. Edit my-first-box.yaml and add one:

apiVersion: workstations.ringleader.dev/v1
kind: Workstation
metadata:
  name: my-first-box
  namespace: local
  labels:
    role: tutorial
spec: {}

Apply the change:

rl apply -f my-first-box.yaml

The label is just a handle. Nothing about the machine changes yet. In the next step a configuration will select it by that label.

Step 2: Declare the agent and the browser bridge

You will apply two resources together. The first is a configuration that installs Claude Code and, crucially, an opt-in browser bridge. The second is a local binding that forwards the workstation’s ports back to your Mac and is allowed to open URLs in your browser.

Create a file called claude.yaml:

apiVersion: workstations.ringleader.dev/v1
kind: WorkstationConfig
metadata:
  name: claude-tools
  namespace: local
spec:
  # Attach to the same tutorial workstation by label.
  selector:
    matchLabels:
      role: tutorial
  devtools:
    - name: nodejs                   # Claude Code installs through Node.js
    - name: claude-code              # installs the Claude Code CLI
    - name: passthrough-www-browser  # opt-in: capture browser opens from inside the VM
---
apiVersion: core.ringleader.dev/v1
kind: LocalBinding
metadata:
  name: tutorial-forward
  namespace: local
spec:
  enabled: true
  workstationSelector:
    matchName: my-first-box
  # Forward every listening port back to your Mac, so an OAuth callback from your
  # browser can reach the login server running inside the VM.
  autoForward:
    forwardAll: true
  # Let the workstation's browser opens come through to this device, and actually launch
  # each one in your host browser rather than only logging it.
  urlForward:
    enabled: true
    open: true

Two pieces make the magic moment work. The passthrough-www-browser devtool is an opt-in shim. It is never installed by default, and it stands in for the system browser inside the VM so that any attempt to open a URL is captured rather than lost. The urlForward block on the local binding is what allows those captured URLs to reach this device and open in your browser. Without both, nothing opens on your Mac.

Apply the file:

rl apply -f claude.yaml

Step 3: Wait for it to land

Wait until the new tools have been installed inside the VM:

rl workstation wait my-first-box --for condition=Configured --timeout 15m -n local

Step 4: Shell in and start Claude Code

Open a shell on the workstation:

rl shell my-first-box -n local

Then start the agent:

claude

Watch your screen. A browser window opens on your Mac for you to sign in to your Claude account. Approve the login there, and Claude Code is authenticated and ready, running inside the VM. From here you can point it at a project and start working exactly as you would locally.

When you want to see the URLs the workstation has opened, run this on your Mac:

rl binding browser-opens

What just happened?

A login flow that normally assumes a browser sits next to the process just worked across the boundary between your Mac and the VM. Here is the chain:

  1. Claude Code tried to open a login URL using the system browser inside the VM.
  2. The passthrough-www-browser shim stood in for that browser, captured the URL, and wrote it to the in-VM agent’s sink instead of trying to open it on the workstation, which has no browser.
  3. The Ringleader daemon on your Mac, which holds an SSH connection to the workstation, was tailing that sink and received the URL.
  4. Because your local binding set urlForward.open: true, the daemon launched the URL in your host browser. You signed in there, and the OAuth callback returned to the login server inside the VM over the ports you forwarded with autoForward.

The important thing is that you configured none of this by hand. You declared the intent, an opt-in bridge and a binding that may open URLs, and Ringleader carried the login across the gap.

This is not specific to Claude Code. Any tool that opens a browser to authenticate, the GitHub CLI, the Google Cloud CLI, the Azure CLI, behaves the same way once the bridge is in place. And it holds whether the workstation is the local VM you used here or a machine running in the cloud on the other side of the world.

Where to go next

You have completed the tutorial path. From here:

When you are finished with the tutorial workstation, tear it down with rl workstation delete my-first-box -n local.