> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aihubmix.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Projects: create, import, view, configure, and delete

> The difference between cloud projects and local projects; create one from scratch, import from GitHub, upload a local project, or link a folder on your computer; the project page, project settings, website previews and sharing, export, and deletion.

A **project** is a set of code sources plus its environment settings. The source can be a GitHub repository, a folder uploaded to your cloud server, or a folder on one of your computers. A session can run inside a project or with **No project** (the default on the new session page).

Projects fall into two groups by source: a **cloud project** keeps its code on your cloud server; a **local project** keeps its code on one of your computers, and its sessions run [on your device](https://docs.aihubmix.com/en/cloud/projects/run-environment.md) on that computer.

## Availability

| Platform | Support | Notes |
| - | - | - |
| Desktop app | Supported | Create cloud projects and local projects; view, configure, and delete all projects |
| Web app | Partial | Create cloud projects; you cannot create local projects; you can see the local projects on each computer, but not their files and commits that are not yet in the cloud |
| Mobile web | Partial | Same as the web app; mobile browsers cannot choose folders, so **Upload local project** is unavailable |

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

| Section | Projects it contains |
| - | - |
| **Cloud projects** | Projects created from scratch, imported from GitHub, or uploaded to the cloud server through **Upload local project** |
| **Local projects** | Projects linked to a folder on one of your computers |

* 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](https://docs.aihubmix.com/en/cloud/interface/sidebar.md).

## 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](https://docs.aihubmix.com/en/cloud/plus/without-plus.md).

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

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

1. Enter a **Project name**, up to 64 characters. If left empty, `my-app` is used.
2. Under **Start from**, choose a starter template. The list follows what the interface shows and currently includes Blank, Node · TypeScript, Next.js, and Python.
3. 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.
4. Click **Create project**. After creation, the new session page opens with this project selected.

#### Import from GitHub

1. Under **Select repositories**, check one or more repositories. You can filter by account / organization or search.
2. 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](https://docs.aihubmix.com/en/cloud/integrations/connectors.md). 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.

1. Drag the project folder into the window, or click **Choose folder…**.
2. The window shows the number and size of the files to upload, and the common config files it detected (such as `package.json` and `pyproject.toml`).
3. 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.

| Limit | Details |
| - | - |
| Automatically excluded | Contents of `.gitignore`, `node_modules`, `.git`, `.env` files, and sensitive files such as credentials, private keys, and certificates |
| Total size | 2 GiB |
| File count | 50,000 |
| Single file | 100 MiB |

* 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](https://docs.aihubmix.com/en/cloud/projects/environment-setup.md). 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:

| Menu item | What it does |
| - | - |
| **Pin** / **Unpin** | Pinned projects appear first in their section |
| **Edit** | Opens project settings |
| **Open on GitHub** | With a GitHub repository, opens the main repository page |
| **Reveal in Finder** (on Windows, **Reveal in File Explorer**) | In the desktop app, for local projects on this computer, opens the project folder |
| **Archive chats** | Archives the sessions in this project |
| **Delete project…** | See "Delete a project" below |

## 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 `.env` and 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 as `localhost:3000`).

* **Open**: opens in the in-app preview window.
* **Share**: creates a share link for this service; see [Share](#sharing).
* **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:

| Option | Values | Default |
| - | - | - |
| Who can access | **Only me**, **Anyone with the link**, **Public** | **Anyone with the link** |
| Expiry | 1 to 30 days | 7 days |

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](https://docs.aihubmix.com/en/cloud/projects/run-environment.md).
* 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.

| Setting | Applies to | Details |
| - | - | - |
| Name | All | 1 to 64 characters; names can repeat within a workspace |
| Description | All | Shown below the title on the project page |
| Repositories | Cloud projects (New, Import from GitHub) | The first is the main repository and cannot be removed; the rest are cloned alongside |
| Source folders | Uploaded projects, local projects | No linked remote repository; changes are delivered as patches |
| Base branch | Projects with a GitHub repository | Sessions create working branches from this branch, and pushes and PRs target it; leave empty to use the default branch |
| Ship behavior | Projects with a GitHub repository | **Open a PR** (default), **Push branch**, or **Custom** (commits according to the prompt you write) |
| Commit author | All | **AIHubMix Agent** (default) or **My GitHub account** (requires a connected GitHub account) |
| Additional cloned repositories | Uploaded projects, local projects | Repositories cloned into the project |

* **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/name` or 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](https://docs.aihubmix.com/en/cloud/projects/environment-setup.md).

### 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](https://docs.aihubmix.com/en/cloud/settings/workspace.md). 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.

## Commits and PRs

When the changes are done, ask the agent in the session to commit, push, or open a PR; the default approach is set by **Ship behavior** in project settings. The session's **Changes** shows the branch status and a **PR #N** link. Uploaded projects have no remote repository, so changes are delivered as patches. See [Agent output](https://docs.aihubmix.com/en/cloud/sessions/agent-output.md).

## FAQ

### What is the difference between **Upload local project** and **Add a local folder**?

**Upload local project** uploads a folder to the cloud server and creates a cloud project; it requires Plus. **Add a local folder** only links a folder on this computer: nothing is uploaded, no cloud server is needed, and sessions run on this computer. It is available in the desktop app only.

### Does deleting a project delete files on my computer?

No. A local project's folder is not affected.

### Can the web app see local projects on my computer?

You can see the project and its session history, and you can start new sessions (they run on that computer), but you cannot see files and commits that are not yet in the cloud.

### After a failed upload, is the uploaded part kept?

No. Clicking **Retry** starts over.

### Do I have to set up the environment after creating a cloud project?

No. You can start sessions as soon as the project is created. Environment setup lets AI install dependencies and fill in secrets in advance.

## Related

* [Project environment](https://docs.aihubmix.com/en/cloud/projects/environment-setup.md)
* [Run environment: on your device and cloud server](https://docs.aihubmix.com/en/cloud/projects/run-environment.md)
* [Workspace settings](https://docs.aihubmix.com/en/cloud/settings/workspace.md)
* [Sidebar](https://docs.aihubmix.com/en/cloud/interface/sidebar.md)
* [New session](https://docs.aihubmix.com/en/cloud/sessions/new-session.md)
* [Connectors](https://docs.aihubmix.com/en/cloud/integrations/connectors.md)
* [What you can do without Plus](https://docs.aihubmix.com/en/cloud/plus/without-plus.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.