---
title: "Projects"
description: "Save a local Git project, start its app with a foreground command, and expose the running result on a stable CloudLink HTTPS route."
canonical: "https://opencodecloud.link/docs/projects/"
lastUpdated: "2026-11-19"
---
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

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

## Create a project

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:

   ```sh
   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.

## 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](/docs/sharing-with-clients/) for the access
workflow and [Exposed services](/docs/exposed-services/) for the route rules.

## 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

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](/docs/live-feedback/).

## 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

- [Share a local app with clients](/docs/sharing-with-clients/)
- [Live Feedback](/docs/live-feedback/)
- [Exposed services](/docs/exposed-services/)
- [User manual](/docs/user-manual/)