// Guide

Use the desktop app

ArtifactBridge Desktop stays in the menu bar on macOS or the system tray on Windows and Linux. It connects local AI tools, shows work that needs you, manages installed Skills, and starts local agents under your settings.

Install and connect

1. In the browser, open Settings → Connect AI tools and open the installation guide from the Desktop app card.
2. Download the installer for your platform and follow the installation steps. The guide also offers a Homebrew path on macOS.
3. Open ArtifactBridge and complete browser sign-in.
4. Choose the detected coding tools you want to connect.
5. Return to the tool and verify a live ArtifactBridge request in a new conversation.

The desktop app includes the ArtifactBridge connection tooling. You still install and sign in to your chosen AI tool separately. Follow the installation guide for platform-specific download and verification instructions.

Choose the workspace

The desktop sidebar names the active workspace. If you belong to several workspaces, use that name as the workspace picker. Check it before sending work from the browser. An agent conversation may need to restart after a workspace or connection change.

Desktop Inbox

Open the tray icon and choose Inbox. It combines work waiting on you with local agent and maintenance status.

• Approve to send: a pending request to start a local agent. Read it before authorizing the start.
• Waiting on you: questions and decisions. Open the item to act in the browser.
• Rooms: relevant discussion activity and links to the full Room.
• Maintenance: installation, connection, or update work.
• Completed and failed: agent outcomes you may need to inspect.

A local start approval does not accept document edits. Review document changes in the browser after the agent prepares them. If a feed is stale, the app can retain its last known items; read the status before assuming they are current.

Desktop Skills

Installed shows Skills on this device. Browse hub shows workspace Skills you can install. Choose the destination tool, install or update, and check the result. Removing a local installation does not remove the workspace Skill. See Share Skills.

Changes from your tools appears at the top of Installed when a local tool with a write-approval gate, such as Hermes, has staged a change to an installed workspace Skill. Nothing leaves this computer until you act. Open Review change to see the exact lines against the workspace version. Send for review files the staged edit as one ordinary change on the document that backs the Skill. Anyone in the workspace can accept it in the Inbox. Edit the reason adds one sentence for the reviewer. Discard asks a second time, then removes the staged change from the tool on this computer.

Settings: General

• Launch at login: starts ArtifactBridge when you sign in to the computer.
• Theme: selects Light or Dark for the desktop app.
• Coding tools: connects or disconnects each detected tool and shows its setup and credential state.
• Sign out: signs this computer out and revokes its tool credentials.
• Quit ArtifactBridge: stops background checks until you open the app again.

Connect or disconnect a coding tool

Turn on a detected tool in Settings → General → Coding tools and wait for its result. Install an undetected tool first. Turning a tool off asks for confirmation and removes the setup ArtifactBridge owns inside that tool. The tool’s own settings remain.

Read the command-line warning beside a detected desktop AI app. A desktop app and a command-line agent are separate installations. Automatic local starts need a supported, available command-line agent and its own valid sign-in.

Settings: Notifications

The main Notifications switch controls desktop alerts. Individual switches cover decisions that need you, failed agents, watched agents that finish, Room summaries and activity, authorization or system blocks, application updates, and Skill updates.

1. Turn on the main switch and the categories you need.
2. Allow ArtifactBridge notifications in the operating system. Use Open System Settings when the app reports a block.
3. Set quiet hours, their schedule, and time zone if needed.
4. Use Send a test notification to check delivery.

Quiet hours hold alerts while items remain in the Inbox. Turning notifications off does not stop the Inbox from refreshing. The operating system can block alerts independently of the app’s preference. Notification history and delivery status help explain whether an alert was sent, held, or blocked.

Settings: Advanced, agent automation

A wake is a request to start or resume a local agent because a conversation needs it. Automatic starts can consume the AI tool’s tokens and use that tool’s local permissions.

• Wake agents automatically: lets eligible requests start without asking you first.
• Hourly limit: limits automatic starts per conversation in an hour.
• Loop guard: pauses after repeated automatic runs in which the agent did not answer in the Room. For a question or a task, only the agent’s linked reply counts as the answer. A message from you in the Room restarts the count.

Keep limits enabled until you understand the workload. With automatic starts off, inspect pending starts in the desktop Inbox. The app shows missing command-line tools and runtime problems near these controls. Agent recruiting in browser Account settings separately controls whether teammates may request your agents.

Settings: Advanced, updates

The ArtifactBridge Desktop row shows the running version, available update, update owner, and last check. Its action can be Check now, Update, Update in Terminal, Repair installation, or Restart now.

Follow the action for your installation. Homebrew, APT, or DNF installations use their package manager. App-managed installations use the supported updater. When offered, Install application updates automatically allows a verified update when no agent work is active.

An app-managed stable installation installs only stable releases, and an app-managed prerelease installation installs only the newest signed prerelease. A new installation of either kind signs in to production, so a prerelease uses your real ArtifactBridge data. A saved connection stays selected after an update.

Keep skills up to date controls scheduled Skill updates separately from application updates. Inspect its last scheduled run if a Skill remains out of date.

Diagnose and remove an installation

Use Run a diagnosis in Advanced settings to inspect the installation and tool connections. If problems are found, the app can offer an AI repair session or an email with a diagnostic report. Read the proposed repair before applying it.

Use Uninstall… in Advanced settings when you want to remove the installation. Review what the removal flow says it will remove and keep. Windows opens the registered native uninstaller. Quit, sign-out, disabling a tool, and uninstalling are separate actions with different effects.

Prerelease: share this computer's slots

The shared slot pool is a prerelease feature. It works only in workspaces where it is turned on. With the pool, you create, edit, pause, and remove agents in the browser, in Agents in the left navigation. The tray's This computer view controls how this computer runs tasks. It does not create a separate agent. Only the computer owner can join the pool, choose the tool and folder, set 1 to 4 slots, or resume the computer. If this computer has several older agent setups, choose one. Their old slot limits do not add together. Existing sessions keep their original setup. This computer joins the pool only after the work of its older setups ends: queued tasks, tasks with an unknown outcome, and sessions that can still resume.

Joining requires explicit consent: any workspace agent that a requester may use can run here. There is no sandbox. Tasks can use local files, shell, network, and tool sign-ins, and read ArtifactBridge with the sender's access. Joining does not share the sender's Space with you. Ask me first is the default; its Inbox offer holds a slot and shows whose access the task uses. Space details appear only if you can open them. A withdrawn offer disappears. Approve or Decline on an offer that is no longer current starts nothing. The tray checks the tool sign-in, the tool, and the folder when it starts, when it reconnects, and when you join or change the setup. While this check runs, and while a check fails, no new pooled task starts on this computer. Offers that have not started go back to the queue with their place and deadline. An offer that waits for you in the Inbox then shows only Decline. The tray does not start a failed attempt again by itself. Running tasks finish, and you can still stop them. This computer shows what failed and how to fix it. The tray also checks every minute. A computer that is ready stays ready until one of these checks fails. New tasks start again after a check passes and ArtifactBridge confirms it. If you paused this computer, it stays paused until you resume. If you decline, the task keeps its place in the queue and its deadline, and this computer is not asked again for that request.

Pause new tasks withdraws unstarted offers and lets running work finish. Stop running tasks asks current work to stop but does not pause the computer: new tasks may start unless you also pause. If you lower the slot count, work above the new limit finishes; it is not stopped. Offers that wait for your approval count as used slots. A canceled task keeps its slot until the computer confirms the stop, for up to five minutes. After five minutes without confirmation, the slot is free for new tasks, but the canceled task may still be running on the computer. When a task on this computer asks a question, your answer continues the same tool session. ArtifactBridge never starts a new session in its place without telling you.

In browser Settings → Executors, members see slot status without task content and manage their own computers. A computer whose tool is not ready shows Tool not ready to everyone, without the cause. Workspace admins can pause or stop a teammate's computer in an emergency, but cannot change its setup or resume it. Only admins add cloud runners (see Connect a cloud runner). Any current admin manages any cloud runner in the workspace, including one that another admin added. Cloud runners offer 1 to 20 slots and run tasks automatically after an admin adds them to the pool. Agent Pause is different: it refuses new agent tasks, holds waiting ones, and asks running ones to stop.

When you join, ArtifactBridge checks the setup you selected and that this device is still signed in, and only then saves your consent. An older join request cannot make this computer ready. If you change or pause the setup, join again to get a new check. If the join fails or you get no confirmation, your saved local setup stays unchanged. Join again to get a new check.

Connect a cloud runner

Workspace admins connect cloud runners in the browser. Members do not see this flow.

1. Open Settings → Executors and select Connect a cloud runner.
2. Enter a Name, the Listener URL, and the Bearer token. The Listener URL is the HTTPS address of the pooled listener on the runner, not its Agent Card. An address that is not HTTPS is refused, and nothing is saved. The token is the one set on the runner.
3. Select Check connection. ArtifactBridge saves the connection and checks that the runner can take pooled tasks.
4. When the check passes, the dialog shows the pool consent. Read it and select Add to pool. Only Add to pool adds the runner to the pool.

If you select Not now, the runner stays saved with the status Not in the pool. Select Review and join on its row when you are ready.

If the check fails, the dialog stays open with your Name and Listener URL, and the token field is cleared. The message tells you what to correct:

• The runner didn't accept the token. Enter the token set on the runner, then select Check connection.
• This runner doesn't support pooled tasks yet. Update the ArtifactBridge plugin on the runner, then select Check again.
• Couldn't reach the runner. Make sure the runner is running and reachable, then select Check again.

If you close the dialog after a failed check, the saved runner shows Not in the pool · Check failed. Select Review and join on its row to check the saved connection again. Select the runner's name to open its connection, where Check again only checks it and Change connection… changes it.

A pool cutover can end the consent of a runner that is already in the pool. The runner then shows Not in the pool and takes no tasks. Select Review and join. ArtifactBridge checks the saved connection again, without a new token, and then shows the pool consent. The runner takes tasks again only after you select Add to pool.

The token is stored encrypted and is sent only when ArtifactBridge calls the runner. It never appears in Room messages, logs, or the settings page again.