# Workspaces A browser-based dev environment (JupyterLab, VS Code, a terminal, and a coding agent) running on your org's GPU allocation. > [!NOTE] > Workspaces run on your organization's **dedicated GPU allocation**. If your org doesn't have one, or you don't have compute access, the **New workspace** button won't appear. Ask your account team or org admin. A **workspace** is your own dev environment in the browser, running on your org's GPUs. Use it to prototype a model, explore a dataset on real hardware, or drive an AI coding agent against a repo, with nothing to set up locally. It gives you JupyterLab, VS Code, a terminal and a built-in coding agent, all in one environment on one home directory. You launch it, work in it for hours or days, and delete it when you're done. Your code, data and model weights never leave your infrastructure. ## What you can do in a workspace - **Code in the browser.** JupyterLab notebooks, a full VS Code editor and a terminal. - **Drive a coding agent on your own models.** OpenCode runs in the workspace terminal and Kilo Code comes set up inside VS Code. Both use your org's models with no key to paste. See [Coding agents](https://docs.privatemind.com/coding-agents.html). - **Work on real GPUs.** A PyTorch and CUDA stack. - **Connect from your own machine.** Use SSH for VS Code Remote-SSH, `scp`, `rsync` and `git`. - **Share the environment.** Make a workspace shared with your org, or co-edit a notebook live. - **Start and stop from anywhere.** The Workspaces page, the `pm` CLI, the API or a schedule. - **Publish what you build.** Open any listening port in the browser with [Port preview](https://docs.privatemind.com/port-preview.html), or publish one port as an app with [App Central](https://docs.privatemind.com/app-central.html). - **Keep your work.** A persistent home volume survives restarts, and [secrets](https://docs.privatemind.com/secrets.html) arrive as files. ## Where it lives Open **Workspaces** under Compute in the sidebar, or go to `/compute/workspaces`. The page lists every workspace you own and any a teammate has shared, each row with buttons to open its surfaces and manage it. ## Launching a workspace Click **New workspace** and choose: | Setting | What it does | | --- | --- | | **Name** | A free-form label. You can rename it later without breaking anything. | | **Type** | The prebuilt environment. A lightweight CPU one for agent-first and general work, a PyTorch GPU one for model work, plus any specialized image your org offers. | | **GPUs** | How many GPUs from your allocation this seat holds. | | **Home volume** | A persistent drive mounted as your home directory. Create one here or reuse an existing volume; its contents survive the workspace. | | **Model weights** | Optional, and shown when your organisation has the [registry](https://docs.privatemind.com/registry.html) on. Up to 8 versions of your org's models, each read-only under `/home/privatemind/models/`, as [Use a model](https://docs.privatemind.com/registry.html#use-a-model) describes. | | **vCPU and memory** | Optional. Blank takes the standard size. On a host dedicated to your organization, the launcher shows what the host has in total. | | **Shared memory** | Optional. The size of `/dev/shm`, which is 64 MiB by default. It comes out of the workspace's memory, so 600 GiB of a 1 TiB workspace leaves about 424 GiB for everything else. | | **Secrets** | Optional, and shown when your organisation has [Secrets](https://docs.privatemind.com/secrets.html) on. Passwords and API keys your code reads as files. | The workspace boots in under a minute, and the CPU type is ready in seconds. A new workspace is **private** to you until you share it. To change the vCPU, memory or shared memory later, open the workspace's menu and pick **Edit compute**. Saving restarts the workspace, so running sessions close. Files in `/dev/shm` stay in memory if a process crashes, and clear when the workspace restarts or stops. The workspace's vCPU and memory share one personal allowance with your inference deployments, training runs and jobs. See [Personal compute quotas](https://docs.privatemind.com/training.html#personal-compute-quotas). Every type has the same four surfaces and the same shell; only the preinstalled science stack differs. On every type the [PrivateMind Python SDK](https://docs.privatemind.com/sdk.html) is preinstalled and configured. The first cell of a notebook can submit a [training job](https://docs.privatemind.com/training.html) or log to MLflow, with no key to paste and no endpoint to set. ## The surfaces Each workspace row has a button per surface. All four open the same files in the same environment, so you can write a script in the editor, run it in the terminal and inspect the output in a notebook. | Surface | What it's for | | --- | --- | | **JupyterLab** | Notebooks and the file browser. | | **VS Code** | The full editor, in a browser tab. | | **Terminal** | A real shell, with `git`, your Python environment, Node.js on current versions, and `nvidia-smi` on a GPU type, on the path. | | **OpenCode** | A terminal coding agent on your org's own models (below). | The workspace runs as an ordinary user, without root, so `sudo` and `apt-get` aren't available. Install Python packages with `pip install --user` or into a virtual environment in your project, and Node.js packages with `npm install` inside the project. Both land on your home volume and survive a restart. The row's **…** menu holds the rest of its actions. **Ports…** lists whatever is listening inside the workspace and opens each one at a URL in your browser. Start `streamlit run app.py` or `uvicorn main:app` in the terminal and it appears there a moment later. See [Port preview](https://docs.privatemind.com/port-preview.html). ## Which version you're on Expand a workspace row and the **What's in it** panel names the version it's running. It lists what that build carries, each with its version: Python, JupyterLab, VS Code, OpenCode, and on a GPU type the CUDA and PyTorch stack. When a newer version is available, the panel shows it, with the release note for each version in between and a **Restart to update** button. A workspace stays on the version it launched with until it restarts: with that button, with **Restart** in the row's **…** menu, or with a **Stop** and then a start. Restarting swaps the image and closes anything running in the workspace, kernels and terminals included. Your home volume is untouched. A workspace moves on its own in one case. When its version is withdrawn for a security fix or a broken build, the platform moves it to the current version and restarts it. On a shared workspace the **Restart to update** button belongs to the owner or a compute admin. Everyone else sees the version and the release notes, and no button. The lightweight CPU type runs Python 3.14 and keeps Python 3.12 beside it. A home volume made on Python 3.12 is moved the first time it starts on this version. Your `pip install --user` packages and virtual environments are reinstalled for 3.14, and the originals are kept with a `.py312` suffix. `~/python-3.14-move.txt` lists what moved, and `pm-python-move undo ` puts an environment back. ## The built-in coding agent **Open OpenCode** gives you a terminal coding agent that reads and writes the same files as your notebook and editor. It works on your actual working tree, with no copy of your repo in between. It runs entirely on **your org's own models**, through the platform. There's no API key to paste and no external provider, so no prompt, file or token leaves your infrastructure. The agent offers your models under stable roles you can switch between: - `coding`, the default; - `reasoning`, for whole-repo work; - `fast`, for quick tasks. > [!TIP] > Type `@` in the agent to pull files into context. It lists files from the directory the agent opened in, so on a brand-new workspace, whose home holds only config files, it finds nothing. Clone or create a project first and open the agent in it: see [Start directory](https://docs.privatemind.com/workspaces.html#start-directory-and-git-identity). To run OpenCode on your own machine against your models, download the same agent configuration from the app. See [Coding agents](https://docs.privatemind.com/coding-agents.html). ## Connectors in the coding agent If your organisation has set them up, the coding agent can reach some of your internal systems directly: a monitoring console, an issue tracker, your Microsoft 365 mail and files. They appear in the agent as MCP servers (tool servers the agent can call). There is no API key or token to paste, because none of them keeps a credential inside your workspace. They arrive switched **off**, so nothing talks to an internal system until you turn its connector on. Most of them need the workspace on a restricted network first, which an organisation admin sets on the workspace. On that network, what a connector returns can't be sent straight back out to the internet. While it is on, the workspace has no route to the public internet, so `pip install`, `npm install` and `git push` stop working. If you need both, use two workspaces, one for each job. **Microsoft 365** reads *your* own mail and files, so it needs two more things: - You have connected Microsoft 365 to your own account in [Connectors](https://docs.privatemind.com/connectors.html), where you sign in to Microsoft and consent. - The workspace is **personal**: the visibility setting where nobody else can open it, not even an organisation admin. On a shared or private workspace somebody other than you could be at the keyboard, so the connector declines to act as you. > [!TIP] > A connector with a single tool whose name ends in `_unavailable` is telling you why it offers nothing. Ask the agent about it, or read the tool's description: it says what to do, such as switching the network, asking an admin or reconnecting your Microsoft 365 sign-in. ## Sharing with your team A workspace is private until you set its **visibility** to **shared**, which lets everyone in your org reach it. Sharing doesn't change the owner. There's no way to claim a shared workspace, so teammates can use it without any of them becoming its owner. Only you or a compute admin can switch it between shared and private. Two people typing into one environment at once would collide, so a shared workspace hands out a **single active session** at a time: - **Open** gives you the surfaces if the workspace is free, stale, or already yours. If a teammate is in it, you'll see **In use by \** instead. - **Take over** (owner or admin) seizes the active session from whoever holds it. - **Release** frees the seat for the next person when you're done. A session you walk away from is reclaimed automatically after 30 minutes. > [!NOTE] > **Release** frees only the seat. The environment keeps running, your kernels stay alive, and the GPUs stay held. To hand the GPUs back, **Stop** the workspace, which keeps its files and can start again later, or **delete** it. Your home volume and everything on it survive either. A workspace that mounts a **personal** volume is closed to everyone else in your organisation, org admins included. Making a volume personal can't be undone. Your own [secrets](https://docs.privatemind.com/secrets.html) go only into a workspace like that, on a personal home volume. Sharing a workspace that holds secrets asks you first, and detaches any secret the people you're adding aren't allowed to read. If all you want to share is one app running in the workspace, such as a dashboard or a demo, publish it with [App Central](https://docs.privatemind.com/app-central.html). The people you choose get that one port, and the workspace stays private. ## Real-time collaboration on a notebook Set a workspace to **Collaborative** and several people can edit the same notebook at once, each with a named cursor and live selections. The **Online Collaborators** panel lists who is in. - It's available on the lightweight CPU workspace type. - Turning it on **restarts** the workspace to serve JupyterLab only, because co-editing is a notebook feature. VS Code, the terminal and OpenCode are unavailable while it's collaborative. The restart clears running kernels, and the app confirms first. - There's no single-active-session lock while it's collaborative. ## Connect from your own machine (SSH) You can point your own machine's tools at a workspace over SSH: VS Code Remote-SSH, `scp`, `rsync` and `git` land in the same environment on the same home directory. There's no VPN and no port to open; the connection uses the same secure path as the browser. Set it up once: 1. **Add your public key.** Open the **SSH Keys** tab in the Workspaces pane and paste your `~/.ssh/id_ed25519.pub` line, as you would on GitHub. One key set applies to every workspace you own, and adding or removing a key reaches your running workspaces without a restart. 2. **Install the helper and sign in.** The app serves a small CLI, already pointed at your deployment: ```sh curl -fsSL https://privatemind.com/pm/install.sh | sh ``` Then run `pm login`. It shows a short code, and you approve it in the browser where you're already signed in. You do this once per machine. 3. **Connect.** The Workspaces pane gives you a ready-made `~/.ssh/config` block. Paste it in and connect with `ssh `, or use **VS Code → Connect to Host** with the same alias. `scp`, `rsync` and `git` work with no extra setup. `pm update` installs the current build from your deployment and shows what's new, and the CLI reminds you when an update is available. If `pm update` is an unknown command, your CLI is older than that command: run the install line in step 2 again, since the commands below need the current build. `pm version` shows the version you have. For help with any command, run `pm help ` or `pm --help`. > [!NOTE] > SSH uses the **owner's** keys. On a shared workspace, teammates work in the browser as themselves, but SSH authenticates by key alone, so shell access uses the owner's keys. ## Stop and start without the browser Besides the Workspaces page, you can stop and start a workspace from the `pm` CLI, from the API or on a schedule. Stopping a workspace shuts it down and gives back what it was using, its GPU included. Its files, projects, name and settings stay, and a stopped workspace still counts towards your workspace limit. Starting it asks for that room again, so a start is refused when there is none, for example when no GPU is free on its cluster. Both are safe to repeat: starting a running workspace or stopping a stopped one changes nothing. **From the CLI.** With `pm` installed and signed in (see above): ```sh pm ls # names and status pm stop pytorch-gpu-k3x9q pm start pytorch-gpu-k3x9q --wait # returns once it is up ``` A unique prefix of the name is enough. Without `--wait`, `pm start` returns as soon as the workspace is starting. With it, `pm` returns once the workspace is up, stops early if it fails to start, and gives up after 15 minutes or whatever `--timeout` says (`--timeout 30m`). A `pm` sign-in is yours and lasts a week, so it suits your own terminal. For a script or a cron job, use an API key. `pm ls`, `pm host`, `pm kube`, and `pm sessions` take `-o json` or `-o yaml` for output a program can read, or `-o name` for the names alone (`pm sessions` prints ids). **From the API.** An [API key](https://docs.privatemind.com/api-keys.html) can start and stop its owner's workspaces. The [Workspaces API](https://docs.privatemind.com/workspaces-api.html) also creates and deletes them, with their volumes. ```sh curl -X POST https://privatemind.com/api/v1/workspaces/pytorch-gpu-k3x9q/stop \ -H "Authorization: Bearer $PMIND_KEY" ``` **On a schedule.** An [automation](https://docs.privatemind.com/cloud-agents.html#scheduled-automations) has a **Workspace** step that starts or stops one of your workspaces, so a GPU workspace can be up at 8am and off at 7pm. For a command that runs and finishes, a [workspace job](https://docs.privatemind.com/sdk-jobs.html) does the work without keeping a workspace up. ## Start directory and git identity Two settings make a fresh workspace feel like yours. **Start directory.** The terminal, VS Code and the coding agent open at your home directory. To open them in another folder under your home, set `startup_dir` when you launch the workspace through the [Workspaces API](https://docs.privatemind.com/workspaces-api.html#launch-a-workspace); it applies to that workspace only. In the app, **Projects** registers `~/projects/` folders on the workspace's home drive, and each project opens in its own tab across JupyterLab, VS Code, the terminal and OpenCode. **Git identity.** Your name and email are seeded into git from your account at launch, so your first `git commit` works with no `Author identity unknown` error. If you've already set your own `user.email` in the workspace, the seed leaves it alone. ## Where next - [Training](https://docs.privatemind.com/training.html): submit training jobs and fine-tunes to your GPU allocation and track every run in MLflow, from a notebook or a script. - [Workspace jobs](https://docs.privatemind.com/sdk-jobs.html): run one command on your home volume without opening a workspace, once or on a schedule. - [Market data](https://docs.privatemind.com/sdk-market-data.html): read the feeds added to a workspace from a notebook; the SDK handles the keys. - [Secrets](https://docs.privatemind.com/secrets.html): attach passwords and API keys to a workspace, where your code reads them from a file. - [Port preview](https://docs.privatemind.com/port-preview.html): open a web server you started in the workspace at a URL in your browser. - [App Central](https://docs.privatemind.com/app-central.html): publish one app from a workspace to the people you choose, without sharing the workspace. - [Coding agents](https://docs.privatemind.com/coding-agents.html): point OpenCode, Kilo Code, Cursor, Cline, and other agents on your own machine at your org's models.