[Workspaces] Auto-select / persist per-user default workspace

agent/scripts/generate_references.py

@@ -419,6 +419,7 @@ def generate_cli_reference():
         'volumes': 'Volume Commands',
         'api': 'API Server Commands',
         'ssh': 'SSH Node Pool Commands',
+        'workspace': 'Workspace Commands',
     }
 
     for group_name, section_title in group_sections.items():
@@ -650,6 +651,8 @@ def generate_python_sdk():
             'stream_and_get',
             'api_get',
             'workspaces',
+            'set_preferred_workspace',
+            'get_user_workspace',
         ],
     }
 

agent/skills/skypilot/references/cli-reference.md

@@ -52,6 +52,7 @@ Launch a cluster or task.
 - `--fast` — [Experimental] If the cluster is already up and available, skip provisioning and setup steps.
 - `--git-url` — Git repository URL.
 - `--git-ref` — Git reference (branch, tag, or commit hash) to use.
+- `--workspace`, `-w` — Workspace to launch into. Shorthand for `--config active_workspace=<name>`.
 
 ### `sky exec`
 
@@ -352,6 +353,7 @@ Launch a managed job from a YAML or a command.
 - `--num-jobs` — Number of jobs to submit.
 - `--git-url` — Git repository URL.
 - `--git-ref` — Git reference (branch, tag, or commit hash) to use.
+- `--workspace`, `-w` — Workspace to submit the managed job into. Shorthand for `--config active_workspace=<name>`.
 - `--yes`, `-y` — Skip confirmation prompt.
 
 ### `sky jobs logs`
@@ -749,6 +751,29 @@ Set up a cluster using SSH targets from a file. If not specified, ~/.sky/ssh_nod
 - `--async` — Run the command asynchronously.
 - `--file`, `-f` — The file containing the SSH targets.
 
+## Workspace Commands
+
+Per-user workspace commands.
+
+### `sky workspace info`
+
+Shows the workspace your next request lands in by default, plus your saved preferred and the workspaces you can access.
+
+**Options:**
+
+- `--config` — Path to a config file or a single key-value pair. To add multiple key-value pairs add multiple flags (e.g. --config nested.key1=val1 --config nested.key2=val2).
+- `-o`, `--output` (default: `table`) — Output format (default: table). Use "json" for a machine-readable shape.
+
+### `sky workspace use`
+
+Sets (or clears with --clear) your default workspace on the server.
+
+**Options:**
+
+- `NAME` — text
+- `--clear` — Clear the saved preferred workspace.
+- `--config` — Path to a config file or a single key-value pair. To add multiple key-value pairs add multiple flags (e.g. --config nested.key1=val1 --config nested.key2=val2).
+
 ## Other Commands
 
 ### `sky debug-dump`

agent/skills/skypilot/references/python-sdk.md

@@ -1212,6 +1212,65 @@ sky.workspaces() -> server_common.RequestId[Dict[str, Any]]
 
 Gets the workspaces.
 
+### `sky.set_preferred_workspace`
+
+```python
+sky.set_preferred_workspace(preferred: Optional[str]) -> Dict[str, Any]
+```
+
+Sets (or clears with None) the user's preferred workspace.
+
+**Args:**
+    preferred: workspace name to set as default, or None to clear.
+
+**Returns:**
+    ``{'preferred': <new value>}`` echoing what was set. Callers that
+    need the resolved workspace + accessible list should follow up
+    with :func:`get_user_workspace`. Raises if the server rejects
+    the change (workspace does not exist, or user lacks permission
+    to it).
+
+### `sky.get_user_workspace`
+
+```python
+sky.get_user_workspace(requested: Optional[str] = None) -> Dict[str, Any]
+```
+
+Returns workspace state for the calling user.
+
+Mirrors the launch-path precedence — if the caller has an explicit
+``active_workspace``, the server returns that with ``source='explicit'``;
+otherwise the resolver runs (preferred / default-fallback /
+single-membership).
+
+**Args:**
+    requested: explicit active workspace to ask about. ``None`` (the
+        default) — the SDK reads your locally-configured
+        ``active_workspace`` (the value `skypilot_config` merges
+        from ``~/.sky/config.yaml`` + ``./.sky.yaml`` + any
+        ``--config active_workspace=X`` override) and forwards it
+        on the wire as ``?requested=``. Pass a non-None value to
+        query the resolver as if ``active_workspace`` were that
+        value, without changing your local config — useful for
+        previewing "what would land if I switched to X".
+
+**Returns:**
+    ``{workspace, source, note, preferred, accessible}``.
+
+    * ``workspace``: the workspace the launch path would pick. Can
+      be ``None`` when the resolver couldn't pick (no access /
+      ambiguous / explicit ``requested`` rejected by RBAC); the
+      reason is then in ``note``.
+    * ``source``: one of ``WORKSPACE_SOURCE_*`` on success, ``None``
+      when ``workspace`` is ``None``.
+    * ``note``: optional message — drift on success
+      (``preferred 'team-x' not accessible``) or the resolver error
+      when ``workspace`` is ``None``.
+    * ``preferred``: the persisted preferred workspace (``None`` if
+      unset).
+    * ``accessible``: sorted list of workspaces the user can launch
+      into.
+
 ## Other Functions
 
 ### `sky.create_debug_dump`

docs/source/reference/api.rst

@@ -293,6 +293,18 @@ API server SDK
 .. autofunction:: sky.api_info
   :noindex:
 
+``sky.set_preferred_workspace``
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autofunction:: sky.set_preferred_workspace
+  :noindex:
+
+``sky.get_user_workspace``
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. autofunction:: sky.get_user_workspace
+  :noindex:
+
 ``sky.api_start``
 ~~~~~~~~~~~~~~~~~
 

docs/source/reference/cli.rst

@@ -208,6 +208,15 @@ Admin CLI
    :nested: full
 
 
+Workspace CLI
+-------------
+
+.. _sky-workspace:
+.. click:: sky.client.cli.command:workspace
+   :prog: sky workspace
+   :nested: full
+
+
 GPUs CLI
 --------
 

sky/__init__.py

@@ -106,11 +106,13 @@ def set_proxy_env_var(proxy_var: str, urllib_var: Optional[str]):
 from sky.client.sdk import endpoints
 from sky.client.sdk import exec  # pylint: disable=redefined-builtin
 from sky.client.sdk import get
+from sky.client.sdk import get_user_workspace
 from sky.client.sdk import job_status
 from sky.client.sdk import launch
 from sky.client.sdk import optimize
 from sky.client.sdk import queue
 from sky.client.sdk import reload_config
+from sky.client.sdk import set_preferred_workspace
 from sky.client.sdk import start
 from sky.client.sdk import status
 from sky.client.sdk import stop
@@ -236,6 +238,8 @@ def set_proxy_env_var(proxy_var: str, urllib_var: Optional[str]):
     'api_status',
     'api_cancel',
     'api_info',
+    'set_preferred_workspace',
+    'get_user_workspace',
     'api_login',
     'api_start',
     'api_stop',

sky/backends/cloud_vm_ray_backend.py

@@ -4140,6 +4140,9 @@ def _dump_code_to_file(codegen: str,
             try:
                 managed_job_info: Optional[jobsv1_pb2.ManagedJobInfo] = None
                 if managed_job_dag is not None:
+                    # `ManagedJobInfo.workspace` is currently not read by
+                    # skylet (see `services.py::QueueJob`). Kept on the
+                    # wire for future consumers.
                     workspace = skypilot_config.get_active_workspace(
                         force_user_workspace=True)
                     entrypoint = common_utils.get_current_command()