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

# How Orchestra Local works

> Where your sessions, memories and issues live on your computer and in git, why Orchestra uses refs, how to look for yourself, and what teammates see and when

Orchestra Local runs on your computer. Nothing you capture goes to
Orchestra's servers: your sessions and memories are kept in a store on your
computer, and what you share with your team travels through git, with your
own git credentials. This page explains where everything is and how to check
it yourself. To set a team up, see [Working as a team on Local](https://docs.orchestrahq.ai/local-teams.md).

## On your computer

Everything Orchestra keeps is under `.orchestra` in your home folder (on
Windows, your user profile).

| Where | What it holds |
| - | - |
| `~/.orchestra/local/store` | Your store: every captured session, memory and issue, searchable by your agents. It never leaves this computer on its own. |
| `~/.orchestra/local/share/published-sessions.json` | Which sessions were published, where and when, and which were held back, with the reason. |
| `~/.orchestra/local/share/activity.jsonl` | The record of what sharing did, one line per event. Read it with `orchestra share log`. |
| `~/.orchestra/local/share/keys.json` | Your team's key, which seals issues. |
| `~/.orchestra/local/share/repos/` | Small git caches of what teammates shared: an index, and only the memories and sessions you opened. |
| `~/.orchestra/enabled-repositories.json` | The repositories you turned on with `orchestra enable`. |

The desktop app, the terminal client and your agents all read the same store,
through the Local daemon that runs in the background.

## In git

What you share goes to git, under `refs/orchestra/`, with one ref per person
for each kind of work:

| Ref | What it holds |
| - | - |
| `refs/orchestra/memory/<person>` | Your shared memories, with secrets and personal details removed. |
| `refs/orchestra/sessions/<person>` | Your published sessions, redacted the same way. |
| `refs/orchestra/issues/<person>` | Your issues, sealed with the team key. |
| `refs/orchestra/team-key` | The team key, sealed separately for each teammate's computer. |

Each person only ever writes their own refs, and every write is a new commit
on top of the last, so nothing anyone shared is overwritten or merged.

### Why refs, not branches

Refs outside `refs/heads/` stay out of everyone's way: they do not show up as
branches, `git clone` and `git pull` do not fetch them, CI does not run on
them, and branch protection on `main` does not apply to them. Your teammates'
checkouts stay exactly as they were. Orchestra fetches only the refs it needs,
and from them only the memories and sessions a task needs.

## Look for yourself

List what a repository holds with plain git, without Orchestra:

```bash theme={null}
git ls-remote origin 'refs/orchestra/*'
```

```text theme={null}
5d1c...  refs/orchestra/issues/7f3e9c2a-...
9a04...  refs/orchestra/memory/7f3e9c2a-...
c71b...  refs/orchestra/sessions/7f3e9c2a-...
e210...  refs/orchestra/team-key
```

On your computer:

```bash theme={null}
orchestra share log            # what sharing did, in order, with the reason for anything held or failed
orchestra session shared       # what this computer published, and what was held back and why
orchestra memory shared        # your shared memories, and any that wait
orchestra doctor               # every check, with the command that fixes each
```

The desktop app's **Sharing** screen shows the same state for each
repository: where it publishes, the last push and fetch, and anything held
back, with a fix. To read your own memories as plain files,
`orchestra memory export --out <folder>` writes one Markdown file per memory.

## Many repositories in one folder

If your team keeps several repositories side by side (for example
`~/code/acme/api`, `~/code/acme/web` and a dozen more), run
`orchestra enable --local` in the parent folder. It turns on every
repository in it. A session you start in the folder and that works in two of
them is published to each repository it touched, and each memory goes to the
repository its evidence came from. See
[A folder of repositories](https://docs.orchestrahq.ai/shared-memory.md#a-folder-of-repositories).

## Protected branches and hosts that refuse refs

Protecting `main`, or requiring pull requests, does not affect Orchestra:
nothing is ever pushed to a branch. On GitHub, branch and tag rulesets apply
to branches and tags only.

Some organizations allow only branches and tags at all (a GitHub push
ruleset, or a server hook). Then the host refuses `refs/orchestra/*`. Two
things tell you: `orchestra doctor` pushes a small test ref to each
repository (and deletes it at once) and says when it was refused, and
`orchestra share log` shows the refused push with the host's own words. Either
ask for `refs/orchestra/memory/*`, `refs/orchestra/sessions/*` and
`refs/orchestra/issues/*` to be allowed, or use a memory repo.

## A memory repo for the whole team

A team admin can send everything to one dedicated repository instead of each
code repository:

```bash theme={null}
orchestra team memory-repo set git@github.com:acme/orchestra-memory.git
```

From each teammate's next share, every session, memory and issue from every
repository in the team goes there, and nothing more to the code
repositories. In the memory repo, each person's work is also on branches you
can browse on your git host: `orchestra/memory/<person>`,
`orchestra/sessions/<person>` and `orchestra/issues/<person>`. Anyone who can
read the memory repo reads work from every repository in the team, so keep it
private to the team. See [A memory repo](https://docs.orchestrahq.ai/shared-memory.md#a-memory-repo).

## What teammates see, and when

| When | What happens |
| - | - |
| While you work | Teammates on your team see your session as live over the team's relay, while both computers are online: a short summary (its title, agent and latest activity line), never the session itself. |
| When a session ends | It and its memories are redacted, checked for secrets and pushed to git in the background. A private session, and a repository where you said no, never are. |
| When a teammate's agent starts a task | Their computer fetches the index of what was shared, picks the few memories that bear on the task, and fetches only those. |
| When a teammate opens a cited session | Their computer fetches that one session. |
| Issues | Sealed with the team key and synced through git when either of you works with issues. A push also nudges teammates' computers online to fetch now. |

Visibility follows your git host: whoever can read the repository (or the
memory repo) can read what was shared there, and nobody else.

## Related

* [Working as a team on Local](https://docs.orchestrahq.ai/local-teams.md): start or join a team, step by step
* [Troubleshooting Orchestra Local](https://docs.orchestrahq.ai/local-troubleshooting.md): what each problem looks like and how to fix it
* [Shared memory](https://docs.orchestrahq.ai/shared-memory.md): sharing, the team key, publishing and unpublishing in detail


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