One ConnectHelp
Troubleshooting and FAQ
Fixes for the problems people hit most, and answers to common questions about cost, privacy and how One Connect works.
Installing and starting#
macOS says the app cannot be opened#
Until a release is signed and notarized, macOS blocks the first launch. Open System Settings → Privacy & Security and choose Open Anyway next to One Connect. See Open it the first time.
The engine does not start#
The Mac app records startup failures in daemon.log in ~/Library/Application Support/dev.agentcontrolcenter.desktop/. Common causes: the project's repository moved (re-add it in Projects), or its configuration no longer validates (the log names the field).
"Refusing to use … for durable state: it is inside a temp directory"#
The data folder must survive reboots so run evidence is not lost. Set ACC_DATA_DIR to a durable folder. For development only, ACC_ALLOW_TEMP_DATA_DIR=1 lifts the check.
"No control-center.yaml found"#
From source, acc looks for --config, then ACC_CONFIG, then control-center.yaml in the current folder. Copy examples/control-center.yaml and edit it, or pass --config.
"no running daemon found"#
acc open, status, kill-all and context need a running daemon. Start one with acc daemon (or pnpm demo), or point at its data folder with --data-dir.
Agents#
Dispatch is blocked#
Open the issue's Dispatch panel: pre-flight names the failing check and how to fix it. The usual ones:
| Pre-flight says | Fix |
|---|---|
| Signed in: failed | Run the vendor's sign-in command in a login terminal, then re-check in Agents and sign-in |
| Own account and vendor terms | Record your own-account confirmation, or re-confirm after it expired or the account changed |
| Billing | The login is metered (an API key, or overage). Sign in with your subscription, or opt in deliberately per agent. |
| Official vendor binary | The Claude Code or Codex binary is not signed by its vendor. Reinstall it from the vendor. |
| Kill switch | Release the kill switch in the top bar, or acc release |
| Path overlap | Another running assignment owns the same paths. Wait, or narrow the scope. |
| No secrets in prompt | The assignment text contains something that looks like a credential. Remove it. |
| Usage | The agent's included usage window is exhausted. Wait for it to reset, or reassign. |
An agent shows "not installed" although it is#
acc onboard lists every copy it finds on PATH and inside app bundles. Tools installed into ~/.local/bin (Cursor) need that folder on your PATH. Pin an exact copy with binary: in the agent's settings.
A run stalled#
A run with no events for 10 minutes (policies.stall.no_event_minutes) raises a stall alert. Open the agent's console to see the last output, then nudge, message or stop it. If an approval is pending, answer it in the inbox.
A run finished without a handoff#
One Connect looks for a handoff in the agent's MCP call, its final message and its commit bodies. If none is found, an alert offers a generated skeleton you can review and accept.
A run was stopped for overage#
The vendor reported paid overage in use and the agent has no metered opt-in. Turn extra usage, on-demand billing or credit auto-recharge off in the vendor account.
Checks and merges#
Checks say "unavailable"#
Required checks only run in your configured local Docker runtime. Check that project.check_runtime is set, Docker is running, the endpoint is the local socket, and the image is installed locally (One Connect never pulls it). Try acc check --config … --sha HEAD to see the exact reason. See Project checks in Docker.
The merge button stays disabled#
Every merge gate must pass: the issue is Approved, an independent reviewer approved this exact SHA, the required checks passed at this SHA in the current runtime, the target is the integration branch, and every prerequisite workflow step is done. Custom git merge drivers also disable merges.
The tracker shows "dry run" or "out of sync"#
Dry run means live: false: writes wait in the outbox. Set live: true once you have reviewed the integration. Out of sync means two deliveries failed; check gh auth status for GitHub or the Linear key, then resolve the alert.
Context#
One Ask says "Partial" or "Stale"#
A stage is off, missing, failed or truncated; the status says which. Large repositories beyond 2,000 files or 16 MiB are indexed partially. A failed Graphify build keeps the previous graph and labels it stale. Uncommitted work is never indexed: commit it.
The code graph is unavailable#
Install Graphify with uv tool install graphifyy (or pipx install graphifyy). Nothing else depends on it.
Semantic search does not work#
The embedding model must already be installed in a local Ollama on 127.0.0.1, or use the Mac app's bundled model at http://127.0.0.1:11435 with qwen3-embedding:0.6b. Keyword search keeps working either way.
FAQ#
Does One Connect cost anything to run?#
The app itself is free. Agents run on the subscriptions you already have, API-key variables are stripped, metered billing blocks dispatch, and hitting a usage limit never falls back to paid usage. You only pay per token if you explicitly opt an agent into metered billing.
Does my code leave my Mac?#
Only through your agents' own vendor tools, exactly as when you use those tools directly, and through integrations you explicitly enable. See What leaves your Mac.
Can several people share one installation?#
Not with subscription logins: vendors' personal plans are for one person. For shared, hosted or customer use, set policies.accounts.mode: api-keys-only, so each agent uses an API key billed to its owner.
Can agents push to main or deploy?#
No. Pushes to protected branches are blocked in every worktree, the daemon never pushes, merges go into the integration branch after your Decision, and deploys go through the release cockpit, one approved step at a time.
Does it work on Windows or Linux?#
The engine and browser dashboard run from source on macOS and Linux. The packaged app is macOS only for now; Windows is a later target.
Why is the command called acc?#
It comes from the project's earlier name, Agent Control Center, and is kept so existing projects and logs stay accessible.
Where do I report a bug or a security issue?#
Bugs: GitHub issues. Security issues: privately, through the repository's Security tab. See Reporting a vulnerability.