Skip to content

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.

  • 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 HOST and PORT environment variables CloudLink provides.
  • The app becomes ready with a 2xx response on the configured route.
  • A public HTTPS port is available: 8443, 2053, 2083, 2087, or 2096. A route with a path can share a port with other path routes.
  1. Open Settings → Projects.

  2. Choose New project.

  3. Select the repository folder.

  4. Enter the start script. For a Vite app on macOS or Linux:

    Terminal window
    npm ci
    exec npm run dev -- --host "$HOST" --port "$PORT" --strictPort
  5. Choose the project name, URL ID, tunnel port, and optional path.

  6. Review the route preview and access policy.

  7. Choose Save project. The route starts disabled and private.

  8. 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.

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 & 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.

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.

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

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.