How to Run Cline in code-server for Remote Development

Running Cline in code-server allows developers to access their AI coding assistant via a web browser connected to a remote virtual machine. This remote pattern has become popular for engineers who need to compile code, run test suites, or execute agentic tools on virtual machines that match their production environments. However, moving from local desktop VS Code to browser-based VS Code introduces architectural hurdles that differ from standard setups.

A developer deploying a browser-based VS Code environment via code-server to interact with Cline will find that a single container restart wipes out all task histories, custom instructions, and Model Context Protocol configurations. The loss occurs because code-server runs extensions in transient container lifecycles that delete local state by default, requiring explicit storage volume mounts to persist Cline's global data. Without planning for storage persistence and API authentication redirects, developers will lose their context, API settings, and model configs every time the server restarts or the container spins down.

Remote virtual machines provide raw computing power and match production systems, which prevents the "works on my machine" syndrome. Yet, extensions running inside code-server operate entirely on the remote host, not in the local browser. This shift in runtime location changes how the environment handles files, network connections, and local settings. Standard guides for Cline focus on desktop installations where local user paths are stable. Remote deployments require a deeper understanding of how code-server structures its data directories and how browser-based IDEs manage API connections when standard OAuth flows are blocked.

For developers seeking an enterprise coordination layer for their remote agents, commodity storage systems are insufficient. When Cline operates in a remote workspace, it needs to save large codebase contexts, read configuration logs, and write output files. If the underlying file system is transient, these files disappear. While traditional cloud storage options do not natively connect to remote development environments, an intelligent workspace provides the persistence and semantic indexing needed to keep remote agent outputs accessible to human teammates. Fast.io serves as this coordination substrate, offering persistent workspaces where agents write their outputs, and humans collaborate in real time. Read the Fast.io agent onboarding to understand how to connect your agentic workflows.

To install Cline in a code-server instance, you must account for the registry differences between Microsoft's official marketplace and open-source alternatives. Because Microsoft limits access to its Visual Studio Marketplace to official VS Code products, code-server connects to the Open VSX Registry by default. Cline is published on Open VSX, which makes installation direct either through the browser interface or the command-line interface. You can review the official Cline installation guide for additional platform-specific details.

Follow this step-by-step checklist to install the extension:

1. Access your running code-server instance in your web browser.
2. Click on the Extensions icon in the Activity Bar on the left side of the window, or press the keyboard shortcut Ctrl+Shift+X (or Cmd+Shift+X on macOS).
3. Type saoudrizwan.claude-dev or Cline in the search bar.
4. Click the blue Install button next to the Cline extension published by saoudrizwan.

If your remote environment is air-gapped or cannot connect to the external Open VSX Registry, you can install the extension using a compiled VSIX file:

1. Download the latest .vsix release file directly from the official Cline repository.
2. Transfer the file to your remote server using a secure file transfer protocol or copy the file path.
3. Open your terminal in code-server or ssh into the remote virtual machine.
4. Run the installation command:

code-server --install-extension /path/to/cline-extension.vsix

5. Verify the installation by checking that the Cline icon appears in your Activity Bar.

Once the extension is active, it will initialize its local workspace files. However, installing the extension is only the first step. Without configuring the directories where Cline writes its task states, any container update or reboot will delete your agent's history.

Persisting the right directories is what keeps Cline conversation histories alive across container restarts. There are 2 of them, and missing the second is the usual cause of a "why did my task history vanish" report.

First, code-server stores user preferences, extensions, and extension data in its user data directory. In Linux environments, this path defaults to ~/.local/share/code-server. Older Cline builds kept agent state under ~/.local/share/code-server/User/globalStorage/saoudrizwan.claude-dev/, so that path alone used to be enough.

Second, and this is the change that breaks older guides, Cline 4.x moved to a single shared data directory that the IDE extension, the CLI, and the SDK all use:

~/.cline/

MCP server definitions now live at ~/.cline/data/settings/cline_mcp_settings.json, and task history moved alongside them. The legacy globalStorage folder is read once on first launch and migrated, after which Cline stops writing to it. Persist both paths so an existing installation keeps its migrated state and a fresh one keeps its new state.

If you are running code-server in a containerized environment like Docker, you must mount a persistent volume for each directory. If the container is destroyed and recreated, the local file system resets, and all previous agent conversations are lost.

To mount the directory in Docker, use the following configuration pattern.

Docker Compose Configuration:

services:
  code-server:
    image: codercom/code-server:latest
    container_name: remote-ide
    ports:
      - "8080:8080"
    volumes:
      - code_server_data:/home/coder/.local/share/code-server
      - cline_data:/home/coder/.cline
      - /path/to/your/workspace:/home/coder/project
    environment:
      - PASSWORD=your_secure_password
    restart: unless-stopped

volumes:
  code_server_data:
    driver: local
  cline_data:
    driver: local

For Kubernetes deployments, define a PersistentVolumeClaim to ensure the storage remains intact when pods reschedule.

Kubernetes Deployment Spec Configuration:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: code-server-deployment
spec:
  replicas: 1
  selector:
    matchLabels:
      app: code-server
  template:
    metadata:
      app: code-server
    spec:
      containers:
      - name: code-server
        image: codercom/code-server:latest
        ports:
        - containerPort: 8080
        volumeMounts:
        - name: code-server-storage
          mountPath: /home/coder/.local/share/code-server
        - name: cline-storage
          mountPath: /home/coder/.cline
      volumes:
      - name: code-server-storage
        persistentVolumeClaim:
          claimName: code-server-pvc
      - name: cline-storage
        persistentVolumeClaim:
          claimName: cline-data-pvc

By binding both the /home/coder/.local/share/code-server and /home/coder/.cline directories to persistent volumes, you ensure that Cline's conversation histories, cached configurations, and MCP settings remain untouched between container updates. This setup is essential for long-running engineering projects where you rely on Cline's previous context to solve complex bugs.

Stop losing agent context between sessions

Get an intelligent workspace with built-in version history and an MCP endpoint to keep your files persistent when you run Cline in code-server. Every organization starts with a 14-day free trial, which requires a credit card. Plans are Starter at $29/mo, Business at $99/mo, and Growth at $299/mo.

Start 14-Day Trial

Once Cline is installed and its data storage is persistent, you can extend its capabilities using the Model Context Protocol. MCP allows the agent to interact with external databases, search engines, and file systems. Standard desktop setups run MCP servers locally by launching command-line tools. However, in a remote server environment, managing local processes for every external tool adds configuration overhead and security risks.

Instead of running separate local processes, you can connect Cline directly to a remote MCP host. Fast.io exposes action-based MCP tools over Streamable HTTP. This remote protocol eliminates the need to run local nodes or npm packages inside your code-server container. To connect Cline to Fast.io's remote server, check the Fast.io agent storage features page for step-by-step connection credentials.

To configure Cline to connect to the Fast.io MCP endpoint, you must edit the Cline MCP settings file. This file is separate from the standard VS Code configurations, and on Cline 4.x it sits in the shared Cline data directory rather than in code-server's user data folder:

~/.cline/data/settings/cline_mcp_settings.json

Open this file and add the Fast.io configuration block under the mcpServers object.

Cline MCP Server Configuration:

{
  "mcpServers": {
    "fastio": {
      "type": "streamableHttp",
      "url": "https://mcp.fast.io/mcp",
      "disabled": false
    }
  }
}

Because this setup uses the streamableHttp connection type, you must specify the type explicitly. Omitting the type field causes Cline to default to the legacy SSE protocol, which expects a persistent stream handshake and fails to connect to the HTTP endpoint.

Connecting Cline to Fast.io provides your coding agent with direct access to an intelligent workspace. Once connected, the agent can write code files, upload debug logs, and retrieve project assets. Unlike raw cloud storage repositories where files are static, Fast.io workspaces index documents on arrival. This indexing enables Intelligence Mode, which allows both your remote Cline agent and human teammates to run semantic and full-text searches with citations. For team coordination, Fast.io handles ownership transfer, allowing an agent to create workspaces and files, transfer ownership to a manager, and retain administration access.

When multiple developers and agents collaborate on the same remote server, keeping the workspace organized is essential to prevent conflicts. If 2 agent sessions run simultaneously in the same repository, they can overwrite each other's files without notice. Creating distinct workspace folders for each agent and developer resolves this risk.

You can configure code-server to open separate workspaces for different agents. In this multi-agent pattern, Fast.io serves as the central file substrate. A research agent can run in one workspace, gathering data and writing structural analysis reports. Once its task is complete, it uploads the files to a shared Fast.io folder. A writer agent running in a separate workspace then pulls those files to generate documentation.

To coordinate these steps, developers use the following practices:

• Create isolated subdirectories. Assign each agent a dedicated working directory on the remote server to prevent file conflicts.
• Use version checkpoints. Rely on Fast.io's per-file version history to track changes. If an agent writes invalid code, developers can revert the file to its previous state with a single click.
• Set up webhook notifications. Enable Fast.io webhooks to alert developers when an agent writes a new file or modifies an existing configuration. This replaces continuous folder polling with reactive triggers.
• Initiate ownership transfer. When an agent finishes building a project, the developer transfers ownership of the workspace to the client or team lead. This secures the files while keeping the remote environment auditable.

By structuring the workspaces this way, you turn code-server from a single-user remote IDE into a coordinated human-agent development environment. Teammates can monitor the agent's progress by viewing the events activity feed, reviewing the append-only audit log, and editing files side by side in real time using Collaborative Notes.

Most remote code-server installations run on virtual machines behind reverse proxies or custom subdomains. When developers attempt to configure AI providers inside Cline, they often face browser redirection hurdles. Standard extensions frequently use OAuth authentication flows that redirect to local addresses such as http://127.0.0.1. In a remote browser-based IDE, this redirect loop fails because the browser running on the client machine cannot route to the remote container's internal ports.

To resolve these redirection blocks, developers must configure their API connections manually. For example, when connecting to LLM providers like Anthropic or OpenRouter, avoid automatic authentication prompts that require web browser redirects. Instead, obtain your API key directly from the provider's console and paste it manually into Cline's settings panel.

If you are deploying code-server behind a reverse proxy, you should secure the interface with a secure proxy wrapper and pass the authentication token via headers. This protects the environment without relying on local redirect systems.

For collaborative teams, this manual setup ensures that team members do not trigger broken browser redirect paths. Instead, they share a persistent workspace running Cline. By connecting your remote code-server instance to Fast.io, you establish a central repository where the agent's work is recorded. The append-only audit log tracks which files the agent modified, while per-file version history allows humans to review changes, revert mistakes, and co-edit code documents using Collaborative Notes. This setup bridges the gap between autonomous remote execution and secure team oversight. Refer to the Fast.io pricing page to select a plan that supports your organization's storage needs.