How to Run Cline in GitHub Codespaces

When running a coding assistant locally, the extension operates within the local operating system process space. This grants the extension direct access to local system keychains, configuration files, and terminal environments. Moving your development workspace to the cloud changes this architecture. In a remote container development environment, the editor is split into a local user interface and a remote server. VS Code extensions running in a dev container are installed and run inside the container, where they have full access to the container's tools, platform, and file system, rather than running on your local computer.

This remote execution model shifts the process host for all active extensions. When you spin up a container using GitHub Codespaces, the remote host starts a lightweight server process inside the container. All background tasks, command runners, language servers, and extensions are loaded and executed by this server process. This architecture ensures that extensions have direct, low-latency access to the remote filesystem, project configuration, and terminal utilities. However, it also means that the extension has no access to your local machine's credentials, files, or background applications.

Understanding this split is critical for configuring tools that rely on external credentials, local keychains, or system libraries. Since the agent executes inside the remote container, any commands it runs or system files it reads are isolated within that specific container. If your development tasks require specific system dependencies, those dependencies must be explicitly defined and installed within the container image. This isolation provides excellent security and consistency across developer setups, but it introduces distinct integration hurdles.

To bridge the gap between cloud-hosted development containers and persistent project storage, teams can route their workspace assets to a dedicated workspace platform. Using a shared workspace ensures that your files remain accessible and synchronized across multiple container rebuilds. You can explore how these cloud environments operate by viewing the details of Fastio workspaces.

Many developers choose to access their cloud container environments using the web-based version of Visual Studio Code. This browser-based editor is highly convenient, but it introduces distinct security and networking boundaries that conflict with standard authentication patterns. One of the most common issues when running Cline in this environment is the failure of web-based editor redirect flows.

When you attempt to authenticate a tool using an external service, the extension typically triggers an OAuth handshake. This process relies on launching a local browser window to sign in and then redirecting the user back to the editor via a custom protocol handler or a local redirect port. In a remote, browser-based environment, this flow breaks. The container running the extension host is a headless Linux environment. If the extension attempts to open a web browser using standard Node.js libraries, the process tries to launch a browser directly inside the headless container where no display manager exists, causing the authentication process to hang.

Even if the extension attempts to open the redirect URL on your local machine, the browser-based editor cannot easily capture the incoming callback. Secure browser sandboxes often block third-party cookies, custom protocol redirects, and local network requests. When the external service attempts to send the authentication token back to the container via a redirect URL, the request is blocked, leaving the extension in an unauthenticated state.

To bypass these redirect blocks, developers must avoid browser-based OAuth sign-in flows inside remote containers. Instead of using usage-billing plans that require a web browser sign-in, you should select API providers that use static credentials. Entering a personal API key directly into the configuration settings bypasses the redirect loop entirely, establishing a stable connection to your language model.

Because containers are ephemeral, any configuration files or credentials stored directly within the container's active filesystem will be lost when the container is rebuilt or stopped. To maintain a persistent development workflow, you must secure your API credentials outside the container storage. API key storage requires Codespaces secret syncing or container environment variables.

GitHub Codespaces provides a dedicated system for managing sensitive credentials. You can define development environment secrets at the personal account level or the repository level. When you start or restart a codespace, the platform makes these secrets available as environment variables inside the container, so your coding tools can read them without the values ever being committed to your source code.

To configure these credentials for your workspace, follow these steps:

1. Navigate to your GitHub settings page.

2. In the left sidebar, select Secrets and variables, then click Codespaces.

3. Under the User secrets section, click New secret.

4. Name your secret (for example, ANTHROPIC_API_KEY) and paste your API key in the Value field.

5. Select the repositories that are allowed to access this secret, then click Add secret.

Once registered, the secret is automatically injected as an environment variable into your active container shell. When Cline starts, it reads these environment variables to authorize API calls to your chosen model provider. If you update your secrets while a codespace is running, you must stop and restart the codespace for the new credentials to take effect. This secret management approach keeps your keys secure and removes the need to enter credentials every time your container rebuilds.

Persist Cline workspace assets across sessions

A shared workspace with an MCP-ready endpoint for your agent's reads and writes, with versioning and search built in. 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

To ensure that every member of your team has immediate access to your development tools, you should configure your repository to preload the necessary extensions automatically. You do this by defining the container's customizations inside a devcontainer.json configuration file.

The configuration file is located in the .devcontainer folder at the root of your repository. You can specify the exact extensions that should be installed when the container is built. For Cline, the official VS Code marketplace extension ID is saoudrizwan.claude-dev.

Here is a complete, copyable devcontainer.json configuration example that preloads the extension:

{
  "name": "Intelligent Workspace Container",
  "image": "mcr.microsoft.com/devcontainers/typescript-node:20",
  "customizations": {
    "vscode": {
      "extensions": [
        "saoudrizwan.claude-dev"
      ]
    }
  },
  "postCreateCommand": "mkdir -p ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings && echo '{\\"mcpServers\\": {}}' > ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json"
}

In this configuration block, we define the base container image and configure the editor customizations. The extensions array instructs the platform to fetch and install the extension directly into the remote container during the build phase.

We also include a postCreateCommand lifecycle hook. This command runs immediately after the container is built. It creates the required settings directory for the extension and initializes an empty configuration file. By pre-creating this directory structure, we ensure that the extension can load its settings without permission errors. This automated setup reduces manual configuration and gives your developers a ready-to-use coding workspace.

FROM mcr.microsoft.com/devcontainers/typescript-node:20

RUN apt-get update && apt-get install -y \\
    chromium \\
    libnss3 \\
    libatk-bridge2.0-0 \\
    libgtk-3-0 \\
    libxss1 \\
    libasound2 \\
    && rm -rf /var/lib/apt/lists/*

Once your container is running and your extension is installed, you can expand the agent's capabilities by connecting it to external services. Cline supports Model Context Protocol, which allows the coding agent to read and write files, query databases, and execute actions on external systems. You can use this protocol to connect your agent to Fastio's shared workspaces.

Fastio serves as a persistent, collaborative storage layer for your development team. While files in your codespace are ephemeral, files in your Fastio workspace are persistent, versioned, and indexed. Fastio exposes its tools over a remote MCP server. To connect Cline to this server, you must edit your local settings file.

Because Fastio's MCP server is hosted, you configure a remote connection rather than running a local command. Open the cline_mcp_settings.json file in your container's user settings directory. On Linux, this is located at ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json. Update the configuration block as follows:

{
  "mcpServers": {
    "fastio-workspace": {
      "type": "streamableHttp",
      "url": "https://mcp.fast.io/mcp/key",
      "headers": {
        "Authorization": "Bearer YOUR_FASTIO_API_KEY"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

In this configuration block, we specify the streamableHttp transport type. We set the remote URL to https://mcp.fast.io/mcp/key, which is the correct endpoint for key-based authentication. We also pass our developer API key in the Authorization header.

By establishing this connection, the coding assistant gains access to a consolidated MCP toolset. The agent can now query your team's indexed documents, co-edit shared files in real time, and save output directly to your shared storage. This setup allows developers and agents to collaborate on the same file system, tracking edits and coordinating project handoffs without local synchronization conflicts.

To use this shared space, teams can start with a paid subscription. Plans are Starter at 29 USD monthly, Business at 99 USD monthly, and Growth at 299 USD monthly. Every organization starts with a 14-day free trial, which requires a credit card. You can set up your team's shared directory by visiting the Fastio pricing page and launching a workspace.