Skip to main content
A self-hosted nao container needs to know where its context lives. NAO_CONTEXT_SOURCE selects the source.

​
Context sources

  • local — Loads context from the directory mounted at NAO_DEFAULT_PROJECT_PATH (default /app/context). This is the default in self-hosted mode.
  • git — Clones context from the repository set in NAO_CONTEXT_GIT_URL. Set this explicitly on a self-hosted deployment.
  • api — Loads projects deployed with the nao deploy CLI. This is the default when 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.
NAO_CONTEXT_SOURCE is only configurable for self-hosted deployments. Cloud users must connect repositories in Settings → Git.

​
Git-managed context

Set NAO_CONTEXT_SOURCE=git to have a self-hosted container clone the context repository when it starts.
  • NAO_CONTEXT_SOURCE — Set to git to enable deployment-managed Git.
  • NAO_CONTEXT_GIT_URL — Repository clone URL. Required for Git-managed context.
  • NAO_CONTEXT_GIT_BRANCH — Branch used for the live context. Defaults to main.
  • NAO_CONTEXT_GIT_SUBPATH — Directory containing the nao project in a monorepo.
  • NAO_CONTEXT_GIT_TOKEN — Credential for private repositories cloned over HTTPS.
  • NAO_CONTEXT_GIT_SSH_KEY — Private key for repositories cloned over SSH.
  • NAO_CONTEXT_GIT_PLATFORM — Overrides platform detection with github, gitlab, or bitbucket.
For example:
Use NAO_CONTEXT_GIT_TOKEN instead of NAO_CONTEXT_GIT_SSH_KEY for HTTPS authentication. Private repository pulls reuse the configured token or SSH key. NAO_CONTEXT_GIT_PLATFORM is usually unnecessary; set it when nao cannot detect GitHub, GitLab, or Bitbucket from the URL, such as on a self-hosted Git server. NAO_CONTEXT_GIT_SUBPATH must point to an existing directory in the configured branch, and that directory must contain a tracked nao_config.yaml. Leave it unset when nao_config.yaml is at the repository root. See the Deployment guide for the clone and secret setup, and Multiple projects for running several context repositories.

​
Update the live context

Project admins can open Settings → Git and click Pull latest to fast-forward the live context from NAO_CONTEXT_GIT_BRANCH. The agent uses the new files after the pull completes. The live checkout’s origin must match NAO_CONTEXT_GIT_URL. nao refuses the pull if the origins differ, the branch has diverged, or local changes would be overwritten. Pull history in Settings → Git shows the result, commit, time, and changed files. See Git settings for the complete workflow.

​
Edit a deployment-managed repository

Admins can edit deployment-managed context files in File Explorer, commit, and open a pull or merge request without an OAuth app or per-user Git authorization. nao pushes with NAO_CONTEXT_GIT_TOKEN or NAO_CONTEXT_GIT_SSH_KEY, while authoring the commit as the nao user who made the change, with nao as co-author. Live context and File Explorer remain separate. Pulling the live context updates clean user worktrees automatically when safe, but never overwrites feature branches, commits, or uncommitted changes.

​
Git settings for a managed repository

Environment-based setup configures the repository directly. Settings → Git therefore shows a read-only summary of the deployment-managed repository rather than the repository connection wizard. Admins can review the configured repository, branch, and subpath, pull the latest live context, and inspect pull history, but the connect and disconnect flow is disabled because the source is controlled by the deployment’s environment, not the UI.
Changes to the context-source environment variables take effect after the container restarts. Update the variables on your deployment platform and redeploy.

​
Troubleshooting

​
Repository origin mismatch

Confirm that the live checkout’s origin and NAO_CONTEXT_GIT_URL identify the same repository. Correct the deployment configuration and redeploy before retrying Pull latest.

​
Context subfolder not found

Confirm that NAO_CONTEXT_GIT_SUBPATH exists in NAO_CONTEXT_GIT_BRANCH and contains a tracked nao_config.yaml. The value should be a repository-relative directory, not an absolute path or a path outside the repository.

​
Private repository credential rejected

For HTTPS, verify that NAO_CONTEXT_GIT_TOKEN is valid and can read the repository. For SSH, verify NAO_CONTEXT_GIT_SSH_KEY and the deploy key’s repository access. Then restart the deployment and retry.