Availability
Cloud projects and local projects
The sidebar has two sections, Cloud projects and Local projects. A project’s section depends only on its source and does not change later.- The + on the right of the section titles is New cloud project and New local project respectively. Empty sections show Import from GitHub and Add a local folder.
- The web app shows the Local projects section only when you have local projects, and it has no +.
- For sidebar sorting, dragging, and pinning, see Sidebar.
Entry points
- The + on a sidebar section title, or Import from GitHub / Add a local folder in an empty section.
- New project on the Projects page.
- The project picker above the input box on the new session page › New project.
- Settings › Workspace › Projects: view all projects and open a project or its settings.
Create a project
There are two creation windows: New local project (links a folder on your computer, desktop app only) and New cloud project (three tabs: New, Import from GitHub, Upload local project). Creating a cloud project requires Plus (cloud server). Without it, the Plus subscription window opens first. After you subscribe, click Continue creating your project or Continue your import to return to the creation window with your selected repositories kept. See What you can do without Plus.New local project (link a folder on this computer)
Use this to work directly with code already on this computer. Files are not uploaded, no cloud server is needed, and no environment setup is required. Available in the desktop app only.- Under Source folders, click Add and choose a folder. Project name is filled with the folder name. You can change it, up to 64 characters.
- Click Create project.
- A local project links one source folder. After creation, you can attach other folders on the same computer in project settings.
- Overly broad folders such as your home folder, and folders you have no read permission for, cannot be chosen; the reason is shown.
- On success, the new session page opens with this project selected and this computer as the default run environment.
New cloud project
New
- Enter a Project name, up to 64 characters. If left empty,
my-appis used. - Under Start from, choose a starter template. The list follows what the interface shows and currently includes Blank, Node · TypeScript, Next.js, and Python.
- If needed, check Create a private GitHub repository (checked by default when GitHub is connected). The repository is created under your personal GitHub account and is private. When GitHub is not connected, this option is unavailable.
- Click Create project. After creation, the new session page opens with this project selected.
Import from GitHub
- Under Select repositories, check one or more repositories. You can filter by account / organization or search.
- Click Get started. After creation, the new session page opens with this project selected.
- When you select multiple repositories, the first is the main repository and the rest are cloned into the project with it (for example, a shared component library). The project name is taken from the main repository and can be changed later.
- If a repository is missing from the list: click Configure access to adjust the authorized scope on GitHub, then come back and click Refresh.
- When GitHub is not connected, click Connect GitHub; after connecting, you return here. See Connectors. Without GitHub, you can click No GitHub? Use a local project.
Upload local project
Uploads a folder from your computer to the cloud server and creates a cloud project.- Drag the project folder into the window, or click Choose folder….
- The window shows the number and size of the files to upload, and the common config files it detected (such as
package.jsonandpyproject.toml). - Click Get started and wait for the upload and import to finish. When done, you see my-app uploaded to the cloud, and the new session page opens.
- If a limit is exceeded, the upload cannot start. Remove large folders and choose again.
- You can click Cancel upload during the upload. After an upload fails or is canceled, uploaded data is not kept, and Retry starts over.
- If the import takes a while, you can close the window and check the Projects page later.
- An uploaded project has no linked remote repository, and changes are delivered as patches. You can later add GitHub repositories to clone with it in project settings.
After creation: set up the environment
You can start sessions as soon as a cloud project is created. If you want AI to install dependencies and fill in secrets and environment variables, go to Project settings › Environment and click the edit button; see Project environment. Local projects use the computer’s own environment and do not need this step.The Projects page
The Projects page lists all projects, most recently updated first. Each row shows the name, the source (GitHub repository or folder name), the update time, the number of sessions in progress, and recent activity. Projects whose source setup failed are marked Source setup failed.- The page header has Search projects (by name and source) and New project.
- Click a row to open the project page; click … at the end of a row to open the project menu.
Project menu
In the … on a sidebar project row or at the end of a row on the Projects page:Project page
The top right of the project page has Open on GitHub or Reveal in Finder, Project settings, and New task in this project. While the project source is still being prepared, or if preparation failed, a notice appears below the title, for example “Source setup failed: Check repository access, then relink it in Settings”.Recent tasks
Lists recent sessions in this project. Sessions in progress are marked In progress; sessions awaiting your approval are marked Needs approval. Click View all to open the activity log filtered to this project.Commits
Lists recent commits on the current branch. Click View all to open the commits page, where you can click a commit to expand the changed files and the lines added and removed.Files
- Lists files and directories, with the latest commit that changed each. If a directory contains a README, it is displayed directly.
- Click a file to open the file view: previewable files (such as Markdown) can switch between Preview / Source, and you can Copy contents or Share file. Large files show only the beginning; binary files cannot be previewed.
- Sensitive files such as
.envand private keys are not displayed on the web.
Website preview
The Website preview area lists the services this project is listening on the cloud server (such aslocalhost:3000).
- Open: opens in the in-app preview window.
- Share: creates a share link for this service; see Share.
- Refresh reads them again; My shares shows all shares for this project.
- When there are no services, ask the agent to start a dev server in the project, and an entry appears here.
- Previews are unavailable while the cloud server is not running. If it stopped when Plus ended, it restarts once you subscribe again.
Share
Create a share
Open the Share window from Share in the website preview or Share file in the file view:
Click Create link, then Copy link. The link is shown only this once and cannot be viewed again after you close the window, so copy it right away. Before choosing Public, make sure the content can be made public.
My shares
My shares lists this project’s shares and their status: active shares can be revoked with Revoke (the existing link stops working immediately); shares that exceed the daily traffic limit are paused and resume the next day; expired shares can be shared again with Share again.Local projects on other computers
A local project’s code exists only on the computer it is linked to. When you view it in the web app or on another computer:- The project page does not show files or commits (Only on your computer).
- You can create sessions in this project, and they run on the computer where the project lives. If that computer is offline, it is marked Device offline. Existing sessions can be viewed, continued, and approved; see Run environment.
- You cannot move sessions into or out of this project, and there is no Reveal in Finder or Add folder.
Project settings
Open from Project settings at the top right of the project page, Edit in the project menu, or Settings › Workspace › Projects.Project info
Changes take effect only after you click Save; click Discard to revert.- Repositories: the main repository has Pull latest from GitHub. If the cloud server has uncommitted changes or has diverged from the remote, the reason is explained and nothing is merged automatically. Click Add repository and enter
owner/nameor paste a GitHub URL. - Source folders: in the desktop app, for a local project on this computer, you can click Add folder to attach other folders on the same computer, which the agent can also read and write. Your home folder, sensitive locations, and locations that overlap with existing folders cannot be added.
Environment
Shows the current Setup script and Start command. Click the edit button to open the environment setup page; see Project environment.Secrets and environment variables
Lists project-level secrets and variables, plus the items Inherited from workspace; when names match, the project-level item wins. Add and edit them in Settings › Workspace › Secrets & variables; see Workspace settings. After deletion, running environments pick up the change after a restart.Export project
Click Export… to open the Export project window, click Export, and when packing is done, click Download archive. The archive includes project files and excludes.env, secrets, dependencies, and caches.
- When the download link expires, you can click Get new link; if packing fails, click Retry archive.
- The cloud server must be running; only the project owner can export.
Delete a project
Open the confirmation window from Delete project… in the project menu or in project settings:- It deletes this project’s cloud environment, files, and dependency cache, and cannot be undone. For a local project, the folder on your computer is not affected.
- Sessions in the project are archived and can be found in Settings › Workspace › Archived chats.
- The window first checks for unpushed changes. If there are uncommitted files or unpushed commits (or the check is not possible right now), a notice lists them, and you must type the project name to delete.