diff --git a/README.md b/README.md index 699df2223..dc19e02a5 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@

-Devsy enables engineering teams to operate at scale using standardized workspaces, reducing hardware costs, saving onboarding time, and improving developer productivity. Devsy users can deploy and use workspaces across Docker, Kubernetes, cloud providers, and SSH remote hosts. +Devsy lets engineering teams operate at scale with standardized workspaces — cutting hardware cost, shortening onboarding, and improving developer productivity. Workspaces deploy across Docker, Kubernetes, cloud providers, and SSH remote hosts. @@ -34,7 +34,7 @@ Devsy enables engineering teams to operate at scale using standardized workspace

Downloads

-Devsy is available as a desktop application and a command-line tool. +Devsy ships as a desktop application and a command-line tool. See the Devsy Docs for installation instructions.

@@ -68,17 +68,17 @@ See the Devsy Docs f - + - + - + @@ -136,7 +136,7 @@ See the Devsy Docs f

Operate Engineering at Scale

-Devsy implements the open DevContainer standard. Development environments remain portable and repeatable across provider backends. +Devsy implements the open DevContainer standard. Workspaces stay portable and repeatable across provider backends.

Linux x64 (AppImage)Linux AppImageLinux AppImage
Linux x64 (Debian/Ubuntu)Linux DEBLinux DEB
Linux x64 (RPM)Linux RPMLinux RPM
Linux
@@ -147,7 +147,7 @@ Lower infrastructure usage with local and remote options plus auto-shutdown cont @@ -167,7 +167,7 @@ Features include prebuilds, inactivity-based shutdown, and Git and Docker creden
No vendor lock-in
-Choose the infrastructure that fits your business. Devsy supports cloud providers and self-managed platforms. +Choose the infrastructure that fits your team. Devsy supports cloud providers and self-managed platforms.
Desktop App
-Use the Devsy desktop app for workspace management. Use the CLI for automation and platform integration. +The desktop app manages workspaces; the CLI drives automation and platform integration.
diff --git a/sites/docs-devsy-sh/pages/developing-in-workspaces/connect-to-a-workspace.mdx b/sites/docs-devsy-sh/pages/developing-in-workspaces/connect-to-a-workspace.mdx index 9d9226c99..e45d3fea7 100644 --- a/sites/docs-devsy-sh/pages/developing-in-workspaces/connect-to-a-workspace.mdx +++ b/sites/docs-devsy-sh/pages/developing-in-workspaces/connect-to-a-workspace.mdx @@ -5,41 +5,38 @@ sidebar_label: Connect to a Workspace ## Connect to a Workspace -After a workspace is successfully created, the workspace is reachable via the ssh host `WORKSPACE_NAME.devsy`. -If you have selected an IDE to automatically open, Devsy will automatically try to open the IDE after a successful workspace creation or `devsy workspace up` command. +Once a workspace is created, it is reachable through the SSH host `WORKSPACE_NAME.devsy`. If you chose an IDE, Devsy opens it after the workspace starts. :::info -You can change the default IDE to open globally via: `devsy ide use vscode` or `devsy workspace up my-workspace --ide vscode` for an individual workspace. +Change the default IDE globally with `devsy ide use vscode`, or per workspace with `devsy workspace up my-workspace --ide vscode`. ::: ### VS Code Browser -Devsy is able to open VS Code in a browser in a workspace. -It will use the open source project [openvscode-server](https://github.com/gitpod-io/openvscode-server) for installing a vscode server binary in the workspace and then tunnel a connection to that binary from the localhost. -To open the workspace inside VS Code browser, you can run the following command: +Devsy can open VS Code in a browser tab. It installs [openvscode-server](https://github.com/gitpod-io/openvscode-server) inside the workspace and tunnels a connection to it from localhost. Open the workspace in VS Code browser with: ``` devsy workspace up my-workspace --ide openvscode ``` -To select a different openvscode version, please run with: +To pick a different openvscode version: ``` devsy workspace up my-workspace --ide openvscode --ide-option VERSION=v1.76.2 ``` ### VS Code -Before connecting VS Code with Devsy, make sure you have installed the [remote ssh extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) and the [code CLI](https://code.visualstudio.com/docs/editor/command-line). Then you can start the workspace directly in VS Code with: +Install the [remote ssh extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) and the [code CLI](https://code.visualstudio.com/docs/editor/command-line). Then start the workspace in VS Code with: ``` devsy workspace up my-workspace --ide vscode ``` :::info SSH Fallback -If for whatever reason this does not work you can also use the regular SSH connection with `WORKSPACE_NAME.devsy` to connect VS Code with a workspace +If this doesn't work, use the regular SSH connection `WORKSPACE_NAME.devsy` to connect VS Code. ::: ### JetBrains Suite (Goland, PyCharm, Intellij etc.) -Make sure you have [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/) installed and a valid jetbrains subscription for your local IDE. The following JetBrains IDEs are supported: +Install [JetBrains Gateway](https://www.jetbrains.com/remote-development/gateway/) and have a valid JetBrains subscription for your local IDE. Supported JetBrains IDEs: * **CLion (clion)** * **Goland (goland)** * **PyCharm (pycharm)** @@ -49,75 +46,82 @@ Make sure you have [JetBrains Gateway](https://www.jetbrains.com/remote-developm * **Rider (rider)** * **RubyMine (rubymine)** -Then start your workspace via: +Start your workspace with: ``` devsy workspace up my-workspace --ide goland ``` -Which will install the goland server binary into the workspace and then open JetBrains Gateway to open this workspace. +Devsy installs the GoLand server binary into the workspace and opens JetBrains Gateway. After installation, the Gateway SSH dialog appears pre-filled — click **Check Connection and Continue** to start the IDE inside the workspace. -After successful installation the Gateway SSH dialog will popup prefilled with the correct information, please click **Check Connection and Continue**, which will start your desired IDE inside the workspace. - -To select a different IDE version, please run with: +To pick a different IDE version: ``` devsy workspace up my-workspace --ide goland --ide-option VERSION=2022.3.3 ``` :::info SSH Fallback -If for whatever reason this does not work you can also use the regular SSH connection with `WORKSPACE_NAME.devsy` to connect your JetBrains IDE with a workspace +If this doesn't work, use the SSH host `WORKSPACE_NAME.devsy` to connect your JetBrains IDE. ::: :::info Fleet Support -Fleet currently only works by manually adding an SSH connection with `WORKSPACE_NAME.devsy` +Fleet only works by manually adding an SSH connection to `WORKSPACE_NAME.devsy`. ::: ### SSH -Upon workspace creation, Devsy will automatically modify the `~/.ssh/config` to include an entry for `WORKSPACE_NAME.devsy`, which allows you to use the following command to connect to your workspace: +When a workspace is created, Devsy adds an entry for `WORKSPACE_NAME.devsy` to `~/.ssh/config`. Connect with: ``` ssh WORKSPACE_NAME.devsy ``` -This also allows you to connect any IDE that supports remote development through SSH via the given host `WORKSPACE_NAME.devsy`. +Any IDE that supports remote development over SSH can also use this host. ### Devsy CLI -If you don't have `ssh` installed or cannot connect through any other IDE, you can use the following Devsy command to access a workspace: +If you don't have `ssh` installed or can't connect through an IDE, use the Devsy CLI: ``` devsy workspace ssh my-workspace ``` -Optionally you can also define a command to run: +Run a command non-interactively: ``` devsy workspace ssh my-workspace --command "echo Hello World" ``` ## IDE Commands -This section shows additional commands to configure Devsy's behavior when opening a workspace. +Configure how Devsy opens workspaces with these commands. ### Configure IDE Options -You can specify certain options such as IDE version and download path if needed. You can list the available options for an IDE via: +Each IDE supports options like version and download path. List them with: ``` devsy ide get openvscode ``` -You will see available options and default values for them. To change an option, you can run: +Change an option with: ``` devsy ide set openvscode -o VERSION=v1.76.2 ``` ### Change Default IDE -To change the default IDE Devsy will use for connecting to a workspace, please run: +Set the default IDE Devsy uses to open workspaces: ``` devsy ide use vscode ``` ### List supported IDEs -You can list all Devsy supported IDEs via: +List every IDE Devsy supports: ``` devsy ide list ``` + +## Desktop shortcuts + +Devsy Desktop ships a command palette and section shortcuts for fast navigation: + +- `Cmd/Ctrl + K` — open the command palette (search workspaces, providers, machines, and pages). +- `Cmd/Ctrl + N` — start the New Workspace wizard. +- `Cmd/Ctrl + 1` through `Cmd/Ctrl + 8` — jump to Dashboard, Workspaces, Providers, Machines, Contexts, Terminals, SSH Keys, and Settings. +- `Esc` — close the active sheet, dialog, or palette (where supported). diff --git a/sites/docs-devsy-sh/pages/developing-in-workspaces/create-a-workspace.mdx b/sites/docs-devsy-sh/pages/developing-in-workspaces/create-a-workspace.mdx index 38f61f5de..8ba40a210 100644 --- a/sites/docs-devsy-sh/pages/developing-in-workspaces/create-a-workspace.mdx +++ b/sites/docs-devsy-sh/pages/developing-in-workspaces/create-a-workspace.mdx @@ -5,23 +5,28 @@ sidebar_label: Create a Workspace ## Create a Workspace -You can create a workspace either from the Devsy CLI or through the Devsy desktop application. A workspace can be created from a Git repository, a local path or a Docker container (e.g. `golang:latest`). +Create workspaces from the Devsy CLI or the Desktop app. A workspace's source can be a Git repository, a local path, or a Docker image (e.g. `golang:latest`). -Upon successful creation, Devsy will make the development container available through the ssh host `WORKSPACE_NAME.devsy`. Alternatively, Devsy can automatically open the workspace in a locally installed IDE, such as VS Code or Intellij. +Once created, the workspace is reachable through the SSH host `WORKSPACE_NAME.devsy`, or Devsy can open it in a local IDE like VS Code or IntelliJ. :::info -A workspace is defined through a `devcontainer.json`. If Devsy can't find one, it will automatically try to guess the programming language of your project and provide a fitting template. +A workspace is defined by a `devcontainer.json`. If none exists, Devsy detects the project's language and picks a matching template. ::: ### Via Devsy Desktop Application -Navigate to the 'Workspaces' view and click on the 'Create' button in the title to open the create-workspace wizard. The wizard walks through five steps: +Open the Workspaces view and click **Create** to launch the wizard. It walks through five steps: -1. **Provider**: Select an initialized provider to host the workspace. Cannot be changed later. If no initialized provider exists, the wizard prompts you to add one (navigates to 'Providers' > 'Add'). -2. **Source**: Pick one of the Quick Start templates or enter a custom source (Git URL, image, or local path). Use 'Show advanced options' to optionally set a **Workspace Folder** (a subfolder within the source to use as the workspace root). -3. **IDE**: Choose an IDE to open the workspace with. Optional; the default is `none`. -4. **Review**: Optionally override the auto-derived **Workspace Name** and confirm the configuration. -5. **Launch**: Devsy creates the workspace and streams progress. The workspace is launched in the chosen IDE on success. +1. **Provider** — pick an initialized provider. Cannot be changed later. If none exists, the wizard offers to add one. +2. **Source** — choose a Quick Start template, browse the image catalog, or enter a custom Git URL / image / local path. **Show advanced options** reveals: + - Ref Type and value (branch, commit, or PR number) for Git sources. + - Project subfolder within the repo. + - Open folder in container (where the editor opens). + - Dev container config path (override `.devcontainer/devcontainer.json` location). + - Prebuild repository for cached images. +3. **IDE** — pick one or more IDEs to open the workspace with. Optional; defaults to none. +4. **Review** — adjust the auto-derived workspace name and confirm the configuration. If the chosen image has no build for your machine architecture, the Review step shows a compatibility warning and a **Run under emulation** toggle. +5. **Launch** — Devsy creates the workspace and streams progress. A 10-minute watchdog cancels the launch if it stalls. The chosen IDE opens on success. :::info Under the hood, the Desktop Application will call the CLI command `devsy workspace up REPOSITORY` @@ -38,7 +43,7 @@ For example: setting `--home=/mnt/c/Users/MyUser/` will result in a workspace pa ### Via Devsy CLI -Make sure to [install the Devsy CLI locally](../getting-started/install.mdx#install-devsy-cli) and select a provider you would like to host the workspace on (such as local docker) via: +[Install the Devsy CLI](../getting-started/install.mdx#install-devsy-cli) and add a provider to host the workspace (such as local docker): ``` # Add a provider if you haven't already devsy provider add docker @@ -46,14 +51,14 @@ devsy provider add docker #### Git Repository -Run the following command in a terminal to start a new workspace: +Start a new workspace from a Git repository: ``` # Create from Git repository devsy workspace up github.com/microsoft/vscode-remote-try-node ``` -You can check out specific states of the repository by appending a commit hash, branch or Pull Request slug to the repository url: +Append a commit hash, branch, or pull request slug to the URL to check out a specific ref: ``` Branch: devsy workspace up github.com/microsoft/vscode-remote-try-node@main Commit: devsy workspace up github.com/microsoft/vscode-remote-try-node@sha256:15ba80171af11374143288fd3d54898860107323 @@ -61,77 +66,108 @@ PR: devsy workspace up github.com/microsoft/vscode-remote-try-node@pull/108/ ``` :::info Private Git Repositories -Devsy will forward git credentials to a remote machine so that you can also pull private repositories. +Devsy forwards your git credentials to the remote machine so private repositories work too. ::: - :::info Multiple workspaces from the same repository -Use the `--id` flag to override the name of the workspace. This allows you to create multiple workspaces from the same repository. +Pass `--id` to override the workspace name. This lets you spin up multiple workspaces from one repository. ::: #### Local Path -Run the following command in a terminal to create a new workspace: +Create a workspace from a local folder: ``` # Create from a local path devsy workspace up ./path/to/my-folder ``` -Devsy will sync the folder into the remote machine and create a development environment from the `devcontainer.json`. +Devsy syncs the folder onto the remote machine and builds the dev environment from the `devcontainer.json`. #### Docker Image -Run the following command in a terminal to create a new workspace from a docker image: +Create a workspace from a Docker image: ``` # Create from a docker image devsy workspace up ghcr.io/my-org/my-repo:latest ``` -Devsy will create the following `.devcontainer.json`: +Devsy generates the following `.devcontainer.json`: ``` { "image": "ghcr.io/my-org/my-repo:latest" } ``` +##### Run under a different platform + +Pass `--platform` to run the container under a non-native architecture (via QEMU emulation on Docker). This is useful for images that only ship `linux/amd64` when you're on Apple Silicon. + +``` +devsy workspace up ghcr.io/my-org/my-repo:latest --platform linux/amd64 +``` + +:::warning Emulation cost +Emulated containers can be significantly slower than native ones. Prefer multi-arch images when available. +::: + +##### Image catalog (Desktop) + +Devsy Desktop ships a curated catalog of pre-built devcontainer images. The Source step of the workspace wizard surfaces them in an image picker and flags incompatible images (e.g. an `arm64`-only image on an `amd64` host). The CLI accepts any of these images as a `--source` or positional argument. + #### Existing local container -If you have a local container running, you can create a workspace from it by running: +Bind a workspace to a container that is already running: ``` devsy workspace up my-workspace --source container:$CONTAINER_ID ``` -This only works with the `docker` provider. +Only the `docker` provider supports this. :::info -Using `--recreate` on a workspace based on an already existing container will be rejected. +`--recreate` is rejected on a workspace backed by an existing container. ::: +## Inspect a workspace + +`devsy workspace describe ` prints a workspace's full configuration plus its live state. By default it renders a `Field | Value` table; pass `--result-format json` for machine-readable output (Devsy Desktop uses the JSON form). + +```sh +devsy workspace describe my-workspace +devsy workspace describe my-workspace --result-format json +``` + +Other useful inspection commands: + +- `devsy workspace status ` — quick state check (`Running`, `Stopped`, `NotFound`). +- `devsy workspace logs ` — stream the agent logs from the container. +- `devsy workspace ping ` — verify the agent is reachable through the tunnel. +- `devsy workspace troubleshoot ` — bundle diagnostics for issue reports. + ## Recreating a workspace -If you are working on the `devcontainer.json` or have pulled changes that affect the development environment, you can recreate a workspace. Recreating a workspace means to apply changes in the `devcontainer.json` or related `Dockerfile` to the development environment. If a prebuild repository is supplied, Devsy will try to find the updated development environment image inside the prebuild repository and if not found will fall back to building it. +Recreating a workspace re-applies changes from the `devcontainer.json` or its `Dockerfile`. Use this after editing the devcontainer or pulling new changes that affect the dev environment. If a prebuild repository is configured, Devsy looks for the updated image there first and falls back to building locally. -When recreating a workspace, changes only to the project path or mounted volumes will be preserved. **All other changes made in the container will be lost.** +Only changes inside the project path or mounted volumes survive a recreate. **Everything else in the container is lost.** ### Via Devsy CLI -Run the following command to rebuild an existing workspace: +Rebuild an existing workspace: ``` devsy workspace up my-workspace --recreate ``` ## Resetting a workspace -Some scenarios require pulling in the latest changes from a Git repository or re-uploading your local folder. If instead of recreating the devcontainer you need to completely restart your workspace from a clean slate, use `Reset` over `Recreate`. +Reset rebuilds the workspace from a clean slate — it pulls the latest Git changes or re-uploads your local folder. Use it instead of `--recreate` when you need a full restart. -** When recreating a workspace, no changes will be preserved! ** +**A reset preserves nothing.** ### Via Devsy CLI -Run the following command to reset an existing workspace: +Reset an existing workspace: ``` devsy workspace up my-workspace --reset ``` diff --git a/sites/docs-devsy-sh/pages/developing-in-workspaces/mcp-server.mdx b/sites/docs-devsy-sh/pages/developing-in-workspaces/mcp-server.mdx new file mode 100644 index 000000000..d7693e9ca --- /dev/null +++ b/sites/docs-devsy-sh/pages/developing-in-workspaces/mcp-server.mdx @@ -0,0 +1,59 @@ +--- +title: Agent Control via MCP +sidebar_label: Agent Control (MCP) +--- + +# Agent Control via MCP + +`devsy mcp serve` runs a [Model Context Protocol](https://modelcontextprotocol.io) server over stdio. MCP-compatible AI clients can connect to it and drive Devsy — listing, creating, and executing inside workspaces — without shelling out to the CLI themselves. + +```sh +devsy mcp serve +``` + +The server reads JSON-RPC frames from stdin and writes them to stdout. Configure your MCP client to launch the command; it will discover the registered tools at startup. + +## Tools exposed + +The server registers 11 tools across workspace and provider domains: + +| Tool | Purpose | +|---|---| +| `workspace_list` | List all workspaces with provider, IDE, and source. | +| `workspace_status` | Get detailed status for a workspace. | +| `workspace_create` | Create and start a new workspace. | +| `workspace_start` | Start (or resume) an existing workspace. | +| `workspace_stop` | Stop a running workspace. | +| `workspace_delete` | Delete a workspace by name. Accepts `force=true`. | +| `workspace_exec` | Run a one-shot command inside a running workspace. | +| `provider_list` | List configured providers. | +| `provider_add` | Add a provider from a registry name, GitHub URL, or local path. | +| `provider_delete` | Remove a configured provider. | +| `provider_use` | Set the default provider for new workspaces. | + +`workspace_exec` is bounded by three server flags: + +- `--exec-timeout-default` (default `5m`) — default per-call timeout. +- `--exec-timeout-max` (default `30m`) — caller-supplied timeouts are clamped to this. +- `--exec-output-cap` (default `100 KiB`) — per-stream byte cap; excess is replaced with a truncation marker. + +## Example client config + +The exact format depends on your MCP client, but every client needs the command to launch and any arguments. A generic JSON shape looks like: + +```json +{ + "mcpServers": { + "devsy": { + "command": "devsy", + "args": ["mcp", "serve"] + } + } +} +``` + +Check your client's documentation for where this config lives (e.g. `claude_desktop_config.json` for Claude Desktop). Refer to the [MCP specification](https://modelcontextprotocol.io/specification) for transport and tool semantics. + +## Security + +The MCP server has the same authority as your local Devsy CLI. A connected client can create, modify, and delete workspaces, run arbitrary commands inside them, and add or remove providers. Only enable `devsy mcp serve` for clients you trust. diff --git a/sites/docs-devsy-sh/pages/getting-started/install.mdx b/sites/docs-devsy-sh/pages/getting-started/install.mdx index 8a97935a1..2e826c010 100644 --- a/sites/docs-devsy-sh/pages/getting-started/install.mdx +++ b/sites/docs-devsy-sh/pages/getting-started/install.mdx @@ -7,40 +7,38 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; -To get started with Devsy, choose either the [Devsy Desktop](#install-devsy) application or the [Devsy CLI](#install-devsy-cli). +Choose either [Devsy Desktop](#install-devsy) or the [Devsy CLI](#install-devsy-cli). ## Install Devsy Download Devsy Desktop: -- [MacOS Silicon/ARM](https://github.com/devsy-org/devsy/releases/latest/download/Devsy_macos_aarch64.dmg) -- [MacOS Intel/AMD](https://github.com/devsy-org/devsy/releases/latest/download/Devsy_macos_x64.dmg) -- [Windows](https://github.com/devsy-org/devsy/releases/latest/download/Devsy_windows_x64_en-US.msi) -- [Linux AppImage](https://github.com/devsy-org/devsy/releases/latest/download/Devsy_linux_amd64.AppImage) -- [Linux Targz](https://github.com/devsy-org/devsy/releases/latest/download/Devsy_linux_x86_64.tar.gz) +- [macOS Silicon/ARM](https://github.com/devsy-org/devsy/releases/latest/download/Devsy_mac_arm64.dmg) +- [macOS Intel/AMD](https://github.com/devsy-org/devsy/releases/latest/download/Devsy_mac_x64.dmg) +- [Windows](https://github.com/devsy-org/devsy/releases/latest/download/Devsy_win_x64.exe) +- [Linux AppImage](https://github.com/devsy-org/devsy/releases/latest/download/Devsy_linux_x86_64.AppImage) +- [Linux DEB (Debian/Ubuntu)](https://github.com/devsy-org/devsy/releases/latest/download/Devsy_linux_amd64.deb) +- [Linux RPM (Fedora/RHEL/openSUSE)](https://github.com/devsy-org/devsy/releases/latest/download/Devsy_linux_x86_64.rpm) +- [Linux Flatpak](https://github.com/devsy-org/devsy/releases/latest/download/Devsy.flatpak) :::info Previous Releases For earlier versions, visit the [GitHub releases page](https://github.com/devsy-org/devsy/releases) ::: :::info Linux Packages -**The official package is the Appimage**, it has been tested working on: +The AppImage is tested on: - Debian 12 and newer - Ubuntu 22.04 and newer - Fedora 36 and newer -- Opensuse Leap 15.3 and newer -- Opensuse Tumbleweed -- Archlinux +- openSUSE Leap 15.3 and newer +- openSUSE Tumbleweed +- Arch Linux -Make sure you have the following dependencies installed for the Appimage to work (usually already installed in desktop distributions): +Most modern desktop distros include the required libraries. If the AppImage fails to launch, install FUSE and the standard GTK/Electron runtime libs: -- glibc version 2.35+ -- fuse2, fuse2 libraries, libopengl, libfribidi, libegl, libxgl - - `sudo apt-get install fuse libfuse2 libopengl0 libfribidi0 libgles2-mesa` - - `sudo dnf install fuse fuse-libs libglvnd-egl libglvnd-opengl libglvnd-glx harfbuzz fontconfig fribidi libthai` - - `sudo zypper in fuse libfuse2 libharfbuzz0 libfribidi0 libthai0` - -These are generally needed for AppImage to work; they are not specific to Devsy. +- Debian/Ubuntu: `sudo apt-get install libfuse2 libgtk-3-0 libnotify4 libnss3 libxss1 libxtst6 xdg-utils libatspi2.0-0` +- Fedora: `sudo dnf install fuse-libs gtk3 libnotify nss libXScrnSaver libXtst xdg-utils at-spi2-core` +- openSUSE: `sudo zypper in libfuse2 gtk3 libnotify4 mozilla-nss libXss1 libXtst6 xdg-utils` ::: :::info Windows Packages @@ -48,34 +46,16 @@ Make sure you have the following dependencies installed for the Desktop App to w - [WebView 2](https://developer.microsoft.com/en-us/microsoft-edge/webview2/?form=MA13LH) -Note that WebView 2 is normally already installed on recent versions of Windows and should not need installing unless you experience issues. +WebView 2 ships with recent versions of Windows. Install it only if you hit issues. ::: -:::info Linux Custom Packages -Since we're not providing deb or rpm packages anymore, we're now providing a tar.gz -that can be used as source for your custom package. - -Keep in mind the following dependencies need to be declared in the package for the -correct functioning of the program: - -- libappindicator3-1 -- libgdk-pixbuf2.0-0 -- libbsd0 -- libxdmcp6 -- libwmf-0.2-7 -- libwmf-0.2-7-gtk -- libgtk-3-0 -- libwmf-dev -- libwebkit2gtk-4.1-0 -- librust-openssl-sys-dev -- librust-glib-sys-dev - -On Fedora: `sudo dnf install libappindicator-gtk3` +:::info Linux Packaging +Devsy publishes `.deb`, `.rpm`, `.AppImage`, and Flatpak builds. The DEB and RPM packages declare their runtime dependencies; the AppImage and Flatpak bundle theirs. ::: ## Install Devsy CLI -Alternatively, you can also use the CLI instead of the desktop application. The Devsy CLI is useful for managing Devsy directly from a terminal. Choose an installation method below, or install it later from the Desktop App." +The Devsy CLI manages Devsy from a terminal. Choose an installation method below, or install it later from the Desktop App. Devsy Flow
Update available
-The update will continue in the background. When it's done you'll be prompted to restart the application. +The update downloads in the background. When it's ready, Devsy prompts you to restart.
Devsy Flow
Update complete — restart required
-At restart the application will be at latest version. +After restart, Devsy runs the latest version. -## Devsy Desktop - alternative +## Devsy Desktop — alternative -If you installed Devsy using deb or rpm packages, you'll need to [download the -new package](https://github.com/devsy-org/devsy/releases/latest/), and install it using your package manager again. +If you installed Devsy from a deb or rpm package, [download the new package](https://github.com/devsy-org/devsy/releases/latest/) and install it again through your package manager. -## Optional: Update Devsy CLI +## Update Devsy CLI -If you just installed the CLI, you just need to download the latest version again -to update. +Re-run the installation command from [Install Devsy CLI](./install.mdx#install-devsy-cli) to download the latest version. diff --git a/sites/docs-devsy-sh/pages/how-it-works/overview.mdx b/sites/docs-devsy-sh/pages/how-it-works/overview.mdx index 9ee645c8d..8b91f0cce 100644 --- a/sites/docs-devsy-sh/pages/how-it-works/overview.mdx +++ b/sites/docs-devsy-sh/pages/how-it-works/overview.mdx @@ -3,16 +3,14 @@ title: How it works sidebar_label: Overview --- -Devsy provides the ability to provision workspaces on any infrastructure. It does so by wrapping your conventional CLI tools such as kubectl, docker, gcloud etc to deploy your development environment -and set up everything required to run the dev container. While creating the workspace Devsy deploys an agent to the machine running the container as well as to the container itself to provide useful -functions such as port forwarding, credential forwarding and log streaming. Doing so it provides a control plane across your development environment. +Devsy provisions workspaces on any infrastructure. It wraps the CLI tools you already use — `kubectl`, `docker`, `gcloud`, and others — to deploy your development environment and run the dev container. When creating a workspace, Devsy deploys an agent to both the host machine and the container to handle port forwarding, credential forwarding, and log streaming. The agent acts as a control plane across your development environment. -Devsy uses a client-agent architecture, where the client deploys it's own agent to host various servers, such as a grpc server or SSH server. -In this regard the system is not unlike a browser server architecture where the front end is deployed and executed on a remote host. There are several improvements this brings to our specific context: - - There can be no conflict of versions between client and server, since you install only one version of the client - - There is no infrastructure to manage for users +Devsy uses a client-agent architecture. The client deploys its own agent, which hosts a gRPC server and an SSH server. This resembles a browser-server architecture where the front end is delivered to a remote host. Two practical wins: -To simplify debugging, Devsy connects your local shell with the agent's STDIO so you can see what's happening locally and in the container at all times. +- No version conflict between client and server — you only install the client. +- No infrastructure to manage. + +For easier debugging, Devsy pipes the agent's STDIO to your local shell so you can see what's happening locally and inside the container. Below is a high level overview of how Devsy uses your local environment, a source repo and a devcontainer to deploy your workspace to the cloud. @@ -21,11 +19,8 @@ Below is a high level overview of how Devsy uses your local environment, a sourc
Devsy - Component Diagram
-Devsy establishes a connection to the workspace using a vendor specific API. This vendor specific communication channel is referred to as the "tunnel". When you run a `devsy workspace up` command, Devsy selects a -provider based on your context and starts your devcontainer. If using a machine provider, Devsy will check if it should create a VM first. Once the devcontainer -is running Devsy deploys an agent to the container. The way in which Devsy communicates with the workspace depends on the provider, this is known as the "tunnel". For AWS this could be instance connect, kubernetes uses -the kubernetes control plane (kubectl), this connection is secured based on this tunnel. The Devsy agent starts a SSH server using the STDIO of the secure tunnel in order for your local Devsy CLI/UI to forward -ports over the SSH connection. Once this is done Devsy starts your local IDE and connects it to the devcontainer via SSH. +Devsy connects to the workspace through a vendor-specific channel called the **tunnel**. When you run `devsy workspace up`, Devsy picks a provider based on your context and starts your devcontainer. Machine providers create a VM first if needed. Once the devcontainer is running, Devsy deploys the agent into it. + +The tunnel's transport depends on the provider — AWS uses Instance Connect, Kubernetes uses the control plane via `kubectl`, and so on. The Devsy agent starts an SSH server over the tunnel's STDIO so the local CLI/UI can forward ports. Devsy then opens your local IDE and connects it to the devcontainer over SSH. -If you developer environment requires any port forwarding, then your IDE or an SSH connection must be running. That's because devsy needs the SSH server running on the agent to perform the forwarding, -which is deployed when starting the IDE or SSH session. +Port forwarding requires an active IDE or SSH session — Devsy needs the agent's SSH server, which only runs while one of those connections is open. diff --git a/sites/docs-devsy-sh/pages/managing-machines/manage-machines.mdx b/sites/docs-devsy-sh/pages/managing-machines/manage-machines.mdx index 9ad98fd08..bb6c6af11 100644 --- a/sites/docs-devsy-sh/pages/managing-machines/manage-machines.mdx +++ b/sites/docs-devsy-sh/pages/managing-machines/manage-machines.mdx @@ -5,19 +5,19 @@ sidebar_label: Manage Machines ## Create a machine -You can create a new machine using: +Create a new machine with: ```sh devsy machine create --provider ``` -At any point you can list all the machines using: +List all machines: ```sh devsy machine list ``` -An example output would be: +Example output: ``` NAME | PROVIDER | AGE @@ -25,7 +25,7 @@ An example output would be: | aws | 21s ``` -You can check in which state is a machine using: +Check the state of a machine: ```sh devsy machine status @@ -39,23 +39,21 @@ Example output: ## SSH into a machine -It is possible to SSH directly into the provider's machine using +Open an SSH session directly to the machine: ```sh devsy machine ssh ``` -This will open a full ssh session to the machine. - ## Stop a machine -Stopping a machine is as easy as: +Stop a machine with: ```sh devsy machine stop ``` -You can check the status afterwards using: +Check the status afterwards: ```sh devsy machine status @@ -69,13 +67,12 @@ Example output: ## Delete a machine -Finally, you can delete the machine simply using: +Delete a machine with: ```sh devsy machine delete ``` :::warning -**Be aware**: this is non-reversible, all the workspace containers, and data will be -lost after deletion. +This is non-reversible. All workspace containers and data on the machine are lost. ::: diff --git a/sites/docs-devsy-sh/pages/managing-providers/add-provider.mdx b/sites/docs-devsy-sh/pages/managing-providers/add-provider.mdx index c3c84a8a1..02d207fa3 100644 --- a/sites/docs-devsy-sh/pages/managing-providers/add-provider.mdx +++ b/sites/docs-devsy-sh/pages/managing-providers/add-provider.mdx @@ -27,28 +27,29 @@ devsy provider list --available ## Via Devsy Desktop Application -Navigate to the 'Providers' view and click on the 'Add' button in the title. -Select one of the providers supplied by default, or click on the '+' button to -add a custom one. +Open the Providers view and click **Add**. The provider wizard has four steps: -You will be prompted to fill some additional settings if needed, depending on -the provider's needs. +1. **Select** — pick a built-in preset, or enter a GitHub link, `provider.yaml` URL, or local file path in the **Provider Source** field below the presets. +2. **Configure** — fill in provider-specific options (the form is generated from the provider's schema). +3. **Initialize** — Devsy runs the provider init and streams logs. +4. **Done** — review the result. Failures show the underlying error. + +The ProviderSheet (click any provider in the list) exposes edit settings, switch version, update, delete, rename, set as default, and re-initialize. :::info -Under the hood, the Desktop Application will call a `devsy provider add PROVIDER` +The Desktop Application calls `devsy provider add PROVIDER` under the hood. ::: ### Adding a custom provider -After you click the `Add` button in the `Providers` section, you can click the -big `+` button to add a custom provider, then fill the `Source` section with either +In the Select step, type one of the following into the **Provider Source** field below the preset grid: - A GitHub link to the provider's project -- An URL to a `provider.yaml` -- A File Path to a `provider.yaml` +- A URL to a `provider.yaml` +- A file path to a `provider.yaml` ## Via Devsy CLI -The providers in this list can easily be installed like: +Install any provider from the list with: ```sh devsy provider add docker diff --git a/sites/docs-devsy-sh/pages/managing-providers/set-source.mdx b/sites/docs-devsy-sh/pages/managing-providers/set-source.mdx index e4c08a228..af88b598e 100644 --- a/sites/docs-devsy-sh/pages/managing-providers/set-source.mdx +++ b/sites/docs-devsy-sh/pages/managing-providers/set-source.mdx @@ -1,50 +1,52 @@ --- -title: Set a provider's source -sidebar_label: Set a provider's source +title: Update or pin a provider version +sidebar_label: Update a provider --- +## List available versions -To update a provider to its latest version, you can use: +```sh +devsy provider versions +``` + +The table shows the published tag, date, and whether it's the currently-installed version. Pass `--prerelease` to include pre-releases and `--no-cache` to bypass the version cache. + +## Re-fetch the current source ```sh devsy provider set-source ``` -To update to a specific version, pass `--version `: +Re-resolves the provider's existing source. If the source is a registry entry or a GitHub repo without a pinned tag, this pulls the latest release. If the source is already pinned (e.g. `github.com/org/repo@v0.1.0`), it re-fetches that same version — use `--version` to move to a different one. + +## Pin to a specific version ```sh devsy provider set-source --version v0.2.0 ``` -To list the available versions for an installed provider, use: +Equivalent inline form (works for GitHub-hosted providers): ```sh -devsy provider versions +devsy provider set-source github.com/my-org/my-repo@v0.2.0 ``` -## From GitHub +## Point at a different source -Similar to adding a provider, you can update via: -```sh -devsy provider set-source my-org/my-repo -``` +The `set-source` command also replaces the provider's source entirely — registry name, GitHub repo, URL, or local path: -If you want to update (or downgrade) a specific version, you can do: ```sh -devsy provider set-source github.com/my-org/my-repo@v0.2.0 +devsy provider set-source my-org/my-repo +devsy provider set-source https://path/to/provider.yaml +devsy provider set-source ../path-to/provider.yaml ``` -## From URL +## Desktop -You can also specify the URL to the `provider.yaml` file, for example: +Open the Providers sidebar, select a provider, and use the ProviderSheet: -```sh -devsy provider set-source http://path/to/my/provider.yaml -``` +- **Select version** — pick a tag from the versions dropdown to switch versions. +- **Update** — jump to the latest release. The button surfaces an "Update available" banner when one is detected. +- **Initialize** — re-run provider init (handy after upgrades). -### From File - -Run the following command to update provider `provider-name`: -```sh -devsy provider set-source ../path-to-updated/provider.yaml -``` +Existing workspaces continue to use the version they were created with. Rebuild a workspace (`devsy workspace up --recreate`) to pick up the new provider. diff --git a/sites/docs-devsy-sh/pages/troubleshooting/ide-troubleshooting.mdx b/sites/docs-devsy-sh/pages/troubleshooting/ide-troubleshooting.mdx deleted file mode 100644 index 1f013aab5..000000000 --- a/sites/docs-devsy-sh/pages/troubleshooting/ide-troubleshooting.mdx +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: IDE Troubleshooting -sidebar_label: IDE Troubleshooting ---- - -This purpose of this page is to outline any known issues with using devsy on unsupported IDEs using the SSH provider - -### NeoVim - -Some issues such as setting $TERM have been noticed on NeoVim, a solution has been documented [here](https://github.com/devsy-org/devsy/issues/1187) diff --git a/sites/docs-devsy-sh/pages/troubleshooting/troubleshooting.mdx b/sites/docs-devsy-sh/pages/troubleshooting/troubleshooting.mdx index 4050d423f..ac890701e 100644 --- a/sites/docs-devsy-sh/pages/troubleshooting/troubleshooting.mdx +++ b/sites/docs-devsy-sh/pages/troubleshooting/troubleshooting.mdx @@ -50,6 +50,18 @@ Common error codes you may see: Re-run with `--debug` to see the original error chain, and pass `--result-format json` (or `plain` to force human-readable output) to control rendering — the default `auto` chooses JSON when stdout is not a TTY. +### Windows: `line 2: $'\r': command not found` + +Windows line endings break shell scripts inside the container. Add the following to `.gitattributes`: + +``` +*.sh eol=lf +``` + +### NeoVim: `$TERM` issues over SSH + +NeoVim can misbehave when `$TERM` isn't set correctly over the SSH provider. A workaround is documented in [issue #1187](https://github.com/devsy-org/devsy/issues/1187). + ### VS Code Browser workspace fails to open on first create -Earlier versions of Devsy could race when bootstrapping the workspace metadata file used by the VS Code Browser tunnel, causing the first browser session to fail immediately after `devsy workspace up --ide openvscode`. This has been fixed — if you previously hit this, simply re-run `devsy workspace up` on the affected workspace. When Devsy exits because the workspace could not be located, it returns exit code `75`, which parent processes (including Devsy Desktop) treat as a transient signal and retry automatically. +Earlier versions of Devsy could race when bootstrapping the workspace metadata file used by the VS Code Browser tunnel, causing the first browser session to fail right after `devsy workspace up --ide openvscode`. This is fixed — if you previously hit this, re-run `devsy workspace up` on the affected workspace. When Devsy exits because the workspace could not be located, it returns exit code `75`, which parent processes (including Devsy Desktop) treat as a transient signal and retry. diff --git a/sites/docs-devsy-sh/pages/troubleshooting/windows-troubleshooting.mdx b/sites/docs-devsy-sh/pages/troubleshooting/windows-troubleshooting.mdx deleted file mode 100644 index 3efef5016..000000000 --- a/sites/docs-devsy-sh/pages/troubleshooting/windows-troubleshooting.mdx +++ /dev/null @@ -1,14 +0,0 @@ ---- -title: Windows Troubleshooting -sidebar_label: Windows Troubleshooting ---- - -This purpose of this page is to outline any known issues with using devsy on Windows and provide known workarounds / fixes. - -### line 2: $'\r': command not found - -Errors like this are caused from windows line endings, to fix add the following to `.gitattributes` - -``` -*.sh eol=lf -``` diff --git a/sites/docs-devsy-sh/sidebars.js b/sites/docs-devsy-sh/sidebars.js index e12c1910b..d16bcba17 100644 --- a/sites/docs-devsy-sh/sidebars.js +++ b/sites/docs-devsy-sh/sidebars.js @@ -103,6 +103,10 @@ module.exports = { type: "doc", id: "developing-in-workspaces/delete-a-workspace", }, + { + type: "doc", + id: "developing-in-workspaces/mcp-server", + }, ], }, { @@ -231,14 +235,6 @@ module.exports = { type: "doc", id: "troubleshooting/linux-troubleshooting", }, - { - type: "doc", - id: "troubleshooting/windows-troubleshooting", - }, - { - type: "doc", - id: "troubleshooting/ide-troubleshooting", - }, ], }, {