Coding with Claude Code

Run Claude Code inside your workstation and watch the login browser open on your own machine, 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 give Claude Code, Anthropic’s AI coding agent, a workstation of its own and start using it.

A dedicated box rather than the one you have been using, because that is the argument for running an agent this way. It gets a real machine with real tools, and not your laptop: none of your other repositories, none of the credentials on your disk, nothing on that machine you did not put in the file.

The account the agent signs in with is a separate matter. claude.ai connectors are attached to your account rather than to a machine, so if you have any, the agent can reach them from inside the workstation as well.

Here is the part that tends to surprise people. When Claude Code needs you to log in, a browser window opens on your machine, 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

  • Ringleader installed, with rl version working. Nothing from the earlier tutorials is required: this one builds its own workstation from scratch. No Ringleader account is needed either, because everything here stays in the reserved local namespace on your own machine.
  • A Claude account. The free tier is enough to try this, and it is the only thing you sign in to.

Step 1: Declare the environment

Three resources, in one file, describe the whole thing: the machine, the tools that go on it, and the browser bridge that lets the agent sign in through your own browser.

Create a file called agent-box.yaml:

apiVersion: workstations.ringleader.dev/v1
kind: Workstation
metadata:
  name: agent-box
  namespace: local
  labels:
    role: agent
spec: {}
---
apiVersion: workstations.ringleader.dev/v1
kind: WorkstationConfig
metadata:
  name: agent-tools
  namespace: local
spec:
  selector:
    matchLabels:
      role: agent

  image:                 # pinned, so "a Debian box" is something this file guarantees
    os: linux
    distribution: debian
    version: "13"

  packages:
    - git
    - ripgrep

  devtools:
    - name: nodejs                   # both agents below install through Node.js
    - name: claude-code              # your agent; swap for `codex` and nothing else changes
    - name: passthrough-www-browser  # opt-in: capture browser opens from inside the VM
---
# Sign-in opens in YOUR browser: autoForward carries the VM's ports back so the
# OAuth callback can land, and urlForward lets the VM ask your host to open the page.
apiVersion: core.ringleader.dev/v1
kind: LocalBinding
metadata:
  name: agent-forward
  namespace: local
spec:
  enabled: true
  workstationSelector:
    matchName: agent-box
  autoForward:
    forwardAll: true
  urlForward:
    enabled: true
    open: true

The config finds the machine by its role: agent label rather than by name, which is the same indirection you met in Adding tools. Label a second workstation the same way and it becomes another agent box.

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 machine.

Step 2: Apply it

Apply the file:

rl apply -f agent-box.yaml

Or, apply the file from our example in GitHub, which is the same manifest:

rl apply -f https://raw.githubusercontent.com/ringleader-dev/ringleader-examples/main/environments/ai-coding-agent/agent-box.yaml

Step 3: Wait for it to land

Wait until the tools have been installed inside the VM:

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

Step 4: Shell in and start Claude Code

Open a shell on the workstation:

rl shell agent-box -n local

Then start the agent:

claude

Watch your screen. A browser window opens on your machine 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 machine:

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 machine 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 machine, 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:

  • Configuration goes deeper on the two-resource model, including a fully configured browser-IDE workstation.
  • The Reference Guide documents every field on each kind, including the full LocalBinding and WorkstationConfig specs.
  • The CLI Reference covers every command for driving these resources.
  • Integration points Claude Code at an LLM gateway (your team’s OpenRouter account, or a proxy you run) across every workstation a selector picks out, without configuring any of them by hand.

When you are finished, tear the agent box down with rl workstation delete -f agent-box.yaml -y. Pass the manifest rather than the name: it declares a config and a binding as well, and deleting the machine alone would leave both behind.