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

# Host Multiple Projects

> Run several nao projects on a single deployment, under one domain, with a project switcher

A single self-hosted deployment can serve **one** project by default - the one you mount with `NAO_DEFAULT_PROJECT_PATH`. If you want to host **several projects on the same instance and domain** (for example one project per team, per warehouse, or per client) and let users switch between them, run the deployment in **multi-project mode**.

## How it works

nao organizes hosting as **organization -> projects -> members**:

* One instance owns one **organization**.
* The organization owns **any number of projects**. Each project is the unit that holds its own context folder, data connections, chats, members, and settings.
* Users switch between the projects they belong to from the **workspace switcher** in the sidebar. No separate URL or subdomain per project - everything lives under the same domain.

Each project's context is pushed to the instance with [`nao deploy`](/nao-agent/cloud/deploy). Projects are identified by `project_name` within the organization: deploying a new name **creates** a project, deploying an existing name **updates** it in place.

<Info>
  Multi-project hosting reuses the same organization and project model as [nao Cloud](/nao-agent/cloud/overview). Enabling it on your own infrastructure is a one-line switch, described below - it does not depend on nao's hosted service.
</Info>

## Single-project vs multi-project

|                       | Single-project (default)                                  | Multi-project                                |
| --------------------- | --------------------------------------------------------- | -------------------------------------------- |
| `NAO_MODE`            | `self-hosted`                                             | `cloud`                                      |
| Context source        | A mounted folder or git repo (`NAO_DEFAULT_PROJECT_PATH`) | Pushed with `nao deploy`                     |
| Projects per instance | One                                                       | Many                                         |
| Project switcher      | Not used - always serves the default project              | Users switch between projects they belong to |

<Warning>
  `NAO_DEFAULT_PROJECT_PATH` and `NAO_MODE=cloud` **cannot be set at the same time** - the container exits on startup if both are present. Multi-project mode replaces the single mounted folder with projects pushed via `nao deploy`, so remove any `NAO_DEFAULT_PROJECT_PATH` (and the project volume mount) when you switch.
</Warning>

## Step 1: Enable multi-project mode

Set a single environment variable on your deployment:

```bash theme={null}
NAO_MODE=cloud
```

When `NAO_MODE=cloud`, the container automatically:

* switches the context source to `api` (projects arrive over `nao deploy` instead of a mounted folder),
* unsets `NAO_DEFAULT_PROJECT_PATH`,
* creates a projects directory (`/app/projects` by default, configurable with `NAO_PROJECTS_DIR`) where each deployed project is stored in its own folder.

Everything else from the [Deployment Guide](/nao-agent/self-hosting/deployment-guide) stays the same - the PostgreSQL database, `BETTER_AUTH_SECRET`, LLM keys, and Cloud Run / container configuration are all shared across every project on the instance.

<Info>
  Because projects are pushed over the API rather than baked into the image, you don't need the `COPY` step or the `NAO_CONTEXT_GIT_URL` variables from the single-project guide. Use the stock `getnao/nao` image and deploy your projects afterward.
</Info>

## Step 2: Create an organization API key

`nao deploy` authenticates with an **organization-level** API key, which can write to every project in the organization.

1. Open the deployed chat UI and sign in as an admin.
2. Go to **Settings** -> **Organization** -> **API Keys**.
3. Click **Create key**, name it, and copy the value - it is shown only once.

See [Per-organization API keys](/nao-agent/cloud/overview#per-organization-api-keys) for details.

## Step 3: Deploy each project

From each project folder (the one containing `nao_config.yaml`), push it to the instance:

```bash theme={null}
nao deploy https://your-nao-domain.com --api-key nao_sk_...
```

The `project_name` in each project's `nao_config.yaml` determines its identity in the organization:

* A **new** `project_name` creates a new project on the instance.
* An **existing** `project_name` replaces that project's context folder in place (every deploy is a full replacement, not a merge).

Repeat for every project you want to host. For example, to host three projects on one domain:

```bash theme={null}
# from ~/projects/sales
nao deploy https://your-nao-domain.com --api-key nao_sk_...     # project_name: sales

# from ~/projects/finance
nao deploy https://your-nao-domain.com --api-key nao_sk_...     # project_name: finance

# from ~/projects/marketing
nao deploy https://your-nao-domain.com --api-key nao_sk_...     # project_name: marketing
```

<Card title="nao deploy reference" icon="upload" href="/nao-agent/cloud/deploy">
  Full command flags, exclusions, `.naoignore`, and create-vs-update behavior
</Card>

## Step 4: Switch between projects

Once more than one project exists, the **workspace switcher** appears in the sidebar. Users pick the active project there, and their chats, context, and data connections are scoped to that project. The selection is remembered per user.

Deploying a new project automatically adds every existing organization member to it. To scope who can see each project, manage members per project under **Settings** -> **Project** -> **Team**:

<Card title="Organizations and projects" icon="users" href="/nao-agent/cloud/overview#managing-team-members">
  Manage organization members, per-project teams, and roles
</Card>

## Keeping projects in sync

Each project is a normal nao context folder, so the usual workflow applies: edit context locally (or in git), run `nao sync`, then `nao deploy` to push. To automate this, run `nao deploy` from CI on each push to the branch that holds a project.

<Card title="Synchronization" icon="sync" href="/nao-agent/context-builder/synchronization">
  Automate context sync and deploys with GitHub Actions
</Card>

## Notes and limitations

* **One domain, no per-project URLs.** Projects are not exposed as subpaths or subdomains. Selection is per user through the switcher, not the URL.
* **Switching requires `NAO_MODE=cloud`.** In default `self-hosted` mode the server always serves the single default project, even if extra project rows exist - the switcher won't change what's served.
* **API keys are organization-scoped.** One key can create or overwrite any project in the organization. Treat it as a privileged secret and rotate it from the same **API Keys** page.