84da8420 · samitouri/QOSami_Agents_Zero

@@ -1,49 +1,28 @@

1 ---

2 name: setup-a0-cli

3 -description: Guide installing, connecting, or troubleshooting the A0 CLI connector on the user's host machine so Dockerized Agent Zero can work on real local files. Use for install A0, set up A0 CLI, connect local files, remote tools, host-vs-container confusion, or CLI connector setup problems.

3 +description: Briefly guide installing, connecting, or troubleshooting the A0 CLI on the user's host so Dockerized Agent Zero can work with real local files. Use for install A0, enable the host connector, connect local files, remote tools, host-vs-container confusion, or A0 CLI setup problems.

4 ---

5

6 # A0 CLI Host Setup

7

8 -Use this skill to guide the user through installing `a0` on their host machine and connecting it to Agent Zero.

8 +`a0` runs on the user's host machine; Agent Zero stays in Docker or its sandbox.

9

10 -## Core Boundary

10 +## Keep The Conversation Short

11

12 -- Agent Zero stays in Docker or its sandboxed runtime.

13 -- `a0` installs and runs on the user's host machine.

14 -- The whole point is to let Agent Zero work on the real files on the user's computer.

12 +- Match the user's brevity. For a brief question, reply with one short sentence and at most one command block.

13 +- Give only the next useful step, then wait for the result. Do not dump installation, connection, fallback, troubleshooting, and success details into one response.

14 +- Ask only for information needed now. For a fresh install, ask only which host OS they use. Ask about previous commands and errors only when they say they already tried or something failed.

15 +- Do not add headings, checklists, expected-output prose, warnings, alternatives, or explanations unless they help with the user's current step or the user asks for detail.

16

16 -## Response Flow

17 +## Fresh Install

18

18 -### 1. Ask whether they already tried

19 +If the host OS is unknown, ask only:

20

20 -Start here:

21 +> Which computer are you installing it on: Windows, macOS, or Linux?

22

22 -> Have you already tried installing `a0`? If so, what command did you run, where did you run it, and what happened?

23 +Once known, give the matching command and tell them to run `a0` when it finishes.

24

24 -If they already tried, diagnose that attempt before repeating instructions.

25 -

26 -### 2. Stop container installs immediately

27 -

28 -If the user is inside the Agent Zero container, `/a0`, `docker exec`, or another sandbox shell, stop and say:

29 -

30 -> `a0` does not get installed inside the Agent Zero container. Exit to your normal host terminal first. Agent Zero stays in Docker; `a0` belongs on your machine.

31 -

32 -Do not keep giving install commands until they are back on the host.

33 -

34 -### 3. Identify the host OS only as needed

35 -

36 -If the platform is unclear, ask one short question:

37 -

38 -> Are you on macOS/Linux shell or Windows PowerShell on the host machine?

39 -

40 -Then use the matching installer.

41 -

42 -### 4. Use the installer-first flow

43 -

44 -Treat these public installer URLs as placeholders for now. Use them first, but be ready to switch to the manual `uv tool install` path if the raw GitHub URL is blocked, private, or unreachable.

45 -

46 -macOS / Linux:

25 +macOS / Linux host terminal:

26

27 ```bash

28 curl -LsSf https://raw.githubusercontent.com/agent0ai/a0-connector/main/install.sh | sh

@@ -55,110 +34,49 @@ Windows PowerShell:

34 irm https://raw.githubusercontent.com/agent0ai/a0-connector/main/install.ps1 | iex

35 ```

36

58 -The installer will install `uv` if needed, then run `uv tool install --upgrade <package-spec>` for the CLI.

59 -

60 -### 5. Use the manual `uv tool install` fallback when needed

61 -

62 -If the placeholder installer URL is unavailable, switch to a manual `uv tool install` flow instead of stopping.

63 -

64 -Public Git fallback:

65 -

66 -```bash

67 -uv tool install --upgrade git+https://github.com/agent0ai/a0-connector

68 -```

69 -

70 -Local checkout or internal mirror examples:

71 -

72 -```bash

73 -uv tool install --upgrade /path/to/a0-connector

74 -uv tool install --upgrade git+ssh://git.example.com/team/a0-connector.git

75 -```

76 -

77 -If they want to reuse the stock installer with a custom package source, explain that the installer honors `A0_PACKAGE_SPEC`.

78 -

79 -### 6. Tell them to run `a0`

80 -

81 -After install, the next step is always:

82 -

83 -```bash

84 -a0

85 -```

86 -

87 -If the command is not found yet, tell them to open a new terminal and run `a0` again.

88 -

89 -### 7. Explain how to connect

90 -

91 -Tell the user what to expect:

92 -

93 -- `a0` opens the host picker first.

94 -- If Agent Zero is running locally, `a0` may discover it automatically.

95 -- If not, the user can enter the Agent Zero web URL manually in the custom URL field.

96 -- The custom URL can be either a normal address with a port, such as `http://localhost:50001`, or a tunnel URL.

97 -- For Flare Tunnel, tell the user to open `Settings > External Services > Flare Tunnel`, click `Create Tunnel`, then copy and paste the HTTPS URL into `a0` exactly as shown.

98 -- Tunnel URLs such as `https://example.trycloudflare.com` do not need a port appended.

99 -- `AGENT_ZERO_HOST` can prefill the target host without bypassing the picker.

100 -

101 -Example:

102 -

103 -```bash

104 -export AGENT_ZERO_HOST=http://localhost:50001

105 -a0

106 -```

107 -

108 -Tunnel example:

109 -

110 -```bash

111 -export AGENT_ZERO_HOST=https://example.trycloudflare.com

112 -a0

113 -```

114 -

115 -### 8. Define success clearly

37 +If the user is inside `/a0`, `docker exec`, or another container shell, stop there: tell them to exit and run the installer in their normal computer terminal. Do not give container installation commands.

38

117 -Successful setup looks like this:

39 +If `a0` is not found after installation, ask them to open a new terminal and try `a0` again.

40

119 -- `a0` starts on the host machine.

120 -- It connects to the user's Agent Zero instance or reaches the login step.

121 -- The user can open a chat from the terminal.

122 -- Agent Zero can now act on real files on the host through the connector flow while Agent Zero itself still runs in Docker.

41 +## Connect

42

124 -## Troubleshooting

43 +Running `a0` opens a host picker and discovers local Docker instances when possible. Tell the user to select the instance it finds.

44

126 -- If the user says they installed inside Docker or shows `/a0` paths, redirect them to the host-machine install.

127 -- If `a0` gets a connector `404`, explain that the running Agent Zero build likely does not include the builtin `_a0_connector` support yet and should be updated.

128 -- If the browser UI works but `a0` does not, remind them the web UI can run without connector support but the CLI cannot.

129 -- If Docker discovery does not find the instance, have them enter the exact Agent Zero URL with `host:port`, or create a Flare Tunnel in `Settings > External Services > Flare Tunnel` and paste that HTTPS URL directly.

45 +If manual entry is needed:

46

131 -## Example Requests And Responses

47 +- Use the exact URL the user currently uses to open Agent Zero, including its actual port.

48 +- Never guess, prescribe, or describe any port as common or default. Do not turn a documentation example into the user's address.

49 +- If the URL is unknown, ask the user to copy it from their browser or Docker's published-port mapping.

50 +- A tunnel URL is pasted exactly as shown and does not need a port appended.

51

133 -### Example 1

52 +Mention `AGENT_ZERO_HOST` only if the user asks to prefill the picker. Use their exact known URL, never an invented example.

53

135 -User: "Help me set up the A0 CLI connector."

54 +## Troubleshoot Only When Needed

55

137 -Respond like this:

56 +- For a failed attempt, ask for the command, whether it ran on the host or in Docker, and the exact output.

57 +- If the installer URL is unreachable but `uv` works, use:

58

139 -1. Ask whether they already tried and whether they are on the host machine.

140 -2. If the OS is unknown, ask whether they are in macOS/Linux shell or Windows PowerShell.

141 -3. Give the matching installer command.

142 -4. Tell them to run `a0`.

143 -5. Explain what the host picker and successful connection should look like.

59 + ```bash

60 + uv tool install --upgrade git+https://github.com/agent0ai/a0-connector

61 + ```

62

145 -### Example 2

63 +- A connector `404` usually means the running Agent Zero build lacks the bundled `_a0_connector`; tell the user to update Agent Zero.

64 +- If discovery fails, ask for the exact Agent Zero URL or suggest a Flare Tunnel only then. The Flare Tunnel flow is `Settings > External Services > Flare Tunnel` → `Create Tunnel` → paste the shown HTTPS URL into `a0`.

65

147 -User: "I'm inside the Agent Zero container. How do I install A0?"

66 +## Response Examples

67

149 -Respond like this:

68 +User: "How to enable host connector"

69

151 -- Stop the flow.

152 -- Explain that `a0` must be installed on the host, not in the container.

153 -- Tell them to exit Docker, open a normal terminal on the machine, then continue with the host installer.

70 +> Which computer are you installing it on: Windows, macOS, or Linux?

71

155 -### Example 3

72 +User: "Linux"

73

157 -User: "The raw GitHub installer URL is blocked on our network."

74 +> Run this in your normal Linux terminal, then run `a0` and select the Agent Zero instance it finds.

75 +>

76 +> ```bash

77 +> curl -LsSf https://raw.githubusercontent.com/agent0ai/a0-connector/main/install.sh | sh

78 +> ```

79

159 -Respond like this:

80 +User: "It asks for a custom URL"

81

161 -- Say the public installer URL is only a placeholder path.

162 -- Switch to a manual `uv tool install --upgrade <package-spec>` flow.

163 -- Offer examples for a local checkout, internal Git host, or the public Git URL if that one works.

164 -- Then tell them to run `a0` and connect to Agent Zero.

82 +> Paste the exact URL you currently use to open Agent Zero in your browser, including its port.

Refine A0 CLI setup guidance