This guide covers setup, builds, tests, and pull requests.
Sign the Contributor License Agreement before your first contribution can merge. A bot checks your signing status when you open a pull request. If you have not signed, the bot comments with instructions. Sign by posting the exact text the bot gives as a comment on the pull request.
CLI development:
Desktop application development:
- Node.js 24+ (with npm)
- Go 1.26+
- Python 3 (node-gyp uses it to build the
node-ptynative module; CI uses 3.14)
-
Clone the repository:
git clone https://github.com/devsy-org/devsy.git cd devsy -
To change the agent code:
- Replace the URL in DefaultAgentDownloadURL with a public repository release that you control
- Build Devsy:
mise run cli:build:dev - Upload
dist/devsy-dev_linux_amd64_v1/devsy-linux-amd64and the ARM64 variant to the release assets
Using mise (recommended):
# Build CLI for development
mise run cli:build:dev
# Build CLI for production
mise run cli:build
# Build with Pro features
mise run cli:build:dev:proUsing Go directly:
CGO_ENABLED=0 go build -ldflags "-s -w" -o devsyThe build writes the devsy binary to the current directory.
Using mise (recommended):
# Setup Electron environment (first time only)
mise run desktop:setup
# Run in development mode
mise run desktop:dev
# Build the application
mise run desktop:buildManual build:
cd desktop
npm ci
npm run buildThe packaged application is in desktop/release/.
# Tidy dependencies
mise run cli:tidy
# Run linters
mise run cli:lint
# Run unit tests
mise run cli:test
# Build for development
mise run cli:build:devIn renderer code, use $lib/... for renderer library modules and $shared/...
for shared modules. This covers type imports, re-exports, and dynamic imports. Use
./... for sibling files. Use relative paths for renderer entry points that have
no alias. Avoid ../... imports when an alias reaches the module.
Main-process, preload, and shared code use relative imports. Their bundlers do not
configure the renderer aliases. Keep the .js extension on TypeScript module
specifiers and the .svelte extension on component imports.
# Install dependencies
cd desktop
npm ci
# Check code quality (type check + svelte-check)
mise run desktop:check
# Run unit tests
mise run desktop:test
# Run e2e tests
mise run desktop:test:e2e# Build for e2e tests
mise run cli:test:e2e:build
# Run all e2e tests
mise run cli:test:e2e
# Run specific test suite
mise run cli:test:e2e:suite "suite-name"
# Run focused tests
mise run cli:test:e2e:focus "test-pattern"
# Setup kind cluster for testing
mise run cli:test:e2e:kind:setup
# Teardown kind cluster
mise run cli:test:e2e:kind:teardownTo change the gRPC tunnel code, run:
mise run cli:build:grpcmise installs the pinned protoc. The task installs the Go protobuf plugins.
Run affected packages with go test -race -short -count=1, then run
mise run cli:lint:ci. Resource cleanup changes need coverage of failure paths
as well as successful calls.
The browser tunnel regression in pkg/ide/opener injects a failing /dev/null
open on Linux and macOS. It checks that a failed helper launch releases its
reserved port. Platform reachability tests in cmd/platform use local HTTP servers
to check connection cleanup between probes.
Cross-compilation checks platform buildability, not runtime behavior. Windows
PTY tests run through the windows-pty step in hack/ci/suites.yaml.
-
Build Devsy:
mise run cli:build:dev
-
Add a provider:
./dist/devsy-dev_linux_amd64_v1/devsy-linux-amd64 provider add docker
-
Configure the provider:
./dist/devsy-dev_linux_amd64_v1/devsy-linux-amd64 provider use docker
-
Start a workspace:
./dist/devsy-dev_linux_amd64_v1/devsy-linux-amd64 workspace up github.com/microsoft/vscode-remote-try-node
# Build UI using act
mise run desktop:act:build:ui
# Build desktop app using act
mise run desktop:act:build:app
# Build flatpak using act
mise run desktop:act:build:flatpak
# Run e2e tests with focus
mise run cli:test:e2e:act:focus "test-pattern"See the docs to learn how to build a provider.
When your provider is ready:
- Add your provider to
community.yaml. - Document it in
sites/docs-devsy-sh/content/docs/managing-providers/manage-providers.mdx.
The Desktop provider wizard does not read community.yaml. Its additional provider list comes from devsy-org repositories whose names start with devsy-provider-.
Devsy Desktop handles deep links that run actions.
URL scheme:
devsy://command?param1=value1¶m2=value2
Opens a workspace from a source, like devsy workspace up with a link:
devsy://open?source=<url-encoded-source>&workspace=<name>&provider=<provider>&ide=<ide>
Parameters:
source(required): URL-encoded workspace sourceworkspace(optional): Workspace nameprovider(optional): Provider to useide(optional): IDE to open
Example:
devsy://open?source=https%3A%2F%2Fgithub.com%2Fuser%2Frepo&workspace=my-workspace&provider=docker&ide=vscode
Imports a Devsy Pro workspace into the local client:
devsy://import?workspace_id=<id>&workspace_uid=<uid>&devsy_pro_host=<host>&options=<options>
Parameters:
workspace_id(required): Workspace IDworkspace_uid(required): Workspace UIDdevsy_pro_host(required): Devsy Pro host URLoptions(optional): Additional options
/cmd: CLI command implementations/pkg: Core packages and libraries/desktop: Desktop application (Electron and Svelte)/e2e: End-to-end tests/providers: Built-in provider definitions/sites: Documentation and download websites/hack: Build and development scripts
The pull request template asks for three things:
- AI disclosure: AI-assisted code is welcome. Name the tool, the model, and what it did. You must understand every line you submit.
- Integration tests: CLI changes need Ginkgo e2e tests in
e2e/tests/. Desktop changes need Playwright e2e tests indesktop/e2e/. Unit tests alone do not cover them. If no integration test applies, say why in the PR. - Conventional Commits title: the title becomes the squash commit subject.
Be respectful and constructive with the community.