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

# Deployment-managed context files

> Control where a self-hosted nao container loads its context from with NAO_CONTEXT_SOURCE

A self-hosted nao container needs to know where its [context](/nao-agent/context-builder/overview) lives. The `NAO_CONTEXT_SOURCE` environment variable picks one of three sources. When the deployment owns the context, the in-app **Settings -> Git** page turns into a read-only summary instead of a connection wizard, so no one can accidentally repoint a managed deployment from the UI.

## Context sources

| `NAO_CONTEXT_SOURCE` | Where context comes from                                                                                                             | Default when                      |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------- |
| `local`              | A directory mounted into the container at `NAO_DEFAULT_PROJECT_PATH` (default `/app/context`), containing a valid `nao_config.yaml`. | Self-hosted / single-project mode |
| `git`                | A Git repository the container clones on startup from `NAO_CONTEXT_GIT_URL`.                                                         | You set it explicitly             |
| `api`                | Projects deployed dynamically with the [`nao deploy`](/nao-agent/cloud/deploy) CLI command.                                          | `NAO_MODE=cloud`                  |

If `NAO_CONTEXT_SOURCE` is unset, nao defaults to `api` in cloud mode and `local` otherwise. An unknown value stops the container at startup.

## Git-managed context

Set `NAO_CONTEXT_SOURCE=git` to have the container clone your context repository when it boots. `NAO_CONTEXT_GIT_URL` is required; the rest scope and authenticate the clone:

```bash theme={null}
NAO_CONTEXT_SOURCE=git
NAO_CONTEXT_GIT_URL=git@github.com:your-org/your-nao-context.git
NAO_CONTEXT_GIT_BRANCH=production        # optional, defaults to main
NAO_CONTEXT_GIT_SUBPATH=tools/nao        # optional, sparse-checkout a subdirectory
NAO_CONTEXT_GIT_PLATFORM=gitlab          # optional, for self-hosted hosts nao can't identify
NAO_CONTEXT_GIT_SSH_KEY={{ secret_ssh_key }}   # SSH URLs
# NAO_CONTEXT_GIT_TOKEN={{ secret_pat }}       # HTTPS URLs (optional)
```

The container picks the auth scheme from the URL: `git@…` / `ssh://…` needs `NAO_CONTEXT_GIT_SSH_KEY`, and `https://…` accepts an optional `NAO_CONTEXT_GIT_TOKEN`. GitHub and Bitbucket host keys are pre-pinned, so SSH connects without a known-hosts prompt. See [Deployment guide](/nao-agent/self-hosting/deployment-guide) for the full clone and secrets walkthrough, and [Multiple projects](/nao-agent/self-hosting/multiple-projects) for running several context repositories from one deployment.

`NAO_CONTEXT_GIT_PLATFORM` (`github`, `gitlab`, or `bitbucket`) only matters when the host name doesn't give the platform away - a self-hosted GitLab at `git.example.com`, for instance. nao uses it to know how to open a review request.

## Editing a deployment-managed repository

The context repository stays editable from the browser even though the deployment owns it. Admins can change context files in the [File Explorer](/nao-agent/chat/admin/file-explorer), commit, and open a pull or merge request - **with no OAuth app and no per-user Git authorization**. nao pushes using the credential the deployment already has (`NAO_CONTEXT_GIT_TOKEN` or `NAO_CONTEXT_GIT_SSH_KEY`), while still authoring each commit as the nao user who made the change, with nao as co-author.

This works against GitHub, GitLab, and Bitbucket, including self-hosted instances.

## The read-only Git summary

When `NAO_CONTEXT_SOURCE=git`, the deployment is the owner of the context *setup*. **Settings -> Git** then shows a read-only summary of the deployment-managed repository instead of the [repository connection wizard](/nao-agent/chat/admin/git): admins can see which repository, branch, and subpath the container was configured with, but the connect and disconnect flow is disabled because the source is controlled by the deployment's environment, not the UI.

To let admins connect the context repository from the browser instead, leave `NAO_CONTEXT_SOURCE` on `local` (or `api`) and set the repository up in-app under [Settings -> Git](/nao-agent/chat/admin/git).

<Note>
  Changing `NAO_CONTEXT_SOURCE` takes effect on container restart, since the context is resolved at startup. Update the environment variable on your platform (Cloud Run, ECS, Kubernetes, …) and redeploy.
</Note>