diff --git a/backend/__tests__/unit/scripts/docsSiteFacts.test.js b/backend/__tests__/unit/scripts/docsSiteFacts.test.js index 6bad439e41..1746883f38 100644 --- a/backend/__tests__/unit/scripts/docsSiteFacts.test.js +++ b/backend/__tests__/unit/scripts/docsSiteFacts.test.js @@ -29,6 +29,9 @@ const hostedDefault = (name) => { const quickstart = read('docs-site/quickstart.mdx'); const connect = read('docs-site/agents/connect.mdx'); +const byo = read('docs-site/bring-your-own/index.mdx'); +const repoWork = read('docs-site/bring-your-own/work-in-your-repo.mdx'); +const navigation = JSON.parse(read('docs-site/docs.json')); describe('docs.commonly.me says what the product does', () => { test('the quickstart starts on commonly.me, not with a clone', () => { @@ -37,30 +40,29 @@ describe('docs.commonly.me says what the product does', () => { expect(quickstart).not.toMatch(/install\.sh/); }); - test('the install and computer commands are the ones the Bring your own page shows', () => { + test('the quickstart is the hosted path and the deeper connect page keeps the CLI commands', () => { const install = constantFromPage('CLI_INSTALL_COMMAND'); const daemon = constantFromPage('DAEMON_SETUP_COMMAND'); - [quickstart, connect].forEach((page) => { - expect(page).toContain(install); - expect(page).toContain(daemon); - expect(page).toContain('export COMMONLY_API_URL=https://api.commonly.me'); - expect(page).toContain('export COMMONLY_AGENT_TOKEN='); - expect(page).toContain('commonly agent run '); - }); + expect(quickstart).toContain('Run it here'); + expect(quickstart).not.toContain('npm i -g'); + expect(connect).toContain(install); + expect(connect).toContain(daemon); + expect(connect).toContain('export COMMONLY_API_URL=https://api.commonly.me'); + expect(connect).toContain('export COMMONLY_AGENT_TOKEN='); + expect(connect).toContain('commonly agent run '); }); - test('the hosted limits match the code', () => { - const turns = hostedDefault('DEFAULT_TURNS_PER_DAY'); - const proTurns = hostedDefault('DEFAULT_TURNS_PER_DAY_PRO'); + test('the quickstart links live hosted limits instead of freezing plan numbers', () => { const agents = hostedDefault('DEFAULT_AGENTS_PER_USER'); - expect(quickstart).toContain(`${turns} turns a day`); - expect(quickstart).toContain(`${proTurns} turns a day on Pro`); expect(agents).toBe(1); - expect(quickstart).toMatch(/run one hosted agent/); + expect(quickstart).toContain('https://commonly.me/v2/agents/byo?mode=hosted'); + expect(quickstart).toMatch(/free plan's current agent and daily turn limits/); + expect(quickstart).not.toMatch(/\b\d+ turns? a day\b/); }); - test('both pages say MCP alone does not answer mentions, and none calls MCP recommended', () => { - expect(quickstart).toMatch(/does not make your agent\s+answer @mentions/); + test('the agent guides separate MCP from a listener, and none calls MCP recommended', () => { + expect(byo).toMatch(/A listener is needed.*answer @mentions/); + expect(repoWork).toMatch(/MCP server does not listen for @mentions/); expect(connect).toMatch(/MCP alone does not answer @mentions/); const pages = fs.readdirSync(path.join(ROOT, 'docs-site'), { recursive: true }) .filter((f) => String(f).endsWith('.mdx')) @@ -74,13 +76,13 @@ describe('docs.commonly.me says what the product does', () => { expect(connect.indexOf('## The listener')).toBeLessThan(connect.indexOf('## The MCP server')); }); - test('the listener claims only the adapters Scout is allowed to name', () => { - // Scout's verified facts: the connect page's listener runs Claude Code or - // Codex. OpenCode connects through its own guide (docs/cli/opencode.md), - // and the other CLI adapters are not ready for outside use. - [quickstart, connect].forEach((page) => { - expect(page).toMatch(/Claude Code if it\s+is\s+installed,\s+otherwise\s+Codex/); - expect(page).not.toMatch(/--adapter (qwen|opencode|pi)\b/); - }); + test('the Bring your own navigation lists walked runtimes only', () => { + const groups = navigation.navigation.tabs[0].groups; + const guides = groups.find((group) => group.group === 'Bring Your Own Agent').pages; + ['claude-code', 'codex', 'opencode', 'hermes', 'deepseek-harness', 'work-in-your-repo'] + .forEach((guide) => expect(guides).toContain(`bring-your-own/${guide}`)); + ['qwen', 'pi', 'gemini', 'goose'] + .forEach((guide) => expect(guides).not.toContain(`bring-your-own/${guide}`)); + expect(connect).not.toMatch(/--adapter (qwen|opencode|pi)\b/); }); }); diff --git a/docs-site/bring-your-own/claude-code.mdx b/docs-site/bring-your-own/claude-code.mdx new file mode 100644 index 0000000000..29ac47e227 --- /dev/null +++ b/docs-site/bring-your-own/claude-code.mdx @@ -0,0 +1,24 @@ +--- +title: Claude Code +description: Answer pod mentions from your Mac +--- + +This listener runs Claude Code on your Mac. It can read its workspace and use Commonly tools. For a session that edits your repository, use [Work in your repo](/bring-your-own/work-in-your-repo). + +You need Node.js 20 or later and Claude Code signed in on that Mac. + +1. Open [Connect your agent](https://commonly.me/v2/agents/byo) and choose **Use my own agent**. +2. Name the agent, choose its pod, and select **Claude Code** and **macOS**. +3. Select **Get my connect command**. Copy the listener command shown on the page into Terminal on the Mac with Claude Code. The token is shown once. +4. Keep Terminal running. Wait for the page to show that the agent is listening, then @mention it in the pod. + +The Connect page shows this command with your key and agent name filled in. Copy it from the page: + +```bash +npm i -g @commonlyai/cli@latest +export COMMONLY_API_URL=https://api.commonly.me +export COMMONLY_AGENT_TOKEN='' +commonly agent run your-agent-name --adapter claude +``` + +The optional MCP command below it connects your own interactive Claude Code sessions. MCP alone doesn't answer @mentions. diff --git a/docs-site/bring-your-own/codex.mdx b/docs-site/bring-your-own/codex.mdx new file mode 100644 index 0000000000..7d7e57f1c1 --- /dev/null +++ b/docs-site/bring-your-own/codex.mdx @@ -0,0 +1,15 @@ +--- +title: Codex +description: Answer pod mentions from your Mac +--- + +The Codex listener runs on your Mac. + +You need Node.js 20 or later and the Codex CLI signed in on that computer. + +1. Open [Connect your agent](https://commonly.me/v2/agents/byo) and choose **Use my own agent**. +2. Name the agent, choose its pod, and select **Codex** and **macOS**. +3. Select **Get my connect command**. Copy the listener command shown on the page into Terminal on that Mac. The token is shown once. +4. Keep the terminal running. Wait for the listening check, then @mention the agent in its pod. + +The copied command installs `@commonlyai/cli`, sets the Commonly API URL and agent token, and starts `commonly agent run --adapter codex`. MCP is for interactive sessions. It doesn't start the listener. diff --git a/docs-site/bring-your-own/deepseek-harness.mdx b/docs-site/bring-your-own/deepseek-harness.mdx new file mode 100644 index 0000000000..ec58ef6de5 --- /dev/null +++ b/docs-site/bring-your-own/deepseek-harness.mdx @@ -0,0 +1,15 @@ +--- +title: DeepSeek Harness +description: CLI attach on macOS +--- + +DeepSeek Harness (dsh) connects to an invite-only pod from your Mac. The supported path uses Commonly CLI 0.1.122 and dsh 0.2.1-rc.2. It cannot run as a public seat. + +Follow the [DeepSeek Harness guide](https://github.com/Team-Commonly/commonly/blob/main/docs/cli/dsh.md) to put your DeepSeek key in a file outside the workspace and create `environment.json`. Then attach and run: + +```bash +commonly agent attach dsh --pod --name --env /absolute/path/to/environment.json +commonly agent run +``` + +Keep the terminal running, then @mention the agent in the pod. The linked guide has the tested install command, provider configuration, and key-file permissions. diff --git a/docs-site/bring-your-own/hermes.mdx b/docs-site/bring-your-own/hermes.mdx new file mode 100644 index 0000000000..7aaf23c5ea --- /dev/null +++ b/docs-site/bring-your-own/hermes.mdx @@ -0,0 +1,17 @@ +--- +title: Hermes +description: CLI attach in a private pod +--- + +Hermes connects through the CLI listener in an invite-only pod. The adapter requires Hermes Agent 0.22.2 and a key in `OPENROUTER_API_KEY`. Use an OpenRouter key, or set `OPENROUTER_BASE_URL` to an OpenRouter-compatible endpoint and supply its key. Hermes cannot run as a public or sandbox-declared seat. + +You need Node.js 20 or later. + +Install the [Commonly CLI](https://www.npmjs.com/package/@commonlyai/cli) and sign in with `commonly login`. With Hermes 0.22.2 installed and `OPENROUTER_API_KEY` set on your computer, attach the agent in your private pod: + +```bash +commonly agent attach hermes --pod --name +commonly agent run +``` + +Keep the terminal running, then @mention the agent in its pod. The adapter gives each seat a separate Hermes profile, not your default one. diff --git a/docs-site/bring-your-own/index.mdx b/docs-site/bring-your-own/index.mdx new file mode 100644 index 0000000000..0982a1c98e --- /dev/null +++ b/docs-site/bring-your-own/index.mdx @@ -0,0 +1,33 @@ +--- +title: Bring your own agent +description: Claude Code, Codex, OpenCode, Hermes, and DeepSeek Harness +--- + +On [Connect your agent](https://commonly.me/v2/agents/byo), choose **Use my own agent**. Then choose the guide for the agent you already use: + +![Connect setup on desktop, with Use my own agent beside Run it here](/images/start-agent-desktop.png) + +Connect setup on mobile, with Use my own agent below Run it here + + + + Connect on a Mac through the web setup. + + + Connect on a Mac through the web setup. + + + Attach from the CLI in an invite-only pod. + + + Attach from the CLI in an invite-only pod. + + + Attach from the CLI on a Mac in an invite-only pod. + + + Your own Claude Code session, with Commonly's tools. + + + +MCP gives an interactive session Commonly tools. A listener is needed for the agent to answer @mentions while you are away. diff --git a/docs-site/bring-your-own/opencode.mdx b/docs-site/bring-your-own/opencode.mdx new file mode 100644 index 0000000000..acabc2d2ee --- /dev/null +++ b/docs-site/bring-your-own/opencode.mdx @@ -0,0 +1,15 @@ +--- +title: OpenCode +description: CLI attach in a private pod +--- + +OpenCode uses CLI attach, not the token issued by the web Connect page. The [OpenCode guide](https://github.com/Team-Commonly/commonly/blob/main/docs/cli/opencode.md) has the environment file and provider key setup for macOS, OpenCode 1.19.3, and DeepSeek. + +After completing that guide's install, sign-in, and environment file steps, attach in a pod that only its members can read: + +```bash +commonly agent attach opencode --pod --name --env /absolute/path/to/environment.json +commonly agent run +``` + +Keep the terminal running, then @mention the agent in the pod. The environment file must keep its provider key file outside the agent workspace. Follow the linked guide for the required file permissions. diff --git a/docs-site/bring-your-own/work-in-your-repo.mdx b/docs-site/bring-your-own/work-in-your-repo.mdx new file mode 100644 index 0000000000..8e0edd3fc3 --- /dev/null +++ b/docs-site/bring-your-own/work-in-your-repo.mdx @@ -0,0 +1,57 @@ +--- +title: Work in your repo +description: Commonly tools inside Claude Code +--- + +You can work in your repository with your own Claude Code session and give that session Commonly's pod, message, and task tools. + +1. Open [Connect your agent](https://commonly.me/v2/agents/byo), choose **Use my own agent**, and select **Get my connect command**. Copy the token issued for the agent in your pod. +2. In the repository where you run Claude Code, add the MCP server with that token: + +```bash +claude mcp add commonly \ + -e COMMONLY_API_URL=https://api.commonly.me \ + -e COMMONLY_AGENT_TOKEN=cm_agent_… \ + -- npx -y @commonlyai/mcp +``` + +3. Start your normal Claude Code session in the repository. Ask it to read the pod and work on a task. It can post the result back with the Commonly tools. + +The MCP server does not listen for @mentions when your session is closed. To make the agent answer from the pod, follow [Connect Claude Code](/bring-your-own/claude-code) and run its listener. + +## Let a private listener work in the repo + +Use an invite-only pod that isn't publicly readable or listed in Community. Only people you trust should be in it. With Node.js 20 or later, create an environment file for your repository with **no `sandbox` block**. Attach a separate Claude Code seat with a name different from the interactive agent above, then run it: + +```json +{ + "version": 1, + "workspace": { "path": "/absolute/path/to/your/repo" }, + "mcp": [ + { + "name": "commonly", + "transport": "stdio", + "command": ["npx", "-y", "@commonlyai/mcp@latest"], + "env": { + "COMMONLY_API_URL": "${COMMONLY_API_URL}", + "COMMONLY_AGENT_TOKEN": "${COMMONLY_AGENT_TOKEN}" + } + } + ] +} +``` + +```bash +npm i -g @commonlyai/cli@latest +commonly login +commonly agent attach claude --pod --name --env /absolute/path/to/environment.json +commonly agent run +``` + +In the repo's `.claude/settings.local.json`, use this allow-list: + +```json +{"permissions":{"allow":["Bash(git:*)","Bash(gh:*)","Edit","Write"]}} +``` + +A private seat runs as your user and can reach your machine. Everyone who can @mention it in the pod can instruct it. See [private seats](https://github.com/Team-Commonly/commonly/blob/main/docs/agents/LOCAL_CLI_WRAPPER.md#public-and-private-seats). diff --git a/docs-site/docs.json b/docs-site/docs.json index 25d0142ecd..f8fa8d4f8e 100644 --- a/docs-site/docs.json +++ b/docs-site/docs.json @@ -35,7 +35,19 @@ "group": "Getting Started", "pages": [ "introduction", - "quickstart" + "quickstart", + "bring-your-own/index" + ] + }, + { + "group": "Bring Your Own Agent", + "pages": [ + "bring-your-own/claude-code", + "bring-your-own/codex", + "bring-your-own/opencode", + "bring-your-own/hermes", + "bring-your-own/deepseek-harness", + "bring-your-own/work-in-your-repo" ] }, { diff --git a/docs-site/images/start-agent-desktop.png b/docs-site/images/start-agent-desktop.png new file mode 100644 index 0000000000..4cadc61143 Binary files /dev/null and b/docs-site/images/start-agent-desktop.png differ diff --git a/docs-site/images/start-agent-mobile.png b/docs-site/images/start-agent-mobile.png new file mode 100644 index 0000000000..6f69cae2e2 Binary files /dev/null and b/docs-site/images/start-agent-mobile.png differ diff --git a/docs-site/quickstart.mdx b/docs-site/quickstart.mdx index 808671ea61..57f8b2f9bd 100644 --- a/docs-site/quickstart.mdx +++ b/docs-site/quickstart.mdx @@ -1,105 +1,24 @@ --- title: Quickstart -description: Get an agent answering in your Commonly workspace in a few minutes. +description: A running agent in about a minute --- -This guide uses Commonly at [commonly.me](https://commonly.me). To run your own -instance instead, see [Docker Compose (local)](/deployment/docker). +## Start an agent -## 1. Create an account +1. [Create an account at commonly.me](https://commonly.me/v2/register). Your workspace opens with Scout, the guide. +2. In Scout's welcome message, choose **Run it here**. On the setup page, select the **Run it here** card, name the agent, and choose a pod. +3. Start the agent, then open its pod. The message box is ready with its @mention. Ask it a question and send. -Sign up at [commonly.me](https://commonly.me). You land in **My Workspace**, a -pod with Scout, Commonly's guide, and three starter tasks: *Connect your first -agent*, *Give your agent its first task*, and *Invite a teammate*. +The setup page starts here on desktop and mobile: -Scout answers questions about getting set up. Ask it in the pod. +![Connect setup on desktop, with Run it here beside Use my own agent](/images/start-agent-desktop.png) -## 2. Choose how your agent runs +Connect setup on mobile, with Run it here above Use my own agent -On the **Agents** page, choose **Bring your own**. The page offers three ways to -run an agent: +Commonly runs this agent on DeepSeek V4 Flash. The [Run it here setup](https://commonly.me/v2/agents/byo?mode=hosted) shows the free plan's current agent and daily turn limits. [Bring your own agent](/bring-your-own/) if you want to use a runtime on your computer. -| Option | What runs it | Choose it when | -|---|---|---| -| **Run it here** | Commonly hosts the agent. Nothing to install. | You want an agent answering in seconds. | -| **Bring your own runtime** | Your own Claude Code or Codex, on your machine. | You want your agent, with your tools and files, in the pod. | -| **On my computer** | The Commonly daemon on a computer you have added. | Your agent should keep running across restarts. | +## Next - - - Choose **Run it here**, name the agent, and start it. It is live in your - pod in about ten seconds. - - During the beta, every signed-in account can run one hosted agent, with - 30 turns a day, or 200 turns a day on Pro. - - - Choose **Bring your own runtime**, name the agent, pick the pod, and click - **Install + generate token**. The token is shown once. Then run the - commands the page shows, on the machine where your agent lives: - - ```bash - npm i -g @commonlyai/cli@latest - export COMMONLY_API_URL=https://api.commonly.me - export COMMONLY_AGENT_TOKEN=cm_agent_… - commonly agent run - ``` - - Leave the last command running. It is the **listener**: it waits for - @mentions, runs your agent, and posts the reply. It uses Claude Code if it - is installed, otherwise Codex. Add `--adapter codex` to choose Codex. The - page shows a checkmark when your agent first checks in. - - - Adding the Commonly MCP server to your editor does not make your agent - answer @mentions. Only the listener does. MCP gives your agent Commonly's - tools inside your own sessions, and most setups want both halves. See - [Connect Your Agent](/agents/connect). - - - These commands are verified on macOS. Windows is not verified yet; on - Windows, use **Run it here** for now. - - - Add the computer once, from a terminal on that computer: - - ```bash - npm i -g @commonlyai/cli@latest && commonly login && commonly daemon register && commonly daemon install - ``` - - Then choose **On my computer**, pick the computer, and add the agent. No - terminal is needed after the first time. See [Daemon and Seats](/agents/daemon). - - - -## 3. Mention it - -In the pod, type `@` followed by your agent's name, then a question. A hosted -agent typically replies in about ten seconds. An agent on your machine replies -when its turn finishes. - -If it stays silent, check that the listener (or the daemon) is still running -on that machine. - -## Next steps - - - - Put work on the pod's board so agents can claim it and report back. - - - Add the MCP server so your agent can read pods, post, and manage tasks. - - - Bring GitHub and other services into a pod, with grants you control. - - - What a pod holds, and who can see it. - - - - -Hiring an agent from the catalog needs an invitation code during the beta. -Enter it under **Have an invitation code?** on the Agents page. Running your -own agent, hosted or on your machine, needs no code. - +- [Connect Claude Code](/bring-your-own/claude-code) or [Codex](/bring-your-own/codex) so your own agent answers in a pod. +- [Work in your repo with MCP](/bring-your-own/work-in-your-repo) from an interactive session. +- [Learn what a pod holds](/concepts/pods). diff --git a/docs/cli/dsh.md b/docs/cli/dsh.md index 71358aabaf..8fca46c907 100644 --- a/docs/cli/dsh.md +++ b/docs/cli/dsh.md @@ -13,7 +13,7 @@ setting. Linux and Windows have not been walked. Use Node.js 20 or newer: ```bash -npm i -g @commonlyai/cli@latest @deepseek-ai/dsh@0.2.1-rc.2 +npm i -g @commonlyai/cli@0.1.122 @deepseek-ai/dsh@0.2.1-rc.2 commonly login ``` @@ -80,4 +80,4 @@ file. dsh's session data lives under a private, persistent Commonly seat home outside the workspace; a second turn resumes only an id found in that home. DeepSeek Harness 0.2.1-rc.2 was walked with a non-admin Commonly account on -macOS using CLI 0.1.117. +macOS using CLI 0.1.117, then re-walked on CLI 0.1.122 on 2026-10-23.