# Workspaces (Coder)

https://coder.k8s.semanticscience.org — sign in with Keycloak.

A workspace is a VM with a durable home directory. It runs under Kata, so it is isolated like a machine, not like a container: you get real `sudo`, your own kernel, and — if you ask for one — a whole GPU.

## Creating one

There is one template, **`workspace`**. It takes these parameters:

| parameter | range | notes |
|---|---|---|
| `cpu` | 1–16 | **keep it ≤ 6 with a GPU** — see the CPU rule below |
| `memory_gb` | 2–64 | Kata sizes the VM from this, up front |
| `gpu_count` | 0–3 | cards are exclusive. Use 1. |
| `gpu_model` | `NVIDIA-A40` | the only option today; it is also what pins a GPU workspace to its node |
| `home_gb` | 10–500 | size of the **`/mnt` scratch disk**, not your home. `/home/coder` is a pre-declared durable volume; ask to have it resized |
| `image` | | the container image; the default is fine |

Requests equal limits, so you get Guaranteed QoS: nobody's burst evicts you, and you cannot burst past what you asked for.

## What survives and what does not

- **`/home/coder`** is your durable volume. It survives stop, delete and rebuild. It is yours; the platform never touches it.
- **`/mnt`** is scratch. Wiped on every rebuild. Put nothing there you cannot regenerate.

## GPU workspaces: the CPU rule

All GPU workspaces run on `fsesrv-g1`: three NVIDIA A40s (46 GiB each) and **32 CPU cores shared by everyone with a card**. Each GPU workspace costs **1 extra core and 10 GiB** of Kata overhead on top of what you request.

So **keep GPU workspaces to 6 CPU** — `3 × (6+1) = 21` leaves room for three people; `3 × (8+1)` does not. The template accepts up to 16 today and does not stop you; what stops you is the scheduler, silently: a request that does not fit sits **Pending with no useful message**. If a GPU workspace will not start, lower `cpu` first. CPU-only workspaces land on the big nodes and may use the full 16.

A build-time check that rejects over-6 with a clear message is on its way (PR #227); until it lands, this is a rule you keep, not one the system keeps for you.

**Stop the workspace when you are not using the GPU.** A running workspace holds its card whether or not anything is on it, and there are three.

## The CLI

```bash
curl -fsSL https://coder.com/install.sh | sh
coder login https://coder.k8s.semanticscience.org

coder list
coder ssh <workspace>            # a real shell; scp, rsync and -L port-forwards work
coder start <workspace>
coder stop <workspace>
coder create <name> --template workspace --yes \
  --parameter cpu=6 --parameter memory_gb=32 --parameter gpu_count=1 \
  --parameter gpu_model=NVIDIA-A40 --parameter home_gb=100 \
  --parameter image=codercom/enterprise-base:ubuntu
coder update <workspace>         # pick up a newer template version
coder tokens create              # a token for scripts
```

When scripting `coder create`, pass **every** parameter listed above — the CLI prompts for any it is missing and fails without a terminal.

## The API

Base `https://coder.k8s.semanticscience.org/api/v2`, header `Coder-Session-Token: <token>`.

```bash
export CODER_TOKEN="$(coder tokens create)"
CODER=https://coder.k8s.semanticscience.org/api/v2

curl -s -H "Coder-Session-Token: $CODER_TOKEN" $CODER/users/me
curl -s -H "Coder-Session-Token: $CODER_TOKEN" $CODER/workspaces
curl -s -X POST -H "Coder-Session-Token: $CODER_TOKEN" -H "Content-Type: application/json" \
  $CODER/workspaces/<id>/builds -d '{"transition":"start"}'     # or "stop"
```

Creating over the raw API needs the template version id and a parameter payload; use `coder create` for that.

## Network from inside a workspace

- Outbound internet goes through a proxy. `HTTPS_PROXY` is preset; `pip`, `curl`, `git` and `sudo apt` just work.
- **You cannot reach other cluster services by internal DNS name.** Always the public hostname — `https://litellm.k8s.semanticscience.org`, never `*.svc.cluster.local`. This is policy, not a bug.