Document development workspaces

2.0/docs/apps/environments.md

@@ -57,6 +57,12 @@ the environment has no active buildable services, and saves the selection for se
 Changes apply to future builds. Existing builds keep the CI provider, registry, and registry repository recorded when
 those builds were created.
 
+## Development workspaces
+
+For persistent code editing over SSH, choose [Development workspace](workspaces.md) when creating an environment.
+This mode is separate from the environment type and cannot be changed after creation. Workspace environments use a
+shared checkout instead of the normal image build and deployment workflow.
+
 ## Copying configuration to a new environment
 
 When you add an environment to an existing app, Step 4 shows `Copy configuration from`. Select another environment of the

2.0/docs/apps/workspaces.md

@@ -0,0 +1,152 @@
+# Development workspaces
+
+A development workspace is an app environment where you or a coding agent can edit a persistent Git checkout and test
+changes against the running application. Commit and push the result, then build and deploy it to a separate Standard
+environment.
+
+!!! note "Availability"
+    Workspace creation must be enabled in Wodby, and the selected stack and cluster must support it. If the option is
+    unavailable, use a Standard environment. A service that supports Git builds does not necessarily support workspaces.
+
+## Workspace or Standard?
+
+| | Development workspace | Standard environment |
+| --- | --- | --- |
+| Application code | Editable Git checkout on persistent storage | Code delivered in a built container image |
+| Updating code | Edit through SSH; reload or restart as the runtime requires | Build and deploy a new image |
+| Git updates | Pull, commit and push explicitly from the checkout | Use the environment's configured CI/CD workflow |
+| Purpose | Development and testing with your tools or agents | Reproducible staging and production deployments |
+
+Choose the execution mode when creating an environment. You cannot switch an existing environment between modes.
+The mode is separate from the [environment type](environment-types.md): selecting `dev` alone does not create a workspace.
+
+A workspace belongs to the user who creates it. Only that owner, while retaining permission to modify the app, can
+connect to its personal SSH runner or change workspace configuration. Normal resource-management permissions still
+apply to pausing and deleting the environment.
+
+## Before you create one
+
+- Select an existing ready cluster that can publish a TCP endpoint for SSH.
+- Choose a stack with one supported source service connected to a Git repository. Any services that share its code,
+  such as a web server, must also support workspace mounts.
+- Provide shared storage that supports ReadWriteMany (RWX). A listed external storage class is not proof that it
+  supports RWX; check with your cluster administrator.
+- Add your public key in [User settings > SSH keys](../user/ssh-keys.md). Keep the private key on your computer.
+- Start with fresh application data. Attaching an existing database or selecting a data import during workspace
+  creation is not supported.
+
+The SSH runner uses additional compute and counts toward service usage. Its resource allocation matches the source
+service. Code and agent-home storage are also billed under normal storage rules.
+
+## Create a workspace
+
+1. Start creating an app, or add an environment from `Apps > [App] > Environments`.
+2. Select the stack and an existing cluster. In the app settings, set **Execution mode** to **Development workspace**.
+   Resolve any eligibility message before continuing.
+3. Under **Workspace checkout**, choose a **Working branch**, **Shared storage**, **Code storage (GiB)** and
+   **Agent home (GiB)**.
+4. Connect the source repository and select the Git reference to start from. The starting reference and the workspace's
+   working branch are separate choices.
+5. Review the services, resource usage and access settings, then create the environment.
+
+Wodby clones the selected source once, prepares dependencies and application setup, then starts the code services.
+Open the environment's **Workspace** page to follow preparation and view participating services. Use its task logs if
+preparation fails.
+
+The initial branch and commit shown there record creation. Use Git inside the workspace to see the current branch,
+HEAD and uncommitted changes.
+
+## Connect your editor or agent
+
+1. As the owner, open **Workspace**, then **Connect**.
+2. Copy the supplied SSH configuration into `~/.ssh/config` and replace `YOUR_PRIVATE_KEY` with your private-key filename.
+3. Run the supplied SSH command and compare the server fingerprint with the one shown in Wodby before accepting it.
+4. Open the working directory shown in the connection details.
+
+Use this SSH connection in a coding tool that supports remote work, or connect with a terminal and run your agent
+inside the workspace. Install and authenticate the agent as required by its provider. Wodby does not include a
+built-in dashboard coding agent.
+
+Agent tools and credentials stored in your private home persist across runner restarts and pauses. Application
+containers do not share that home. The agent can access the application's code and environment through the runner;
+use credentials and application data appropriate for development.
+
+Authenticate Git separately when you need to fetch or push. The credentials Wodby uses for the initial clone do not
+automatically authenticate your SSH session with the Git provider. Do not commit agent credentials or Git tokens.
+Coordinate multiple agents using the same checkout; they can otherwise overwrite each other's edits.
+
+Updating your registered SSH keys refreshes workspace access and ends existing runner sessions. Removing permission
+to modify the app also removes owner access. Revocation can be delayed if the cluster is unreachable.
+
+### MCP controls
+
+[Connect your client to Wodby MCP](../dev/mcp.md) to inspect workspace state and manage its lifecycle. Discover available
+tools from the connected server before using them.
+
+| Tool | What it does |
+| --- | --- |
+| `get_workspace_context` | Reads runtime and preview information, preparation state and initial Git details. |
+| `get_workspace_connection` | Returns the owner's SSH connection details and setup guidance. |
+| `prepare_workspace` | Reruns preparation while preserving the checkout. |
+| `restart_workspace` | Restarts the SSH runner and ends active sessions. It does not restart the application. |
+| `pause_workspace` / `resume_workspace` | Pauses or resumes the environment. |
+
+Read tools require `mcp:read` with OAuth. Lifecycle tools require `mcp:operate` and `confirm: true` reflecting your
+approval; follow the returned task to completion. The `develop_in_workspace` prompt, when offered by your client,
+guides the workflow but does not authorize operations.
+
+Connecting MCP does not connect your editor to SSH or move an existing agent session into the workspace. Workspace
+MCP tools do not edit files or report live Git status. Establish the remote connection separately.
+
+## Edit, reload and prepare
+
+Edits affect this environment's shared checkout. Whether a browser preview updates immediately depends on the service
+and your application. PHP can read changed source on subsequent requests, but application caches may need clearing.
+Development servers need a watcher that works with shared storage; custom Node commands may require polling.
+
+Use **Restart application** when the runtime does not reload changes. This preserves the checkout and does not pull
+Git updates or reinstall dependencies. **Restart SSH runner** only restarts your remote connection service and ends
+SSH and agent sessions.
+
+Use **Retry preparation** after correcting failed setup or when dependencies need preparing again. It stops code
+services while preparation runs; supporting services and an available SSH runner remain usable. Preparation may
+change dependencies and generated files, so review your Git diff afterward. It never pulls, resets or reclones an
+initialized checkout.
+
+Workspace preparation is separate from ordinary post-deployment scripts. Those scripts do not run for workspace
+deployments. After pulling code yourself, decide whether to rerun preparation, run an application-specific command,
+or restart the application.
+
+For Drupal projects with a tracked settings file, include the required Wodby settings bootstrap intentionally in your
+project. Preparation will not rewrite tracked settings or replace tracked upload placeholders. Making a tracked file
+ignored does not remove it from Git.
+
+## Deliver changes to a Standard environment
+
+1. Inspect the current branch and diff inside the workspace. Run the project's tests and check its preview.
+2. Commit the intended source changes and push them to your Git provider.
+3. Open a pull request and complete your normal review process.
+4. Build and deploy the approved code in a separate Standard environment using your usual [CI/CD](../cicd/index.md).
+
+Workspaces use development images and tools. A successful workspace preview does not prove the production image will
+build or run; the Standard environment's build and tests validate that. Local dependency installations, uncommitted
+files and workspace data are not transferred with a Git push. Wodby does not automatically create a PR or a preview
+environment as part of this workflow.
+
+## Limits and recovery
+
+- Code services run one replica without autoscaling. Scheduled jobs remain disabled.
+- Code-service derivatives must be disabled; supporting-service derivatives can remain available.
+- Changing the repository or source links, upgrading the stack, deploying a built image into the workspace, and moving
+  it to another cluster are not supported. Create a new environment for those changes.
+- To protect HTTP previews with [App Access](access.md), choose **Selected endpoints**. **Entire app** protection
+  conflicts with the workspace's published SSH port. HTTP access policies do not protect that SSH endpoint.
+- [Pausing](environments.md#pausing-and-resuming-an-environment) stops workloads and SSH access but preserves code and
+  agent-home storage. Storage remains provisioned and billable; pausing does not delete the cluster.
+- Resume does not pull code. It can retry preparation interrupted by a lifecycle operation, but an ordinary preparation
+  failure requires an explicit retry after you fix the cause.
+- Failed preparation leaves code services stopped. If the SSH runner is ready, connect to inspect and repair the
+  checkout, then retry preparation. A missing or inconsistent checkout needs recovery rather than an automatic reclone.
+
+Before deleting the environment, push any work you need and copy out important local data or agent settings.
+Persistent workspace storage is not a substitute for keeping your source in Git.

2.0/docs/dev/mcp.md

@@ -321,3 +321,9 @@ A plan does not approve deployment, and staging approval does not approve produc
 
 For custom clients and exact behavior, see the [protocol, authentication, task, and log reference](mcp/reference.md)
 and [tool catalog](mcp/tools.md). Use the connected server's schemas for current inputs and capabilities.
+
+## Development workspaces
+
+Use [workspace MCP controls](../apps/workspaces.md#mcp-controls) to inspect a development workspace, retrieve the owner's
+SSH connection details, rerun preparation, or pause and resume it. Connect your editor or agent over SSH separately to
+work on the checkout.

2.0/docs/dev/mcp/tools.md

@@ -23,6 +23,8 @@ These tools require `mcp:read` when using OAuth.
 | `get_app` | Get an app by ID. |
 | `find_environment` | Find an app environment by organization, app name, and the legacy `instanceName` argument. |
 | `list_app_instances` | List app environments with optional project, app, cluster, and status filters by names or IDs. |
+| `get_workspace_context` | Read development workspace runtime, preview, preparation and initial Git information. |
+| `get_workspace_connection` | Get the owner’s SSH endpoint, fingerprint and connection guidance. |
 | `get_app_instance` | Get an app environment by ID. |
 | `prepare_app_creation` | Resolve defaults and return missing questions for creating an app and initial app environment. This does not create anything. |
 | `prepare_app_instance_creation` | Resolve defaults and return missing questions for creating an app environment in an existing app. This does not create anything. |
@@ -79,6 +81,9 @@ These tools require `mcp:operate` when using OAuth.
 
 | Tool | Use |
 | --- | --- |
+| `prepare_workspace` | Rerun workspace preparation, preserving the checkout. Requires `confirm: true`. |
+| `restart_workspace` | Restart the SSH runner, ending sessions; does not restart the application. Requires `confirm: true`. |
+| `pause_workspace` / `resume_workspace` | Pause or resume a workspace environment. Requires `confirm: true`. |
 | `create_deployment` | Create a deployment for one or more app services selected by IDs or by service names with an app environment selector, and suggest waiting for its task. |
 | `redeploy_deployment` | Redeploy from an existing deployment. |
 | `deploy_build` | Deploy a completed app build. |

2.0/docs/user/ssh-keys.md

@@ -10,6 +10,12 @@ Wodby adds your SSH keys to SSHD app services with a published port in apps wher
 
 Changing your SSH keys triggers redeployment of those SSHD services so the updated authorized keys can be applied.
 
+## Development workspaces
+
+[Development workspaces](../apps/workspaces.md#connect-your-editor-or-agent) use the owner's registered keys for their
+personal SSH runner. Other users with writable app access do not receive workspace SSH access. Key changes refresh
+access and end active runner sessions; an unreachable cluster can delay that refresh.
+
 ## Supported key formats
 
 The dashboard accepts the following public key types:

2.0/mkdocs.yml

@@ -207,6 +207,7 @@ nav:
   - Apps:
       - Overview: apps/index.md
       - App environments: apps/environments.md
+      - Development workspaces: apps/workspaces.md
       - Cluster migration: apps/migration.md
       - Maintenance mode: apps/maintenance.md
       - Stack: apps/stack.md