From ccb63a3bc1a8df2831dd9683d8333eb642c41cb4 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Fri, 23 Oct 2026 14:37:18 -0700 Subject: [PATCH 1/4] docs: start local computer agent guide Co-authored-by: nib Agent-Model: codex/gpt-6-sol/medium Agent-Model: codex/gpt-6.1-sol/medium --- docs-site/agents/on-my-computer.mdx | 38 +++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 docs-site/agents/on-my-computer.mdx diff --git a/docs-site/agents/on-my-computer.mdx b/docs-site/agents/on-my-computer.mdx new file mode 100644 index 0000000000..88bab24064 --- /dev/null +++ b/docs-site/agents/on-my-computer.mdx @@ -0,0 +1,38 @@ +--- +title: Run an agent on your computer +description: Add a computer once, then let its daemon run an agent in your pod. +--- + +Your agent can run on a computer you control while joining a Commonly pod. The +Commonly daemon on that computer starts the agent and keeps it running. Your +files and local CLI stay on your computer. + +## Add the computer + +Open **Agents → Bring your own agent**. Under **More ways**, choose **Add a +computer** and run the command shown there on the computer you want to use: + +```bash +npm i -g @commonlyai/cli@latest && commonly login && commonly daemon register && commonly daemon install +``` + +Reload the page after setup. The registered computer then appears as an **On +my computer** option. Setup stores a machine credential locally; the page does +not show an agent runtime key for this path. + +## Add an agent to the computer + +Choose **On my computer**, select the computer and a pod, and name the agent. +You can choose Claude Code or Codex as its local adapter. Select **Add to this +computer**. The daemon picks up the request, starts the agent, and the page +waits for it to report that it is running. Then open the pod and mention the +agent. + +If it keeps waiting, check the daemon on that computer: + +```bash +commonly daemon status --verbose +``` + +For daemon commands and a manual foreground run, see [Daemon and +Seats](/agents/daemon). From 7f5d37c5b3a50685cdd9565caf8f063e4b61a7d0 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sat, 24 Oct 2026 00:43:18 -0700 Subject: [PATCH 2/4] docs: finish local computer agent guide Co-authored-by: nib Agent-Model: codex/gpt-6-sol/medium Agent-Model: codex/gpt-6.1-sol/medium --- docs-site/agents/on-my-computer.mdx | 24 ++++++++++++++++++++++++ docs-site/docs.json | 1 + 2 files changed, 25 insertions(+) diff --git a/docs-site/agents/on-my-computer.mdx b/docs-site/agents/on-my-computer.mdx index 88bab24064..f4cdb512ef 100644 --- a/docs-site/agents/on-my-computer.mdx +++ b/docs-site/agents/on-my-computer.mdx @@ -34,5 +34,29 @@ If it keeps waiting, check the daemon on that computer: commonly daemon status --verbose ``` +## Check the connection + +The agent's card on **Agents** shows whether it is connected, has not +connected yet, or was last seen earlier. Open the agent's **Settings** to see +its connection state and controls. A computer that has stopped checking in +does not silently become a hosted agent; start or check its daemon on that +computer. + +The agent's installer or an instance admin can request a fresh runtime key +from **Settings → Control**. Choose **Regenerate key** while it is connected, +or **Reconnect** if it has disconnected. The bound daemon receives the request +and replaces the agent's key; the new key is not displayed in the browser. +If the computer's own key was revoked, register that computer again before +reconnecting the agent. + +## Remove a computer + +On the computer, `commonly daemon unregister` removes its registration and +local credential. Removing a computer or revoking its machine credential +retires that credential; the daemon and its agents are disconnected on their +next call. To run the agent elsewhere, register another computer and use the +agent's **Settings → Runtime** control to move it. The agent's identity and +memory stay with Commonly. + For daemon commands and a manual foreground run, see [Daemon and Seats](/agents/daemon). diff --git a/docs-site/docs.json b/docs-site/docs.json index be14178bed..5cd70059e7 100644 --- a/docs-site/docs.json +++ b/docs-site/docs.json @@ -76,6 +76,7 @@ "pages": [ "agents/connect", "agents/settings", + "agents/on-my-computer", "agents/adapters", "agents/daemon", "agents/runtime-protocol", From 35065ce221956ccbda9ba0247af2723d53af8af5 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sat, 24 Oct 2026 01:24:39 -0700 Subject: [PATCH 3/4] docs: correct local computer setup and reconnect flow Co-authored-by: nib Agent-Model: codex/gpt-6-sol/medium Agent-Model: codex/gpt-6.1-sol/medium --- docs-site/agents/on-my-computer.mdx | 36 +++++++++++++++++------------ 1 file changed, 21 insertions(+), 15 deletions(-) diff --git a/docs-site/agents/on-my-computer.mdx b/docs-site/agents/on-my-computer.mdx index f4cdb512ef..9b451f4240 100644 --- a/docs-site/agents/on-my-computer.mdx +++ b/docs-site/agents/on-my-computer.mdx @@ -9,8 +9,9 @@ files and local CLI stay on your computer. ## Add the computer -Open **Agents → Bring your own agent**. Under **More ways**, choose **Add a -computer** and run the command shown there on the computer you want to use: +Open **Agents → Bring your own agent**. If you have no computer yet, expand +**Other ways to connect** and choose **Add a computer**. To add another +computer, run the same setup command on it: ```bash npm i -g @commonlyai/cli@latest && commonly login && commonly daemon register && commonly daemon install @@ -23,8 +24,10 @@ not show an agent runtime key for this path. ## Add an agent to the computer Choose **On my computer**, select the computer and a pod, and name the agent. -You can choose Claude Code or Codex as its local adapter. Select **Add to this -computer**. The daemon picks up the request, starts the agent, and the page +Leave the adapter on **Auto-detect on that computer**, or choose one explicitly. +Auto-detect tries Claude Code, then Codex. Claude Code is supported on Mac; +Codex runs on Mac and Linux, including WSL. Select **Add to this computer**. +The daemon picks up the request, starts the agent, and the page waits for it to report that it is running. Then open the pod and mention the agent. @@ -36,27 +39,30 @@ commonly daemon status --verbose ## Check the connection -The agent's card on **Agents** shows whether it is connected, has not -connected yet, or was last seen earlier. Open the agent's **Settings** to see -its connection state and controls. A computer that has stopped checking in +The agent's card on **Agents** shows whether it is connected, **Not connected +yet**, **Not seen in N min**, or **Disconnected: key revoked**. Open the agent's +**Settings** to see its connection state and controls. A computer that has +stopped checking in does not silently become a hosted agent; start or check its daemon on that computer. The agent's installer or an instance admin can request a fresh runtime key -from **Settings → Control**. Choose **Regenerate key** while it is connected, -or **Reconnect** if it has disconnected. The bound daemon receives the request -and replaces the agent's key; the new key is not displayed in the browser. +from **Settings → Control**. **Regenerate key** appears for a connected agent; +**Reconnect** also appears when it is disconnected or its last check-in is +stale. Either control takes you to **Bring your own agent**. Press **Reconnect** +there to send the request to the bound daemon. The daemon then replaces the +agent's key; the new key is not displayed in the browser. If the computer's own key was revoked, register that computer again before reconnecting the agent. ## Remove a computer On the computer, `commonly daemon unregister` removes its registration and -local credential. Removing a computer or revoking its machine credential -retires that credential; the daemon and its agents are disconnected on their -next call. To run the agent elsewhere, register another computer and use the -agent's **Settings → Runtime** control to move it. The agent's identity and -memory stay with Commonly. +local credential. Then run `commonly daemon uninstall` to remove its launchd +or systemd service. Unregistering the computer retires its machine credential; +the daemon and its agents are disconnected on their next call. To run the agent +elsewhere, register another computer and use the agent's **Settings → Runtime** +control to move it. The agent's identity and memory stay with Commonly. For daemon commands and a manual foreground run, see [Daemon and Seats](/agents/daemon). From de0c42ef12274219bb829ea1a5ad4dd2b71bb421 Mon Sep 17 00:00:00 2001 From: Lily Shen <115414357+lilyshen0722@users.noreply.github.com> Date: Sat, 24 Oct 2026 02:36:00 -0700 Subject: [PATCH 4/4] docs: clear stale machine registration before recovery Co-authored-by: nib Agent-Model: codex/gpt-6.1-sol/medium --- docs-site/agents/on-my-computer.mdx | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs-site/agents/on-my-computer.mdx b/docs-site/agents/on-my-computer.mdx index 9b451f4240..2f5be28239 100644 --- a/docs-site/agents/on-my-computer.mdx +++ b/docs-site/agents/on-my-computer.mdx @@ -52,8 +52,10 @@ from **Settings → Control**. **Regenerate key** appears for a connected agent; stale. Either control takes you to **Bring your own agent**. Press **Reconnect** there to send the request to the bound daemon. The daemon then replaces the agent's key; the new key is not displayed in the browser. -If the computer's own key was revoked, register that computer again before -reconnecting the agent. +If the computer's own key was revoked, sign in again with `commonly login` if +needed. Run `commonly daemon unregister` to remove the old local registration, +then `commonly daemon register` before reconnecting the agent. Unregister also +works when the server has already removed the computer. ## Remove a computer