Using One Connect

Projects

Each project is one repository with its own engine, database, agents, Docker namespace and terminals. Add, clone, switch and stop projects from Settings → Projects.

One engine per project#

The Mac app runs a separate engine for every project you open. Each has its own event database, agents, worktrees, Dictionary index, Docker Compose namespace, terminals, secrets and phone pairings, stored under its own folder in the app's data. One repository maps to exactly one project.

Switching projects only changes which engine the window shows. Other projects' engines and agent runs keep going, and returning shows their live dashboard and logs. A response that arrives after you switched is dropped, so one project's data never lands in another's view.

Add a local repository#

Open Settings → Projects and choose Choose folder….
One Connect scans the repository root without running any of its scripts: Git state, frameworks, package manager, declared checks, Compose services and Dockerfiles. You see what it detected.
Choose Add and open.

Some folders are refused: a subfolder of a repository (choose the root), your home folder, system folders and credential folders.

If the repository has a control-center.yaml whose project.repo resolves to the same root, that file is used.
Otherwise a private configuration is generated in the app's data. Nothing is written into your repository.
A folder that is not a Git repository gets a reviewable git init step that runs only after you approve it.
A repository with no commits is added as needs first commit. Uncommitted changes are reported as excluded, because Dictionary only indexes work at a Git revision.

Clone from a Git URL#

Enter the Repository URL, choose a parent folder and optionally a folder name, then Prepare clone. One Connect shows the exact git clone command it will run, with hooks, submodules, credential helpers and ext:: transports disabled. It reaches the network only after you Approve and run. The approval is bound to that exact command, expires after two minutes and works once.

URLs with embedded credentials are refused.
SSH URLs may use your SSH agent.
HTTPS credential helpers and prompts are off, so private HTTPS repositories need an SSH URL.

Manage running projects#

Action	Effect
Start engine	Starts the project's engine. Before each start, the app re-checks that the configuration still points at the registered repository and that the engine serves it.
Stop runs	Engages that project's kill switch: every run stops and dispatch is blocked.
Stop engine	Shuts that project's engine down gracefully. Detached runs keep going and are reattached next time.
Kill switch: all projects	Engages the kill switch of every running project.

Engines that were running when you quit restart on the next launch. An engine left behind by a crash is stopped only if its command line proves it is that project's engine.

The project registry#

projects.json in the app's data folder is the durable registry: each project's name, configuration, exact repository root, onboarding scan, the open project and which engines were running. It is readable only by you. A corrupt registry is set aside, never overwritten.

The offline demo#

Without an added project, and any time from the project switcher, the app offers the Offline demo: a sample repository with scripted fake agents and GitHub and Linear import fixtures. Its model names, output and usage reports are examples. It spends no subscription usage and connects to no tracker.

In a browser#

A browser signed in to an engine (for example with acc open) is bound to that one project. Projects are added and switched in the Mac app.