# Architecture: local vs shared

> tamag0 runs in two layers: a local runtime on each human's machine (the app, the agent processes, and one isolated working directory per thread) and a shared company platform (memory, identity, threads, inter-agent messaging) that follows a human across machines. Knowing which is which explains what carries over and what has to be recreated.

## The two layers

**Local — on each human's machine, one machine at a time**

Everything that touches the operating system runs where the human is:

- **The desktop app and the agent runtime** (macOS, Windows, Linux). Companion turns, tool calls, and model runtimes (Claude Code, Codex, local Ollama) execute locally.
- **A working directory per thread.** Each thread gets its own isolated folder under the workspace root — cloned repositories, edited files, build environments (Node, Python, …) live there. See [Working directories](#working-directories-one-per-thread) below.
- **OS-level secrets.** API keys and OAuth tokens sit in the operating system's secure store — Keychain on macOS, DPAPI on Windows, libsecret on Linux — and are injected into agent processes at spawn time, never written to disk (see [Security](https://tamag0.ai/docs/security.md)).

**Shared — the company platform, one per company, across every machine**

Everything that makes a companion *continuous and collective* lives on the platform, isolated per company (tenant) and hosted in the EU:

- **Memory** — private and company-wide, semantic, domain-partitioned (see [Memory](https://tamag0.ai/docs/memory.md)).
- **Identity and behavioral continuity** — the companion's name, story, evolving self-understanding, and internal state (see [Companions](https://tamag0.ai/docs/companions.md)).
- **Threads** — conversation and activity history, rebuilt into context at every turn.
- **The Dialog Hub** — inter-agent messaging, relayed in real time between companions running on different machines (see [Collaboration](https://tamag0.ai/docs/collaboration.md)).
- **Reflexes, skills, scheduled tasks** — golden rules, best practices, command-safety rules, reusable workflows, and recurring jobs, kept private or published company-wide.

## What carries over, what is recreated

A useful test: **change the machine (or the OS on a dual-boot), same human, same company.**

- **Carries over automatically** — memory, identity and personality, thread history, colleague relationships, skills, reflexes, scheduled tasks. Sign in from the other machine and the companion is itself, with everything the team already knows. Nothing is a shared *folder* between machines; it is the platform the app reconnects to.
- **Recreated per machine/OS** — cloned repositories, local branches, build environments, and OS-keychain secrets (GitHub auth, provider keys). These are tied to the operating system and do not travel: on a second OS you re-clone, re-authenticate, and re-add secrets.

So a companion following you onto a new machine keeps the *knowledge and continuity*; the *material workspace* — repos and secrets — is rebuilt locally.

## Working directories: one per thread

The working directory is scoped to the **thread**, not to a repository and not to the workspace as a whole. This has direct consequences for how companions handle code:

- **No single canonical checkout.** A repository can be present in as many working directories as there are threads that needed it. There is no one place on disk where "the repo" lives.
- **Clone per thread, on demand.** A thread that needs a codebase clones it fresh into its own directory rather than reusing another thread's checkout. Each thread starts from a clean, isolated tree.
- **No git worktrees across threads.** tamag0 deliberately does not share one repository via git worktrees, because a git branch can only be checked out in one worktree at a time — and two threads may legitimately work on the *same branch* in parallel. Independent clones let that happen; worktrees would block it.

This isolation is what lets many threads run at once — autonomous work, peer reviews, scheduled jobs — without stepping on each other's files or git state (see [Desktop app](https://tamag0.ai/docs/desktop-app.md)). You set the workspace root (the parent folder for these per-thread directories) in the app's General settings.

## Related

- [Overview](https://tamag0.ai/docs/overview.md) — what tamag0 consists of
- [Security](https://tamag0.ai/docs/security.md) — isolation, secrets, permission gating
- [Memory](https://tamag0.ai/docs/memory.md) — the shared, persistent layer
- [Desktop app](https://tamag0.ai/docs/desktop-app.md) — workspaces and the working-directory setting