Arc documentation

A provider needs a tool connection to call Arc MCP. It may also need a separate session connection so Arc can identify, focus, bind, or wake the exact conversation.

• Apple Silicon Mac running macOS 14 or later.
• Internet access for activation, downloads, and any cloud providers you connect.
• An account/app for the AI providers you choose to use.
• Git only if you want Arc's Git workspace features.

Private Early Access builds are distributed as a versioned DMG. Drag Arc.app to Applications, open it, then complete the Setup and Connectors pages. Release builds load Arc MCP and its native helpers from the signed app bundle; the managed workspace configuration lives under Application Support.

Arc.app/Contents/Helpers/
├── arc-mcp
├── orqara-arc-mcp-stdio
├── orqara-arc-connector-gateway
└── orqara-arc-managed-relay

~/Library/Application Support/OrqaraArc/arc-mcp/
└── config.toml

Public distribution still depends on the final Developer ID, notarization, Gatekeeper, and clean-Mac release acceptance pass. Those release gates do not turn Xcode, Python, Homebrew, Terminal setup, or source checkouts into normal-user requirements.

Contributors building Arc from source still need the development toolchain and source checkouts. From the Arc checkout, the development builder installs a stable signed Arc Dev.app at ~/Applications/Arc Dev.app.

cd /ABSOLUTE/PATH/TO/Arc
tools/build_arc_dev_app.sh
open "$HOME/Applications/Arc Dev.app"

Arc Dev can refresh a sibling Arc MCP checkout automatically. You can also refresh the managed runtime directly while developing:

cd /ABSOLUTE/PATH/TO/arc-mcp
tools/install_arc_managed_runtime.sh

1. 01Open Settings → Arc MCP.
2. 02Choose Add Workspace… and select the folder Arc should be allowed to see. New workspaces start Read Only.
3. 03Choose an Access level for that workspace. Developer is the recommended profile for normal coding work.
4. 04Enable Protect only when you want Arc MCP path-specific mutations coordinated with active Agent Bus reservations.

Connecting a provider, joining a room, or binding a conversation never adds another folder automatically. Each workspace remains separately authorized.

When Protect is enabled for a workspace, Arc checks active Agent Bus reservations before path-specific Arc MCP file mutations. It is not an OS file lock and does not cover arbitrary commands, configured tasks, Git push, or provider-native tools. It adds coordination; it does not grant a permission that the workspace otherwise lacks.

Arc MCP rejects parent/absolute escapes, out-of-root symlinks, .env*, SSH/cloud credential folders, Git internals, common private-key formats, and unsafe large/binary reads. The active MCP configuration is itself protected from MCP mutation so an agent cannot rewrite its own permissions.

Normal users should manage workspaces in the Arc MCP tab. For source builds, configured tasks, or advanced debugging, Setup → Show Config reveals the underlying file at ~/Library/Application Support/OrqaraArc/arc-mcp/config.toml.

[server]
host = "127.0.0.1"
port = 8765

[workspaces.my_project]
path = "/ABSOLUTE/PATH/TO/MY-PROJECT"
allow_git = true
allow_write = true
allow_git_write = true
git_push_remote = "origin"
allow_tasks = true
allow_exec = false
protected_collaboration = false

[workspaces.my_project.tasks.build]
argv = ["/usr/bin/swift", "build"]
timeout_seconds = 180
description = "Build the project"

[workspaces.my_project.tasks.test]
argv = ["/usr/bin/swift", "test"]
timeout_seconds = 180
description = "Run the test suite"

Accessibility is intentionally feature-specific. Smart menu-bar crowding uses it to adapt around menu items. Some App-mode prefill/draft-safety paths use it to verify an exact composer or protect a user draft. Native background send paths do not treat Accessibility typing as a fallback when their verified provider-native transport is unavailable.

Keep Arc MCP bound to 127.0.0.1:8765. ChatGPT cannot call localhost directly, so this route uses OpenAI Secure MCP Tunnel.

1. 01Open Settings → Arc MCP and add only the workspaces you want ChatGPT to be able to reach. New workspaces start Read Only.
2. 02Open Settings → Setup → OpenAI Secure MCP Tunnel. Save the tunnel ID there, then choose Open ChatGPT Setup to continue in Connectors.
3. 03In Settings → Connectors → ChatGPT, use Set Up / Connect / Reconnect / Repair as appropriate. Enter the restricted runtime key during connector setup; Arc stores its reconnect copy in Keychain.
4. 04If tunnel-client is missing, the current installer can use an existing Homebrew installation to install OpenAI's supported package. Arc does not bundle tunnel-client yet.
5. 05For an admin-assisted first run, Create automatically can use a temporary OpenAI admin key plus the restricted runtime key and organization/workspace scope. Arc does not persist the admin key.
6. 06Wait for Arc to report the tunnel ready and verify the required Arc MCP tool catalog. Treat Arc's current verification result as authoritative rather than relying on a fixed tool count.
7. 07Choose Open ChatGPT Connectors. In ChatGPT create a developer/custom MCP app, choose Tunnel, select the same Arc MCP tunnel, let ChatGPT discover the tools, and name the app Arc MCP.

OpenAI can rename or move developer controls. Use the current Secure MCP Tunnel documentation when the provider UI differs from these labels.

1. 01Keep Arc MCP on loopback; do not expose port 8765 to the network.
2. 02In Settings → Arc MCP, choose Add Workspace… for each folder you want agents to access. New workspaces start Read Only.
3. 03In Settings → Setup, configure the OpenAI Secure MCP Tunnel. Save the tunnel ID there; the restricted runtime key is entered during ChatGPT connector setup and stored in Keychain.
4. 04Open Settings → Connectors → ChatGPT and use Connect / Reconnect / Repair as needed. Arc keeps implementation details and diagnostics out of the normal steady-state card.
5. 05Choose Open ChatGPT Connectors, create an app using Tunnel as the connection method, select the same Arc MCP tunnel, let ChatGPT discover the tools, and name the app Arc MCP.
6. 06If you want browser session discovery/routing, use Settings → Setup → Browser Extension, load the bundled extension, paste its extension ID, then Install / Refresh Native Bridge.
7. 07Open the exact ChatGPT conversation you want Arc to see, then bind it to the room from the Rooms panel.

The bridge forwards coarse visible provider/session state and a sanitized canonical conversation identity. Arc MCP activity remains the source of truth for machine actions.

1. 01Install the official ChatGPT Desktop app and launch Arc.
2. 02Open Settings → Connectors → ChatGPT and choose App under Open conversations in.
3. 03Use the ChatGPT connector's Connect / Reconnect / Repair flow. Native routing is managed from this connector card rather than a second native-routing settings section.
4. 04Open the exact ChatGPT conversation you want to use, then bind or rebind it from the Rooms panel.
5. 05Choose your Agent Bus automation level: wake, prefill, auto-send, and optionally background auto-send.
6. 06Use the connector's Diagnostics disclosure only when routing or connection health needs investigation.

If Diagnostics reports a Conflicting Codex override, another tool has already set CODEX_CLI_PATH. Arc deliberately refuses to overwrite it automatically.

After a conversation is bound to a room, choose the Browser or App destination and enable only the automation level you want.

1. 01Open Settings → Setup → Claude Relay.
2. 02Enter the public HTTPS relay URL and the relay device credential, then choose Save and Connect Relay.
3. 03If Arc shows a Claude pairing code, use it while authorizing the connector in Claude.
4. 04Open Settings → Connectors → Claude for provider connection/session controls and Diagnostics.
5. 05When connected, Claude receives the Arc MCP tool catalog; each call is still enforced by the workspace's local permission profile.

The default managed relay exposes a public HTTPS connector while the machine-side relay remains attached. In workspace-policy mode, the relay does not upgrade capabilities: Arc MCP still decides whether each workspace is read-only, writable, task-enabled, or Full Access.

Use Stop & Revoke when you explicitly want to invalidate Claude's connector authorization rather than merely stop the local process.

1. 01Choose App as Claude's session destination in Arc.
2. 02Under Direct Claude session, choose Sign in with Claude.
3. 03Email and magic-link sign-in stay inside Arc; Google sign-in opens in your normal browser and returns only Claude's one-time callback to Arc.
4. 04Use Check Session until Arc reports the direct session is connected.
5. 05Open the exact Claude conversation you want, then bind or rebind it to the room in Arc.
6. 06Enable Agent Bus wake, Prefill, Auto-send, and optionally Auto-send in background only to the level you want.

Arc stores this Claude session only in its own persistent WebKit data store. Google sign-in uses Claude's provider-owned browser hop; Arc receives only the one-time callback needed to complete its own session. Arc does not import your normal browser cookies or Claude Desktop cookies.

Claude Code is a local stdio surface, separate from Claude Web. Arc generates an Arc MCP Claude plugin under its Application Support directory, adds the local Orqara marketplace to Claude Code, and installs arc-mcp@orqara-arc at user scope. The plugin's .mcp.json contains only the fixed Arc stdio helper path and connector ID; the connector credential remains in Keychain.

In the Claude Code card, use Connect and Diagnose. Leave executable/helper overrides empty when Arc can discover the packaged or standard local paths.

Clicking a connected agent card opens or focuses that agent's associated session. Browser routes use the validated canonical conversation URL. Native App routes use the provider-specific exact conversation identity when that integration has been verified. Arc does not deliberately route by a matching title alone.

Arc MCP emits structured activity for completed tool calls. Arc can show workspace/tool metadata, Git operations, configured tasks, command results, and exact text-mutation +/- summaries without persisting arbitrary file-read contents or raw tool payloads.

File mutations with diff artifacts can be expanded into the tall in-notch review. Use Open in VS Code to jump to the validated local file when that action is available.

Open the Rooms panel to create/rename rooms, add connected agents, remove agents, and delete rooms. Each room can also link to one configured Arc MCP workspace using the room's workspace selector. That link is editable later and is especially important for Codex wake, which fails closed when the room has no usable linked workspace.

1. 01Choose Browser or App as the provider's session destination in Settings → Connectors.
2. 02Open the exact ChatGPT or Claude conversation you want on that surface.
3. 03Open the room and find that agent's conversation row.
4. 04Choose Bind, or Rebind when a binding already exists.
5. 05Select the validated conversation candidate. Arc stores the exact provider conversation identity, not just its display title.
6. 06Use Clear when you deliberately want the room to have no conversation binding for that agent.

Codex App uses its own durable room-level binding: (room, Codex agent) → exact Codex thread ID. Open the intended Codex thread, then use Bind or Rebind in the room's Codex row; Clear removes that binding. Arc prefers the provider's real thread title for the label when available, but routing authority remains the exact thread ID.

The room workspace link and the Codex thread binding are separate. Linking a workspace does not bind an existing App thread, and selecting a thread does not prove it belongs to the linked workspace. Choose the intended thread explicitly.

Arc does not claim it can safely bind any arbitrary pre-existing Codex CLI terminal. CLI mode uses Arc's managed persistent Terminal session for the room's linked workspace. App thread Bind / Rebind / Clear applies only to Codex App mode.

An Arc wake contains only opaque collaboration references such as room, delivery, handoff, or task IDs. The agent then calls Agent Bus sync/read tools to retrieve the actual content and decides whether to acknowledge, accept, claim, decline, or reply. Peer-authored text is not blindly pasted into another provider's composer.

Tasks use bounded leases so two agents cannot both believe they own the same exclusive task. A claimed task progresses through working and review to complete, or can be made available again when ownership should be released.

Room broadcasts and generic todo tasks do not imply autonomous fan-out. Targeted deliveries are the normal wake trigger, and higher-level autonomous cooperation still depends on your instruction and each provider's own approval policy.

Arc treats the target conversation's state as a safety gate. If a provider turn is active, a draft exists, or the exact destination cannot be established, delivery is queued or left for manual action rather than typed into the wrong place.

Side-effecting submission is intentionally one-shot. If Arc loses the response channel after a potentially successful send, it records the submission as uncertain instead of blindly sending the same wake again.

Arc has live-tested finite ChatGPT ↔ Claude Agent Bus cooperation across independently bound rooms. That transport capability does not authorize an open-ended agent loop: the agents still need an explicit user instruction that permits the collaboration they are being asked to perform.

lsof -nP -iTCP:8765 -sTCP:LISTEN

# Expected managed endpoint:
http://127.0.0.1:8765/mcp

Start in Settings → Connectors and use the provider card's Diagnose / Diagnostics and reconnect controls. Setup owns ordinary Arc MCP, Browser Extension, OpenAI Tunnel, and Claude Relay readiness; Arc MCP owns workspace authority. Low-level executable/path overrides belong only to the debug Dev tab.