Getting Started

Get RemoteKube running in your cluster in under 10 minutes. This guide covers prerequisites, your first deployment, and connecting from your phone or browser.

Prerequisites

Before you begin, make sure you have:

  • A Kubernetes cluster — Any conformant distribution: EKS, GKE, AKS, k3s, KIND, minikube, or self-hosted. Kubernetes 1.24+ with RBAC enabled.
  • kubectl — Configured to access your target cluster.
  • Helm 3 — For production deployments (optional for KIND/Docker Compose).
  • A Claude account — Pro or Max plan. You'll authenticate inside the container via /login (browser OAuth). Credentials persist in the PVC.
  • Docker — For building custom images or running via Docker Compose.

Choose Your Deployment Method

RemoteKube supports three deployment methods. Choose the one that fits your workflow.

Option 1: KIND (Local Development)

Best for trying RemoteKube locally. This creates a KIND cluster, installs Calico CNI for NetworkPolicy support, builds the image, and deploys with Helm — all in one command.

KIND bootstrap
$ git clone https://github.com/PatrykQuantumNomad/claude-in-a-box.git
$ cd claude-in-a-box
$ make bootstrap

The bootstrap process takes 3-5 minutes. Once complete, the agent pod is running and ready. See the KIND Deployment Guide for details on the bootstrap flow, Calico CNI, and health probes.

Option 2: Docker Compose (Standalone)

Run the agent as a standalone container without Kubernetes. Useful for quick testing or environments where you don't need cluster-level access.

Docker Compose
$ git clone https://github.com/PatrykQuantumNomad/claude-in-a-box.git
$ cd claude-in-a-box
$ docker compose up -d
$ docker attach claude-agent
$ # Inside Claude Code: /login

Option 3: Helm (Production)

Production-grade deployment with configurable RBAC tiers, resource limits, persistence, and NetworkPolicy isolation.

Helm install
$ helm install claude-agent ./helm/claude-in-a-box \
$ --set image.repository=ghcr.io/PatrykQuantumNomad/claude-in-a-box \
$ --set image.tag=latest

See the Helm Chart Reference for all configurable values, RBAC profiles, and security settings.

Verify Installation

After deployment, check that the agent pod is running:

Verify pod status
$ kubectl get pods -l app=claude-agent
$ # Expected: claude-agent-0 1/1 Running

The pod should show 1/1 containers ready — the Claude Code agent.

Connect from Your Phone or Browser

Note: Remote Control mode is currently not available on Linux (server-side feature gate). The entrypoint keeps the code path for when Anthropic enables it. For now, use interactive mode with kubectl attach.

When Remote Control becomes available on Linux, you'll be able to connect from any device:

  1. Open claude.ai or the Claude mobile app.
  2. Start a new conversation.
  3. Your remote agent will appear as an available connection.
  4. Start managing your cluster — ask Claude to check pod status, read logs, or diagnose issues.

See Claude Code & Remote Connect for details on how the relay architecture works and how to configure startup modes.

Choose a Security Tier

RemoteKube supports three RBAC tiers with increasing permissions:

Tier Permissions Best For
readonly (default) List and get resources only Monitoring, incident triage, on-call
operator Create, update, delete within namespaces Active management, deployments
airgapped Cluster-admin equivalent Trusted dev/staging environments

To deploy with the operator tier:

Helm install (operator)
$ helm install claude-agent ./helm/claude-in-a-box \
$ -f helm/claude-in-a-box/values-operator.yaml

Next Steps