Projects
Projects are the desktop workflow for apps that CloudLink should start for you. A Service forwards an app you already run. A Project saves a local Git folder and a foreground start command, then starts and exposes the app when you choose.
Projects are available in the desktop app. The macOS and Windows downloads include the tray UI; the Linux download on this site is headless.
Before you create a project
Section titled “Before you create a project”- The desktop app is installed and the machine is paired.
- The project is a local Git repository. A Git remote and an OpenCode project registration are optional.
- The start command keeps the app in the foreground and respects the
HOSTandPORTenvironment variables CloudLink provides. - The app becomes ready with a
2xxresponse on the configured route. - A public HTTPS port is available:
8443,2053,2083,2087, or2096. A route with a path can share a port with other path routes.
Create a project
Section titled “Create a project”-
Open Settings → Projects.
-
Choose New project.
-
Select the repository folder.
-
Enter the start script. For a Vite app on macOS or Linux:
Terminal window npm ciexec npm run dev -- --host "$HOST" --port "$PORT" --strictPort -
Choose the project name, URL ID, tunnel port, and optional path.
-
Review the route preview and access policy.
-
Choose Save project. The route starts disabled and private.
-
Choose Start & expose. The app starts from the repository folder.
Saving does not start or expose the app. Only Start & expose enables the route, and the share URL remains unavailable until the app passes its readiness check.
Access and sharing
Section titled “Access and sharing”A project route uses the same access policy as a service:
- Private — paired devices and the browser credential.
- Public link — anyone with the managed share link.
- Password protected — the share link plus a visitor password.
Set an optional expiration and apply the access settings to create the share link. Revoking sharing, changing the password, changing the route, or stopping the project closes active reviewer and visitor sessions for that route.
See Share a local app with clients for the access workflow and Exposed services for the route rules.
Start, stop, and update
Section titled “Start, stop, and update”- Start & expose starts the project’s script and enables its route.
- Stop app stops the process and closes active connections.
- Disable route keeps the project saved but stops forwarding traffic.
- Changes to the folder, script, or route require an explicit restart before they take effect. Access policy changes apply through the access controls and can end active reviews.
- The project status reports starting, running, stopped, and failures.
Remote service APIs can list managed routes and their URLs. They cannot turn a project into a port forward, start its script, or change its lifecycle.
Live Feedback
Section titled “Live Feedback”After the first successful start, the desktop app can offer Live Feedback. It reuses the project’s folder, script, route, and access policy, then lets you invite reviewers into isolated worktrees and let an OpenCode agent apply their changes.
Live Feedback requires the OpenCode integration and a password-protected project route. Starting and exposing the project itself does not require OpenCode. See Live Feedback.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Check |
|---|---|
| Start button is unavailable | Choose a free tunnel port and save the project first |
| App status stays stopped | The start command exited, or it does not keep the app in the foreground |
| Route enabled but URL unavailable | The app has not passed readiness |
| App ignores the assigned port | Read HOST and PORT from the environment in the start script |
| Port rejected | Use 8443, 2053, 2083, 2087, or 2096 |
| Changes do not apply | Stop the project, save the change, then start it again |
| Live Feedback is hidden | Start and expose the project first, and enable the OpenCode integration |
Related
Section titled “Related”CloudLink (OpenCode Cloud Link) is an independent product. It is not built by the OpenCode team, is not endorsed by them, and is not affiliated with them in any way. See thePrivacy Policy andTerms & Conditions.