docs(hub): document zero-friction onboarding (#3657)
Lead with the browser-to-CLI onboarding journey, document the generated starter bundle, and align guided setup with available Hub connections and daemon-reported runtime defaults.
This commit is contained in:
Mohamed Boudra
@@ -8,7 +8,7 @@ category: Hub
|
||||
|
||||
# Hub quickstart
|
||||
|
||||
Run Hub locally, connect it to Slack without a public server, and answer a mention with an agent on your machine.
|
||||
Run Hub on your machine, connect it to Slack without a public server, and answer a mention with an agent in your repository. Hub's browser setup hands off to your terminal, and guided setup writes and deploys the workflow for you.
|
||||
|
||||
You need [Paseo installed and running](/docs), Node.js, and a Slack workspace where you can create an app.
|
||||
|
||||
@@ -18,13 +18,13 @@ You need [Paseo installed and running](/docs), Node.js, and a Slack workspace wh
|
||||
npx @getpaseo/hub
|
||||
```
|
||||
|
||||
Open <http://localhost:3000>. Hub uses an embedded database by default, so this first run needs no database, environment variables, or Docker.
|
||||
Open the address it prints, normally <http://localhost:3000>, and create the operator account Hub asks for.
|
||||
|
||||
Create the operator account when Hub welcomes you.
|
||||
The first run needs no database, Docker, environment variables, or API keys. Hub creates an embedded database, your organization, and a **Default** project. You never create a project by hand.
|
||||
|
||||
## 2. Connect Slack
|
||||
|
||||
The next screen explains how to create the Slack app and gives you a manifest to paste into Slack. Keep **Socket Mode** selected. It connects out from Hub and does not need a public address or HTTPS.
|
||||
**Set up your apps** explains how to create the Slack app and gives you a manifest to paste into Slack. Keep **Socket Mode** selected. It connects out from Hub and needs no public address or HTTPS.
|
||||
|
||||
Paste the App-level token and Bot token back into Hub, then choose **Connect Slack**. Invite the bot to the channel where you will use it:
|
||||
|
||||
@@ -32,35 +32,63 @@ Paste the App-level token and Bot token back into Hub, then choose **Connect Sla
|
||||
/invite @Paseo
|
||||
```
|
||||
|
||||
You can skip GitHub and Discord for now. Their setup remains available under **Apps**.
|
||||
GitHub and Discord can wait. Their setup stays available under **Apps**.
|
||||
|
||||
## 3. Initialize the project
|
||||
## 3. Connect the machine your code is on
|
||||
|
||||
From the repository where the agent should work:
|
||||
**Connect a daemon** shows one command with this Hub's address already in it:
|
||||
|
||||
```sh
|
||||
paseo hub init
|
||||
paseo hub login http://localhost:3000
|
||||
```
|
||||
|
||||
Choose **Custom endpoint…** and enter `http://localhost:3000`, then choose Slack. The guided setup:
|
||||
Run it on the machine where your code lives, in the repository the agent should work in. Guided setup records that directory as the workflow's working directory.
|
||||
|
||||
- signs you in through the browser;
|
||||
- connects the local Paseo daemon;
|
||||
- uses the default project created during first-run setup;
|
||||
- selects the connected Slack workspace and asks for your Slack username;
|
||||
- writes `.paseo/hub.yml` and `.paseo/workflows/slack-help.yml`;
|
||||
- validates the generated bundle and offers to deploy it.
|
||||
Approve the login in the browser tab that opens. Leave the Hub tab open: it watches for the daemon and shows **Daemon connected** by itself. **Continue** and **Do this later** both land in the Default project.
|
||||
|
||||
Accept the default **Deploy now?** choice. The generated workflow accepts mentions only from the username you entered.
|
||||
## 4. Answer the setup questions
|
||||
|
||||
## 4. Mention the bot
|
||||
Your terminal confirms the login, then picks up where the browser left off. Most questions arrive with a default or a suggested answer; only your Slack member ID has to be typed.
|
||||
|
||||
Mention the bot in the channel:
|
||||
| Question | What it wants |
|
||||
| ----------------------------------------- | --------------------------------------------------------------------------------------- |
|
||||
| Connect this daemon to this Hub? | Yes. This enrolls the machine you are on. |
|
||||
| Initialize and deploy a starter workflow? | Yes. |
|
||||
| Starter agent provider, model, and mode | What your daemon reports it can run. Suggested model and mode entries are its defaults. |
|
||||
| Your Slack member ID | `U01234567`, the only account allowed to trigger the bot. |
|
||||
|
||||
Setup lists the app connections ready for this workflow. Because you connected one Slack workspace in step 2, it selects that connection automatically instead of asking you to choose Slack. If several usable connections exist, setup asks for the **Trigger connection**. If none is ready, it sends you to **Hub → Apps** and stops before asking about the agent or writing files.
|
||||
|
||||
The agent provider list contains only runtimes the daemon can use; it does not suggest one arbitrarily. Suggested model and mode entries are defaults reported by the daemon. A provider that has modes but no default mode is still offered; setup asks you to pick the mode instead of guessing one.
|
||||
|
||||
[Find your Slack IDs](/docs/hub/triggers/slack#find-your-slack-ids) has the two clicks that copy your member ID. The Slack workspace comes from the app you connected in step 2, so setup does not ask for it.
|
||||
|
||||
Setup then validates the bundle, writes it, and deploys:
|
||||
|
||||
```text
|
||||
@Paseo explain what this project does
|
||||
.paseo/
|
||||
├── hub.yml
|
||||
└── workflows/
|
||||
└── slack-help.yml
|
||||
```
|
||||
|
||||
Hub starts the agent on your daemon and posts its reply in the Slack thread. Open the project's **Activity** tab if nothing runs.
|
||||
If `.paseo/` already exists, setup asks before replacing it. Declining the daemon connection prints `paseo hub connect <hub>; then paseo hub init` — both commands, because connecting alone does not create the workflow. Declining only the starter workflow prints `paseo hub init`.
|
||||
|
||||
Hub keeps its local state in your user data directory (normally `~/.local/share/paseo-hub`). [Self-hosting](/docs/hub/self-hosting) covers PostgreSQL, public URLs, environment-managed apps, Docker, and cloud deployment. [Configuration](/docs/hub/configuration) explains the generated files and manual deployment.
|
||||
## 5. Mention the bot
|
||||
|
||||
In the channel you invited the bot to:
|
||||
|
||||
```text
|
||||
@Paseo have a look
|
||||
```
|
||||
|
||||
Hub starts the agent on your daemon and posts its reply in the Slack thread. The terminal prints the project's Activity URL, where the run appears. If nothing runs, [Activity](/docs/hub/activity) tells a filtered mention from one that never matched a workflow.
|
||||
|
||||
## Next
|
||||
|
||||
- [How Hub works](/docs/hub/concepts) — how an event becomes a workflow run on your daemon.
|
||||
- [Generated starter bundle](/docs/hub/configuration#generated-starter-bundle) — the two files setup wrote, field by field.
|
||||
- [Workflows](/docs/hub/workflows) — routing, prompts, and provider replies.
|
||||
- [Hub security](/docs/hub/security) — read this before widening `from_users` or giving an agent GitHub authority.
|
||||
|
||||
Hub keeps its local state in your user data directory, normally `~/.local/share/paseo-hub`. [Self-hosting](/docs/hub/self-hosting) covers deployment and advanced configuration when you outgrow the local run.
|
||||
|
||||
Reference in New Issue
Block a user