Everyone is welcome to contribute. The most important rule is simple:
Everything starts with an issue. No issue, no pull request.
Every bug fix, feature, refactor, documentation change, and other improvement must be connected to an open issue before work begins. The issue is where we agree on the problem, keep decisions visible, and prevent duplicated work.
First, search the open issues to see whether the problem has already been reported.
- If an issue already exists, add any useful context there instead of opening a duplicate.
- If no issue exists, open a new issue and choose the template that best matches the problem.
- Do not publish security vulnerabilities in a public issue. Follow the private reporting instructions in SECURITY.md.
This rule also applies to every new feature and feature request. Before starting a new feature, open a Feature request issue—even when the change seems small. Explain the user problem, the result you want, and how you will know the feature is complete. A pull request must not be the first place a new feature is proposed.
Write the issue so that someone unfamiliar with the problem can understand it. Include:
- A clear title describing one problem.
- What you were trying to do and why it matters.
- What happened and what you expected instead.
- Steps to reproduce the problem, if it is a bug.
- What a successful result should look like.
- Relevant screenshots, logs, versions, or links. Remove secrets and personal information first.
Keep one issue focused on one problem. If the work contains separate problems, open separate issues so each can be discussed, assigned, and completed on its own.
Anybody can claim an open issue, including first-time contributors. You do not need repository access and you do not need to wait for a maintainer.
-
Open the issue you want to work on and check its current assignees.
-
Add a new comment containing exactly:
/assign -
The bot will add you as an assignee and react to your comment with a thumbs-up.
You may self-assign any open issue. If somebody is already working on it, coordinate with them in the issue before starting so effort is not duplicated.
A pull request is the implementation of an issue, not the beginning of a new
discussion. Open and assign the issue first, then create your branch from
qa and make the change.
Every pull request must:
- target the
qabranch; - stay within the scope agreed in its issue; and
- include
Fixes #123orCloses #123in the pull request description, replacing123with the real issue number.
This link is mandatory, including for small changes and draft pull requests. A pull request that is not connected to an issue will be rejected and closed without review.
remote.futrx has a Preact/Vite frontend, a Go backend, a catalog of installable applications, and infrastructure scripts for installation and updates. Keep changes inside the existing boundaries and follow the patterns in the code around them. For deeper implementation details, read the development documentation.
Use the commands below to build, test, and run the project locally. Before you start, also read AGENTS.md for the repository-specific development and QA workflow, including how to deploy and verify frontend, backend, installation, and update changes.
- Go 1.25+
- Node.js 22.14+
- Linux with LXD only when running the complete application; builds and most tests also work without LXD
Build and test the backend:
cd backend
go build ./...
go test ./...
go run ./cmd/remoteThe backend listens on port 7682 by default. From the repository root, also
build and test the separate application-catalog module:
go build ./...
go test ./...cd frontend
npm install
npm test
npm run devThe frontend runs on port 5174 and proxies API and WebSocket requests to the
backend on port 7682. Run npm run build before submitting frontend changes.