> ## Documentation Index
> Fetch the complete documentation index at: https://anaconda.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Workstations FAQ

export const TroubleshootSolution = ({children}) => <>
    <hr className="my-3 w-full" />
    <details className="mt-3">
      <summary className="cursor-pointer font-semibold text-base mb-1">
        Solution
      </summary>
      <div className="mt-2 ml-4" data-component-part="step-content">
        {children}
      </div>
    </details>
  </>;

export const TroubleshootCause = ({children}) => <details className="mt-3 mb-2">
    <summary className="cursor-pointer font-semibold text-base mb-1">
      Cause
    </summary>
    <div className="mt-2 ml-4" data-component-part="step-content">
      {children}
    </div>
  </details>;

export const TroubleshootTitle = ({children}) => <>
    <p className="m-0 font-semibold text-xl leading-tight mb-2" role="heading" aria-level={3}>
      {children}
    </p>
    <hr className="my-3 w-full" />
  </>;

export const Troubleshoot = ({children}) => <div className="callout my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border troubleshoot-admonition dark:troubleshoot-admonition" data-callout-type="troubleshoot">
    <div className="mt-0.5 w-4">
      <svg width="14" height="14" viewBox="0 0 640 640" fill="currentColor" className="w-4 h-4" aria-label="Troubleshoot">
        <path d="M541.4 162.6C549 155 561.7 156.9 565.5 166.9C572.3 184.6 576 203.9 576 224C576 312.4 504.4 384 416 384C398.5 384 381.6 381.2 365.8 376L178.9 562.9C150.8 591 105.2 591 77.1 562.9C49 534.8 49 489.2 77.1 461.1L264 274.2C258.8 258.4 256 241.6 256 224C256 135.6 327.6 64 416 64C436.1 64 455.4 67.7 473.1 74.5C483.1 78.3 484.9 91 477.4 98.6L388.7 187.3C385.7 190.3 384 194.4 384 198.6L384 240C384 248.8 391.2 256 400 256L441.4 256C445.6 256 449.7 254.3 452.7 251.3L541.4 162.6z" />
      </svg>
    </div>
    <div className="prose min-w-0 w-full">{children}</div>
  </div>;

export const Comments = ({children}) => {
  return <div class="my-4 px-5 py-4 overflow-hidden rounded-2xl flex gap-3 border border-zinc-500/20 bg-zinc-50/50 dark:border-zinc-500/30 dark:bg-zinc-500/10" data-callout-type="comments">
      <div class="w-4">
        <svg width="14" height="14" viewBox="0 0 640 640" fill="currentColor" xmlns="http://www.w3.org/2000/svg" class="w-5 h-5" aria-label="Comments">
            <path d="M320 112C434.9 112 528 205.1 528 320C528 434.9 434.9 528 320 528C205.1 528 112 434.9 112 320C112 205.1 205.1 112 320 112zM320 576C461.4 576 576 461.4 576 320C576 178.6 461.4 64 320 64C178.6 64 64 178.6 64 320C64 461.4 178.6 576 320 576zM280 400C266.7 400 256 410.7 256 424C256 437.3 266.7 448 280 448L360 448C373.3 448 384 437.3 384 424C384 410.7 373.3 400 360 400L352 400L352 312C352 298.7 341.3 288 328 288L280 288C266.7 288 256 298.7 256 312C256 325.3 266.7 336 280 336L304 336L304 400L280 400zM320 256C337.7 256 352 241.7 352 224C352 206.3 337.7 192 320 192C302.3 192 288 206.3 288 224C288 241.7 302.3 256 320 256z" />
        </svg>
      </div>
      <div class="text-sm prose min-w-0 w-full">
        {children}
      </div>
    </div>;
};

Answers to common questions about workstations on Anaconda Platform. For an introduction to workstations, see [What is a workstation?](/docs/platform/concepts/what-is-a-workstation) For help creating and connecting to a workstation, see [Setting up a cloud workstation](/docs/platform/guides/develop/setting-up-a-cloud-workstation).

## Using workstations

<AccordionGroup>
  <Accordion title="Can a non-admin create or edit a workstation?">
    Yes. Any user can create and edit their own workstations. Administrators can additionally create workstations for other users and view all workstations in the deployment.
  </Accordion>

  <Accordion title="Are workstations tied to a specific perimeter?">
    No. Think of workstations as laptops in the cloud: from a workstation, you can access any perimeter you have access to.
  </Accordion>

  <Accordion title="Can I switch perimeters inside my workstation?">
    Yes. Run `outerbounds perimeter switch --id <PERIMETER_NAME>` to switch perimeters on your workstation, or use the platform's pre-installed VS Code extension: open it from the extensions bar and select the perimeter to switch to.
  </Accordion>

  <Accordion title="Can I use perimeter credentials outside flows on a workstation?">
    Yes. On AWS and Google Cloud, your perimeter credentials are available throughout the workstation environment. CLI tools such as the AWS CLI or `gcloud`, scripts, and notebooks automatically use the credentials of the selected perimeter, whether or not you are using Metaflow.

    When you switch perimeters, the credentials swap automatically, and subsequent commands, scripts, and flows use the new perimeter's credentials.
  </Accordion>

  <Accordion title="How much access does an additional user get on my workstation?">
    Full access, including your deployment credentials. Any flow an additional user runs appears as launched by you, unless they set up their own `outerbounds` configuration on that workstation.

    <Warning>
      Reserve the additional users feature for temporary debugging scenarios. An additional user acts with your credentials, so their actions are indistinguishable from yours.
    </Warning>
  </Accordion>
</AccordionGroup>

## Configuration and images

<AccordionGroup>
  <Accordion title="Can I use a custom Docker image for my workstation?">
    Yes. In the Create a new workstation dialog, paste the image's URI into the **Image** field. You do not need to install anything related to VS Code in your image.

    If the URI has no registry prefix, the platform pulls from public AWS ECR by default. To pull from a different registry, include the registry in the URI. For Docker Hub, the URI format is:

    ```text theme={null}
    docker.io/<MY_REGISTRY>/<MY_IMAGE>:<MY_TAG>
    ```

    <Comments>
      Replace \<MY\_REGISTRY> with your Docker Hub organization or username.<br />
      Replace \<MY\_IMAGE> with the image name.<br />
      Replace \<MY\_TAG> with the image tag.
    </Comments>

    For details on developing with a custom image, see [Managing dependencies](/docs/platform/guides/compute/managing-dependencies).
  </Accordion>

  <Accordion title="How do I build my own workstation image?">
    There are two options for building your own workstation image.

    <Note>
      Whichever option you choose, make sure your deployment can pull the image from its registry. The registry must be reachable from the deployment, and the deployment must have credentials to access it.
    </Note>

    <Tabs>
      <Tab title="Start from a base image">
        Start from one of the platform's base workstation images and add your dependencies on top:

        <CodeGroup>
          ```text CPU base image theme={null}
          006988687827.dkr.ecr.us-west-2.amazonaws.com/obp-workstations/python:<TAG>
          ```

          ```text GPU base image theme={null}
          006988687827.dkr.ecr.us-west-2.amazonaws.com/obp-workstations/nvidia/cuda:<TAG>
          ```
        </CodeGroup>

        <Comments>
          Replace \<TAG> with the version tag of the image. Tags are listed in the image registry.
        </Comments>

        Both images include:

        * A system-wide installation of Python
        * Dependency management tools (including conda and mamba)
        * A default user (`workstation-user`)
        * The home directory set to `/home/ob-workspace`
        * The GitHub CLI (`gh`)
      </Tab>

      <Tab title="Build from scratch">
        Your image must meet these requirements:

        * The user's home directory must be set to `/home/ob-workspace`, and that must be reflected in `/etc/passwd`.

        <Note>
          This is the only directory that persists across workstation hibernations and restarts.

          ***

          The platform's tooling depends on this being the user's home directory.
        </Note>

        * You must include at least one system-wide installation of Python.

        Anaconda also recommends pre-installing tools like `git` and `gh` so users can authenticate with Git providers easily.

        To set the home directory, add the user in your Dockerfile with the home directory set:

        ```dockerfile theme={null}
        RUN useradd -m -d /home/ob-workspace <USERNAME>
        ```

        <Comments>
          Replace \<USERNAME> with the name of the user to create.
        </Comments>

        <Warning>
          If your image uses the root user, you cannot modify `HOME` directly. Edit it in `/etc/passwd` instead:

          ```dockerfile theme={null}
          RUN sed -i 's|root:x:0:0:root:/root|root:x:0:0:root:/home/ob-workspace|' /etc/passwd
          ```
        </Warning>
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="What does the platform install on my workstation?">
    The platform installs:

    * The `outerbounds` CLI and the Metaflow Python package, via `pip install outerbounds`.
    * Credentials to access your deployment, renewed automatically when they expire.

    You do not need to start any VS Code processes on the workstation; they are set up by default.
  </Accordion>

  <Accordion title="What can I modify after the workstation is created?">
    **Editable at any time:**

    * Additional users
    * Auto-hibernation settings

    **Editable only while the workstation is hibernating:**

    * CPU, GPU, memory, and shared memory
    * Disk size (you can only increase it)
    * Base image
    * Compute pool or instance type
  </Accordion>

  <Accordion title="Which image is used when I launch a task with Kubernetes from my workstation?">
    By default, tasks launched with `--with kubernetes` or `argo-workflows` use the workstation's image.

    To override the image for a run:

    <Tabs>
      <Tab title="In the flow code">
        ```python theme={null}
        @kubernetes(image="<IMAGE_URI>")
        ```

        <Comments>
          Replace \<IMAGE\_URI> with the URI of the image to use for the task.
        </Comments>
      </Tab>

      <Tab title="On the command line">
        ```sh theme={null}
        python flow.py run --with kubernetes:image=<IMAGE_URI>
        ```

        <Comments>
          Replace \<IMAGE\_URI> with the URI of the image to use for the task.
        </Comments>
      </Tab>
    </Tabs>
  </Accordion>

  <Accordion title="Can I choose the instance type for my workstation?">
    Yes. When creating or updating the workstation, select the compute pool that corresponds to the instance type you want, provided the pool is configured to allow workstations.

    To check whether a pool supports workstations, select **Compute** in the left-hand navigation, click **Pools**, and select the pool. A pool that supports workstations displays "Available for running Workstations" in its details:

    <Frame>
      <img src="https://mintcdn.com/anaconda-29683c67/VD0yQ0tXYWIdTsBU/images/platform/plat_compute_pools_workstations.png?fit=max&auto=format&n=VD0yQ0tXYWIdTsBU&q=85&s=526bb8a0b0c833ad31fa697bbdbe50af" alt="The Pools tab of the Compute page showing a compute pool marked as available for running workstations" width="1866" height="1082" data-path="images/platform/plat_compute_pools_workstations.png" />
    </Frame>
  </Accordion>

  <Accordion title="Can I configure a default IAM role or GCP service account for my workstation?">
    By default, all processes on the workstation assume the task role of the currently selected perimeter. If that is not sufficient, provision a new role assumable by the task role and contact [Anaconda Support](https://support.anaconda.com/) to make it the default on all workstations.
  </Accordion>
</AccordionGroup>

## Working on a workstation

<AccordionGroup>
  <Accordion title="Which IDEs can I use with my workstation?">
    VS Code or Cursor.
  </Accordion>

  <Accordion title="Can I use Jupyter Notebooks or JupyterLab on my workstation?">
    Yes.

    1. Connect to your workstation using the platform's VS Code extension.

    2. Install JupyterLab and Jupyter Notebook:

       ```sh theme={null}
       conda install jupyterlab notebook
       ```

    3. Launch Jupyter with `jupyter lab` or `jupyter notebook`.

       Jupyter runs on the workstation's localhost, and VS Code automatically port-forwards it to your local machine, so you can open it directly in your browser. Leave the workstation's VS Code window open in the background while you work.

    4. Copy the URL from the command's output into your browser.
  </Accordion>

  <Accordion title="Can I SSH into my workstation?">
    Not directly. If you need SSH access, install and configure `openssh-server` on the workstation. For issues or longer-term solutions, contact [Anaconda Support](https://support.anaconda.com/).
  </Accordion>

  <Accordion title="How do I set up Git access on my workstation?">
    The base workstation images include the `gh` CLI. Run `gh auth login` to authenticate with GitHub. When possible, the platform's VS Code extension forwards your Git credentials to the workstation to minimize setup steps.
  </Accordion>

  <Accordion title="Can I copy files from my local machine to my workstation?">
    For files under 100 MB, drag and drop the file into the workstation's VS Code window. For larger files, use Metaflow's S3 client to store the files in S3, then pull them down to the workstation.
  </Accordion>

  <Accordion title="Can I run a long-running process on my workstation?">
    Anaconda recommends running long-running flows with `argo-workflows`, which offers better reliability. If you need to run the process on your workstation instead, use `tmux` so the process does not depend on your connection to the workstation.
  </Accordion>

  <Accordion title="What directories persist across sessions?">
    `/home/ob-workspace` is the only directory that persists across sessions, hibernations, and restarts.

    <Warning>
      Data outside `/home/ob-workspace` is lost when the workstation hibernates. Save anything you want to keep inside `/home/ob-workspace`.
    </Warning>
  </Accordion>
</AccordionGroup>

## Resources, cost, and lifecycle

<AccordionGroup>
  <Accordion title="What qualifies as activity for auto-hibernation?">
    A workstation is considered active if, within the time window:

    1. A Python process is running, or
    2. A file on the workstation changed.
  </Accordion>

  <Accordion title="When does a workstation occupy cloud instances?">
    Whenever the workstation is running, regardless of whether you are actively working on it, it occupies cloud resources and counts as active usage for billing. Enable auto-hibernation so the workstation hibernates when you are not using it.
  </Accordion>

  <Accordion title="Is workstation usage included in cost reports?">
    Yes. Cost reports include workstation usage.
  </Accordion>

  <Accordion title="How do I check my workstation's CPU and memory usage?">
    The workstation's page shows charts of its CPU and memory utilization. If the workstation is under- or over-provisioned, update its resources.
  </Accordion>

  <Accordion title="Are workstation actions audited?">
    The platform audits workstation creation, spec updates, hibernation, and restarts. The activity log for a workstation is available in the workstations view.
  </Accordion>
</AccordionGroup>

## Troubleshooting

<Troubleshoot>
  <TroubleshootTitle>My workstation is taking a long time to start</TroubleshootTitle>

  <TroubleshootCause>
    Two common causes:

    1. **Lack of capacity**: Clusters keep only the capacity needed for currently running jobs, so your workstation waits while new capacity is provisioned. The delay varies with your cloud provider, instance type, and that instance type's current availability.
    2. **Large image**: Pulling a large image from its registry takes time on first use.
  </TroubleshootCause>

  <TroubleshootSolution>
    Wait for capacity to provision or the image pull to complete. If your workstation takes more than five minutes to start, contact [Anaconda Support](https://support.anaconda.com/).
  </TroubleshootSolution>
</Troubleshoot>

<Troubleshoot>
  <TroubleshootTitle>My workstation is stuck on "Opening remote"</TroubleshootTitle>

  <TroubleshootCause>
    The VS Code remote session occasionally fails to establish a connection to the workstation.
  </TroubleshootCause>

  <TroubleshootSolution>
    Hibernate the workstation and restart it from the platform UI, and restart VS Code as well. This resolves the issue in most cases. If you are still stuck, contact [Anaconda Support](https://support.anaconda.com/).
  </TroubleshootSolution>
</Troubleshoot>