From 1d1928e6d72b5a89f45e81db33f6487f9ad9a5e5 Mon Sep 17 00:00:00 2001 From: Samuel K Date: Tue, 3 Nov 2026 09:53:49 -0600 Subject: [PATCH] docs: correct provider and workspace guidance --- .agents/skills/devsy/references/providers.md | 20 +++++++++++-------- CONTRIBUTING.md | 2 +- hack/ci/README.md | 5 +++-- hack/ci/suites.yaml | 15 -------------- .../continuous-integration.mdx | 2 +- .../create-a-workspace.mdx | 2 +- .../developing-in-workspaces/credentials.mdx | 2 +- .../devcontainer-json.mdx | 2 +- .../inactivity-timeout.mdx | 2 +- .../stop-and-delete-a-workspace.mdx | 4 ++-- .../workspace-snapshots.mdx | 2 +- .../docs/fragments/setup-virtualbox.mdx | 7 +++---- .../tutorials/minikube-vscode-browser.mdx | 8 ++++---- .../docs/tutorials/podman-provider-setup.mdx | 2 +- 14 files changed, 32 insertions(+), 43 deletions(-) diff --git a/.agents/skills/devsy/references/providers.md b/.agents/skills/devsy/references/providers.md index 1a923445e..6b008d1de 100644 --- a/.agents/skills/devsy/references/providers.md +++ b/.agents/skills/devsy/references/providers.md @@ -25,10 +25,14 @@ can change the default. To keep the default, run without initializing it. Options given to add do not carry over to init. To use the provider, find the installed name and run -`devsy provider init ` with the required repeatable -`--option KEY=VALUE` values. Init does not change the default. Then check the -status and the default with `provider_list` before you create a workspace. If -the user asked only for installation, report that init is still needed. +`devsy provider init `. For sensitive options, use the +`DEVSY_PROVIDER__` environment variable instead +of passing `--option KEY=VALUE` on the command line. Use an established +credential mechanism to supply the variable without exposing it in shell +history or logs. See [Safety and authority](safety.md). Init does not change +the default. Then check the status and the default with `provider_list` before +you create a workspace. If the user asked only for installation, report that +init is still needed. After an MCP add, check the default and report any change. Do not turn a request for one workspace into a default change. @@ -39,7 +43,7 @@ later creates that omit a provider and does not move existing workspaces. ## Remove or recover Deleting a provider changes shared configuration and does not repair a -workspace. Confirm the target and intent, and check dependent workspaces. The -delete fails if workspaces use the provider. Do not force-remove the provider or -delete its workspaces to get past that. When a provider fails, diagnose its -configuration, connectivity, or runtime. Do not delete or replace it. +workspace. It fails if workspaces use the provider. When a provider fails, +diagnose its configuration, connectivity, or runtime. Do not delete or replace +the provider or its dependent workspaces as an automatic repair. Delete or +replace only when the user explicitly authorizes the exact target and action. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e9a5db99..b71b7620a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -214,7 +214,7 @@ When your provider is ready: 1. Add your provider to `community.yaml`. 2. Document it in `sites/docs-devsy-sh/content/docs/managing-providers/manage-providers.mdx`. -The docs and the UI then list your provider. +The Desktop provider wizard does not read `community.yaml`. Its additional provider list comes from `devsy-org` repositories whose names start with `devsy-provider-`. ## Desktop deep links diff --git a/hack/ci/README.md b/hack/ci/README.md index b4e77ad6d..a60e248e6 100644 --- a/hack/ci/README.md +++ b/hack/ci/README.md @@ -31,8 +31,9 @@ e2e group from `e2e.suites`. - **Ginkgo spec**: add its label to `e2e.suites` and choose a `group`. Set only the fields that differ from the group defaults, such as `runner`, `test_timeout`, `install_kind`, `install_podman`, `requires_secret`, and - `host_setup`. List labels that another workflow runs in `e2e.ungated` with a - reason. + `host_setup`. List labels that PR CI must not select directly in + `e2e.ungated` with a reason. These include sub-labels exercised by gated + suites and labels run manually or by another workflow. `go test ./hack/ci` fails when a Ginkgo label or Go test package has no tier, or when the manifest names a label that no longer exists. New tests need no diff --git a/hack/ci/suites.yaml b/hack/ci/suites.yaml index cf29fd96d..6ea804566 100644 --- a/hack/ci/suites.yaml +++ b/hack/ci/suites.yaml @@ -1,18 +1,3 @@ -# Test tier manifest for the PR workflow (.github/workflows/pr-ci.yml). -# -# This file is the single place that defines what tests exist, where they run -# and how they run. The workflow contains no per-suite conditions; it asks -# `hack/ci matrix` for its job matrices and `hack/ci unit|e2e|setup` for the -# behaviour. hack/ci/manifest_test.go fails when a Ginkgo label or a Go test -# package is not assigned to a tier here. -# -# To add a test: -# - Go unit test in an ordinary package: nothing to do, it is discovered. -# - Go test in a package under test/ or e2e/ that must run as a unit test: -# add the package to a `unit.steps` entry. -# - Ginkgo spec: add its label to `e2e.suites` (or to `e2e.ungated` with a -# reason when another workflow runs it). - unit: # One job per runner; every runner executes the steps whose `os` matches. runners: diff --git a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/continuous-integration.mdx b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/continuous-integration.mdx index 9d69f42b3..5800096c4 100644 --- a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/continuous-integration.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/continuous-integration.mdx @@ -3,7 +3,7 @@ title: Continuous Integration sidebar_label: Continuous Integration --- -`devsy ci` builds a temporary devcontainer, runs a command in it, and deletes the workspace afterward. Use it to check that your `devcontainer.json` builds and your tests pass inside it. +`devsy ci` starts a devcontainer workspace and runs a command in it. It deletes a newly created workspace afterward unless you pass `--keep`, but never deletes a workspace that existed before the run. Use it to run tests inside the container and check the build of a newly created workspace. ## How it works diff --git a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/create-a-workspace.mdx b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/create-a-workspace.mdx index 38d75a3fe..da702c05b 100644 --- a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/create-a-workspace.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/create-a-workspace.mdx @@ -124,7 +124,7 @@ build/ - A missing or empty file uploads everything. - An unreadable file or invalid pattern stops the upload with an error naming the file. -- The file filters only the workspace folder upload. Extra bind mounts, local Docker bind mounts, and image builds follow their own rules. After a Git clone, Devsy deletes the paths the file lists, matched literally. Devsy does not read `.gitignore` or `.dockerignore`. +- The file filters only the workspace folder upload. Extra bind mounts, local Docker bind mounts, and image builds follow their own rules. After a Git clone, Devsy deletes the paths the file lists, matched literally. A negated rule such as `!build/keep.txt` cannot restore a file deleted with `build/` after a Git clone. Devsy does not read `.gitignore` or `.dockerignore`. ## Inspect a workspace diff --git a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/credentials.mdx b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/credentials.mdx index 5fa11b191..8d39492c7 100644 --- a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/credentials.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/credentials.mdx @@ -73,7 +73,7 @@ Normal completion removes forwarded credentials before Devsy writes config back. ### Connections and troubleshooting -After you change the option, close existing service connections and reconnect. Restart a browser IDE to replace its services connection, and restart any older browser tunnel after you opt in. Changing the option does not revoke tokens that running code already has. +After you change the option, close existing service connections and reconnect. A running browser tunnel keeps the GitHub CLI setting it started with, and restarting the browser IDE reuses that tunnel. After opting out, stop the older browser tunnel process and reconnect so `/github-credentials` requests no longer access its host GitHub accounts. Changing the option does not revoke tokens that running code already has. The guest's shared credential port has one live services owner. SSH sessions carry their expected host and service identity, and a mismatched or older service falls back to local authentication. Browser terminals and external SSH clients carry no session data, so they use the first live services owner. If two hosts use the same guest user, end the first connection before you change the owner. A second browser connection does not change or revoke the first owner's access. diff --git a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/devcontainer-json.mdx b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/devcontainer-json.mdx index 706bbc113..e149fc5bc 100644 --- a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/devcontainer-json.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/devcontainer-json.mdx @@ -98,7 +98,7 @@ After you edit the configuration, apply it without deleting the workspace: devsy workspace up my-workspace --recreate ``` -Devsy applies every change, including the Dockerfile, mounts, and features. It replaces the running container only if the rebuild succeeds. A failed build leaves the existing workspace running. +Devsy builds and validates the new image before stopping or replacing the existing container. If the build fails, the existing workspace stays in its previous state, whether running or stopped. A later failure can leave the old container stopped or removed, depending on the provider. Pass `--recovery` to start a recovery container with features and lifecycle commands disabled if the build fails. Anything outside volumes is lost. The project folder and other mounted paths stay. diff --git a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/inactivity-timeout.mdx b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/inactivity-timeout.mdx index a03196ac1..5681cada6 100644 --- a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/inactivity-timeout.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/inactivity-timeout.mdx @@ -85,6 +85,6 @@ A pod whose daemon uses an older lifecycle protocol must be replaced once. `devs Set `shutdownAction` in `devcontainer.json`. It is not a provider option. - `none` turns off the container timeout monitor. For machines, it also stops `agent.exec.shutdown` from running. -- Any other value turns on the container timeout monitor. For machines, `agent.exec.shutdown` runs when the timeout passes, if the command is set. +- Any other value allows the container timeout monitor to run when the effective timeout is positive. For machines, `agent.exec.shutdown` runs when the timeout passes, if the command is set. When `shutdownAction` is unset, the default is `stopCompose` for Compose workspaces and `stopContainer` for all others. Apart from `none`, and apart from Kubernetes rejecting `stopCompose`, the value does not change what the container timeout does. diff --git a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/stop-and-delete-a-workspace.mdx b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/stop-and-delete-a-workspace.mdx index ee6c3f4fb..837e05302 100644 --- a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/stop-and-delete-a-workspace.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/stop-and-delete-a-workspace.mdx @@ -5,7 +5,7 @@ sidebar_label: Stop or Delete a Workspace ## Stop a workspace -Stopping pauses a workspace so it stops using CPU and memory. Depending on the provider, Devsy stops the container or shuts down the VM it runs on. The data is kept. +Stopping pauses a workspace so it stops using CPU and memory. Depending on the provider, Devsy stops the container or shuts down the VM it runs on. Workspace data is kept unless the provider discards disk state on shutdown, as microsandbox does with `ephemeral` enabled. In Devsy Desktop, open the workspace actions menu and choose **Stop**. From the CLI, run: @@ -25,7 +25,7 @@ Stopping or deleting a workspace first cancels its running `devsy workspace up - ## Delete a workspace -Deleting removes the workspace and all data Devsy stores about it. Depending on the provider, Devsy removes the container or deletes the VM. +Deleting removes the workspace and its local workspace data. Depending on the provider, Devsy removes the container or deletes the VM. Build and lifecycle output in [setup history](../troubleshooting/setup-history.mdx) stays in the local store until retention prunes it. In Devsy Desktop, open the workspace actions menu, choose **Delete**, and confirm. If the delete fails, the workspace detail page shows the error and links to the logs. diff --git a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/workspace-snapshots.mdx b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/workspace-snapshots.mdx index 2db0a717a..c11e05e09 100644 --- a/sites/docs-devsy-sh/content/docs/developing-in-workspaces/workspace-snapshots.mdx +++ b/sites/docs-devsy-sh/content/docs/developing-in-workspaces/workspace-snapshots.mdx @@ -6,7 +6,7 @@ sidebar_label: Workspace Snapshots A snapshot saves a workspace at one point in time: the container filesystem (installed packages, config changes) and the contents of the bind-mounted volume, including uncommitted code. Devsy stores snapshots as OCI artifacts in a registry you control. Restore a snapshot later or use it to move a workspace to another provider. -Devsy pushes snapshots to an OCI registry and pulls them from it. It does not store them locally. You need push and pull access. +Devsy pushes snapshots to an OCI registry and pulls them from it when needed. Creating a snapshot also leaves the committed container image locally after the push, but the registry is still required for the snapshot manifest and volume. You need push and pull access. ## Limitations diff --git a/sites/docs-devsy-sh/content/docs/fragments/setup-virtualbox.mdx b/sites/docs-devsy-sh/content/docs/fragments/setup-virtualbox.mdx index 81b53969b..904b1f171 100644 --- a/sites/docs-devsy-sh/content/docs/fragments/setup-virtualbox.mdx +++ b/sites/docs-devsy-sh/content/docs/fragments/setup-virtualbox.mdx @@ -1,12 +1,11 @@ ## Install VirtualBox -### Minimum machine requirements +### Recommended resources for this walkthrough -Minimum requirements from the [VirtualBox](https://www.virtualbox.org/wiki/End-user_documentation) and -[Ubuntu Desktop](https://ubuntu.com/download/desktop) documentation: +For this walkthrough with [VirtualBox](https://www.virtualbox.org/wiki/End-user_documentation) and [Ubuntu Desktop](https://ubuntu.com/download/desktop), use these resource recommendations. They are not vendor minimum requirements. -| Item | Minimum requirement| +| Item | Recommendation | |---|---| | CPU | dual core CPU | | RAM | 16GB (the walkthrough below allocates 8GB to the guest VM, so the host needs headroom on top of that) | diff --git a/sites/docs-devsy-sh/content/docs/tutorials/minikube-vscode-browser.mdx b/sites/docs-devsy-sh/content/docs/tutorials/minikube-vscode-browser.mdx index 3c4a626a0..a5b472cbc 100644 --- a/sites/docs-devsy-sh/content/docs/tutorials/minikube-vscode-browser.mdx +++ b/sites/docs-devsy-sh/content/docs/tutorials/minikube-vscode-browser.mdx @@ -154,10 +154,10 @@ ls ~/.kube cache completion.bash.inc config ``` -The `config` file in `~/.kube` is the kubeconfig for the Kubernetes provider. Set the kubeconfig path in the provider to: +The `config` file in `~/.kube` is the kubeconfig for the Kubernetes provider. Print its absolute path and use the output when configuring the provider: -``` -/home/dev/.kube/config +```sh +echo ~/.kube/config ``` In production, give the kubeconfig a specific context, namespace, and user. Install kubectl on the machine where the Devsy client runs, because the Kubernetes provider runs kubectl with the local kubeconfig to reach a remote cluster. @@ -191,7 +191,7 @@ Go to **Providers** > **+ Add** and select the Kubernetes provider. |---|---| | Kubernetes Namespace | default | | Disk Size | 1Gi | -| Kubernetes Config | /home/dev/.kube/config | +| Kubernetes Config | The absolute path printed by `echo ~/.kube/config` | Select **Add Provider** diff --git a/sites/docs-devsy-sh/content/docs/tutorials/podman-provider-setup.mdx b/sites/docs-devsy-sh/content/docs/tutorials/podman-provider-setup.mdx index 38b642f51..c3961a3a3 100644 --- a/sites/docs-devsy-sh/content/docs/tutorials/podman-provider-setup.mdx +++ b/sites/docs-devsy-sh/content/docs/tutorials/podman-provider-setup.mdx @@ -114,7 +114,7 @@ devsy workspace ssh my-workspace ### Socket not found or permission denied -Devsy cannot reach the Podman socket. On macOS and Windows, check `podman machine list` and start the machine with `podman machine start`. On Linux, check the user socket: +Devsy cannot reach the Podman socket. On macOS and Windows, check `podman machine list` and start the selected machine with `podman machine start `. On Linux, check the user socket: ```bash systemctl --user status podman.socket