mirror of
https://github.com/getpaseo/paseo.git
synced 2026-10-14 13:22:37 +00:00
Initialize Hub with organization triggers (#4517)
* fix(cli): initialize current Hub triggers Hub init still authored and deployed project bundles after hosted configuration moved to organization triggers. Generate the self-contained trigger contract and keep project bundle deployment behind the existing --project path. * fix(cli): harden Hub trigger setup * docs(hub): align public setup guides with organization triggers
This commit is contained in:
Mohamed Boudra
+10
-9
@@ -293,25 +293,26 @@ Use `PASEO_HOME` to run multiple isolated daemon instances.
|
||||
|
||||
```bash
|
||||
paseo hub login [url] # Approve and store organization-scoped CLI access
|
||||
paseo hub init # Guided setup: scaffold and deploy a starter bundle here
|
||||
paseo hub init # Create and optionally deploy a starter trigger here
|
||||
paseo hub connect [url] # Enroll this daemon using CLI access
|
||||
paseo hub projects # List projects in the authenticated organization
|
||||
paseo hub projects # List legacy projects in the authenticated organization
|
||||
paseo hub status # Show the current Hub relationship
|
||||
paseo hub disconnect # End it
|
||||
paseo hub deploy -p <project> # Discover, validate, and activate a Hub bundle
|
||||
paseo hub deploy -p <project> --dry-run # Validate without activating
|
||||
paseo hub deploy # Validate and install .paseo/triggers/*.yml
|
||||
paseo hub deploy --dry-run # Validate without installing
|
||||
paseo hub deploy -p <project> # Deploy an existing legacy project bundle
|
||||
paseo hub logout # Remove the active stored CLI login
|
||||
```
|
||||
|
||||
Run deploy from the project root. It reads `.paseo/hub.yml`, every direct `.paseo/workflows/*.yml` file, and referenced `.paseo/workflows/partials/*` files in deterministic path order. It does not search parents, accept an alternate resource path, or flatten the bundle into monolithic YAML.
|
||||
Run deploy from the repository root. By default it reads every direct `.paseo/triggers/*.yml` file in deterministic path order. It validates all triggers before installing them one at a time. If an installation fails after earlier ones succeeded, the error lists the installed files. `--dry-run` only validates; it does not create or activate revisions.
|
||||
|
||||
Pass `-p, --project <slug>` to select the target project. `--dry-run` performs the same discovery and server validation without recording or activating a revision. Both outputs include the resolved Hub, project, and discovered workflow count.
|
||||
Pass `-p, --project <slug>` for an existing legacy bundle: `.paseo/hub.yml`, direct `.paseo/workflows/*.yml` files, and referenced workflow partials. See [Deploy from the CLI](/docs/hub/configuration#deploy-from-the-cli).
|
||||
|
||||
`login` opens the Hub approval page and stores a durable organization-scoped CLI credential under `PASEO_HOME`. In an interactive terminal it then asks whether to connect this daemon and whether to initialize and deploy a starter workflow, both defaulting to yes. Declining the connection prints `paseo hub connect <origin>; then paseo hub init`, because the connection alone does not produce a bundle; declining only the starter prints `paseo hub init`. `--json` and non-TTY login remain login-only and never prompt. The stored login is separate from the daemon relationship created by `connect`.
|
||||
`login` opens the Hub approval page and stores a durable organization-scoped CLI credential under `PASEO_HOME`. In an interactive terminal it offers to connect this daemon, then separately asks whether to allow Hub automations to run agents. Connection defaults to yes; execution permission defaults to no. It then links to Hub's **Triggers** page and prints `paseo hub init` for setup as code. `--json` and non-TTY login remain login-only and never prompt. The stored login is separate from the daemon relationship created by `connect`.
|
||||
|
||||
`init` runs the same guided setup on its own and requires a TTY. It connects the daemon, uses the organization's only project or asks which one, and lists the Hub app connections that can back a starter workflow. One usable connection is selected automatically; with several, you choose a **Trigger connection**. If none is ready, setup sends you to **Hub → Apps** and stops before selecting an agent or writing files.
|
||||
`init` requires a TTY. It signs in and connects the daemon as needed, then lists the organization's app connections that can back a starter trigger. One usable connection is selected automatically; with several, you choose a **Trigger connection**. If none is ready, setup sends you to **Hub → Apps** and stops before selecting an agent or writing files.
|
||||
|
||||
Setup then asks which agent provider, model, and mode the starter should run, choosing from what the connected daemon reports. A provider is offered only when the daemon has it enabled with a selectable model. Suggested model and mode entries are the daemon's defaults; no provider is suggested merely because it appears first. The mode question is skipped for providers that expose no modes and asked explicitly when the daemon has modes but no default. Finally, setup asks for the identity that gates the chosen connection: a GitHub username, a Slack member ID, or a Discord user ID. It writes `.paseo/hub.yml` and `.paseo/workflows/<provider>-help.yml`, validates them against Hub, and deploys. An existing `.paseo/` directory is replaced only after you confirm. See the [generated starter bundle](/docs/hub/configuration#generated-starter-bundle).
|
||||
Setup asks which agent provider, model, and mode to run. Providers must be enabled and expose both a selectable model and an execution mode. Suggested model and mode entries are the daemon's defaults; a mode is still selected explicitly when there is no default. Setup then asks for the identity allowed to trigger the bot: a GitHub username, Slack member ID, or Discord user ID. It validates the trigger, writes `.paseo/triggers/<provider>-help.yml`, and asks whether to deploy. Replacing that file requires confirmation; existing legacy bundles and other trigger files are preserved. See the [generated starter trigger](/docs/hub/configuration#generated-starter-trigger).
|
||||
|
||||
Interactive logout checks the same-origin daemon relationship and asks whether to disconnect before deleting the login. Declining removes only the login. JSON and noninteractive logout never prompt or disconnect implicitly; `--disconnect-daemon` is the explicit automation path, and `--force` applies to that daemon disconnection. If a requested disconnection fails, the login is preserved.
|
||||
|
||||
|
||||
+41
-13
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Hub public API
|
||||
description: Use organization credentials to list projects, validate or install configuration, dispatch runs, and enroll daemons.
|
||||
description: Use organization credentials to install triggers, manage legacy configuration, dispatch runs, and enroll daemons.
|
||||
nav: Public API
|
||||
order: 79
|
||||
category: Hub
|
||||
@@ -8,7 +8,7 @@ category: Hub
|
||||
|
||||
# Hub public API
|
||||
|
||||
The Hub public API lets automation operate on projects and daemons in one
|
||||
The Hub public API lets automation operate on triggers, projects, and daemons in one
|
||||
organization. Set the Hub origin in `PASEO_HUB_URL` below, for example
|
||||
`https://hub.example.com`.
|
||||
|
||||
@@ -37,13 +37,13 @@ organization is not accessible through the key.
|
||||
|
||||
Each key has one or more selectable scopes:
|
||||
|
||||
| Scope | Operation |
|
||||
| ------------------------ | --------------------------------------------------- |
|
||||
| `projects:read` | List active projects in the organization. |
|
||||
| `configuration:validate` | Validate configuration without changing Hub state. |
|
||||
| `configuration:install` | Replace and activate a project's configuration. |
|
||||
| `runs:dispatch` | Dispatch a configured manual trigger for a project. |
|
||||
| `daemons:enroll` | Issue a short-lived daemon enrollment token. |
|
||||
| Scope | Operation |
|
||||
| ------------------------ | --------------------------------------------------------------------- |
|
||||
| `projects:read` | List active projects in the organization. |
|
||||
| `configuration:validate` | Validate triggers or legacy configuration without changing Hub state. |
|
||||
| `configuration:install` | Install triggers or replace a legacy project's configuration. |
|
||||
| `runs:dispatch` | Dispatch a configured manual trigger for a project. |
|
||||
| `daemons:enroll` | Issue a short-lived daemon enrollment token. |
|
||||
|
||||
API keys do not grant dashboard access. They cannot manage connections,
|
||||
projects, or organization members.
|
||||
@@ -65,6 +65,34 @@ API failures use RFC 9457 problem details. Missing, invalid, or revoked credenti
|
||||
|
||||
A valid key without the scope required by an endpoint returns `403` in the same format.
|
||||
|
||||
## Trigger validation and installation
|
||||
|
||||
`paseo hub deploy --dry-run` validates each `.paseo/triggers/*.yml` file through `POST /api/v1/triggers/validate`. `paseo hub deploy` validates all files first, then installs each through `POST /api/v1/triggers/install`.
|
||||
|
||||
Both endpoints accept one self-contained document:
|
||||
|
||||
```json
|
||||
{
|
||||
"yaml": "name: manual-task\nenabled: true\non:\n manual.run: {}\nrun:\n target: { daemon: my-macbook, cwd: /workspace }\n agent: { provider: codex, model: gpt-5, mode: full-access }\n prompt: Complete the task and call hub.finish_execution.\n max_runtime: 1h\n idle_timeout: 5m\n"
|
||||
}
|
||||
```
|
||||
|
||||
Use a daemon slug and agent runtime available in your organization. Validation requires `configuration:validate` and returns `200` with `{ "name": "manual-task", "valid": true }`.
|
||||
|
||||
Installation requires `configuration:install`. It creates or updates the organization's trigger by the YAML `name` and returns `201`:
|
||||
|
||||
```json
|
||||
{
|
||||
"triggerId": "00000000-0000-4000-8000-000000000001",
|
||||
"name": "manual-task",
|
||||
"revisionId": "00000000-0000-4000-8000-000000000002",
|
||||
"version": 1,
|
||||
"active": true
|
||||
}
|
||||
```
|
||||
|
||||
Invalid YAML or an unknown organization resource returns `422` with field issues. Each installation is a separate request; a later failure does not undo earlier successful installs. See [Deploy from the CLI](/docs/hub/configuration#deploy-from-the-cli).
|
||||
|
||||
## Project list
|
||||
|
||||
`GET /api/v1/projects` returns active projects in the bearer credential's organization. `paseo hub projects` renders the projects as a table. With `--json`, it returns `{ "origin": "...", "projects": [...] }` so even an empty result records the resolved Hub.
|
||||
@@ -81,7 +109,7 @@ A valid key without the scope required by an endpoint returns `403` in the same
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration validation
|
||||
## Legacy configuration validation
|
||||
|
||||
`POST /api/v1/configurations/validate` accepts the same `projectSlug` and complete `files` bundle as configuration install. It performs the same compilation and resource resolution without recording a revision or changing the active configuration.
|
||||
|
||||
@@ -94,9 +122,9 @@ On success, Hub returns `200`:
|
||||
}
|
||||
```
|
||||
|
||||
`paseo hub deploy --dry-run` calls this endpoint with the identical locally resolved payload that a deployment would send.
|
||||
`paseo hub deploy --project <slug> --dry-run` calls this endpoint with the identical locally resolved payload that a deployment would send.
|
||||
|
||||
## Configuration install
|
||||
## Legacy configuration install
|
||||
|
||||
`configuration:install` validates the supplied canonical bundle, stores the exact authored files, and activates a new revision.
|
||||
|
||||
@@ -157,7 +185,7 @@ curl --fail-with-body -sS -X POST "$PASEO_HUB_URL/api/v1/configurations/install"
|
||||
--data @configuration-install.json
|
||||
```
|
||||
|
||||
`paseo hub deploy -p <project>` calls this endpoint with the discovered local bundle. The command uses an exact-origin stored login when flags and environment credentials are absent. See [Deploy from the CLI](/docs/hub/configuration#deploy-from-the-cli).
|
||||
`paseo hub deploy -p <project>` selects this legacy endpoint with the discovered local bundle. The command uses an exact-origin stored login when flags and environment credentials are absent. See [Deploy from the CLI](/docs/hub/configuration#deploy-from-the-cli).
|
||||
|
||||
## Manual run dispatch
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
title: Hub configuration
|
||||
description: Configuration bundles, GitHub sync, CLI deployment, and revisions.
|
||||
description: Generate, edit, and deploy organization triggers from your repository.
|
||||
nav: Configuration
|
||||
order: 70
|
||||
category: Hub
|
||||
@@ -8,98 +8,75 @@ category: Hub
|
||||
|
||||
# Hub configuration
|
||||
|
||||
A project configuration is one versioned bundle:
|
||||
Each organization trigger is one self-contained YAML file. Keep triggers in your repository and deploy them with `paseo hub deploy`:
|
||||
|
||||
```text
|
||||
.paseo/
|
||||
├── hub.yml
|
||||
└── workflows/
|
||||
├── <workflow>.yml
|
||||
└── partials/
|
||||
└── <partial>.md
|
||||
└── triggers/
|
||||
└── <trigger>.yml
|
||||
```
|
||||
|
||||
`hub.yml` owns named environments and agents. Each direct-child workflow file owns one trigger and its ordered inline steps. Prompt partials referenced by those workflows live below `workflows/partials/`. Workflow discovery is fixed by convention; there is no manifest or include list.
|
||||
## Generated starter trigger
|
||||
|
||||
[single-repo-team-bot](https://github.com/getpaseo/hub/tree/main/examples/single-repo-team-bot) is a complete bundle in this shape: Discord, Slack, and GitHub workflows running a classifier and a worker on shared partials. Copy `.paseo/` into your repository and replace the placeholders its README lists.
|
||||
Run `paseo hub init` from the repository the agent should work in. Setup selects an app connection and an available agent runtime, asks which user may trigger it, validates the result, and writes one file. It then asks whether to deploy. Interactive `paseo hub login` connects the daemon and points to this command; it does not write trigger files.
|
||||
|
||||
## Generated starter bundle
|
||||
|
||||
`paseo hub init`, and the guided setup that interactive `paseo hub login` offers, write two files for the directory you run them in:
|
||||
For a Slack connection named `my-team`, the generated document looks like this:
|
||||
|
||||
```yaml
|
||||
# .paseo/hub.yml
|
||||
environments:
|
||||
my-macbook:
|
||||
kind: daemon
|
||||
# .paseo/triggers/slack-help.yml
|
||||
name: slack-help
|
||||
enabled: true
|
||||
on:
|
||||
slack.mention:
|
||||
connection: my-team
|
||||
filters:
|
||||
from_users: [U01234567]
|
||||
max_runtime: 2h
|
||||
run:
|
||||
target:
|
||||
daemon: my-macbook
|
||||
cwd: /Users/you/code/your-repo
|
||||
agents:
|
||||
starter:
|
||||
agent:
|
||||
provider: codex
|
||||
model: gpt-5
|
||||
mode: full-access
|
||||
continuation:
|
||||
mode: conversation
|
||||
max_runtime: 90m
|
||||
idle_timeout: 10m
|
||||
prompt: |
|
||||
Answer with hub.reply, then complete this request and call hub.finish_execution when done.
|
||||
|
||||
<user-prompt>
|
||||
${{ paseo.prompt }}
|
||||
</user-prompt>
|
||||
outputs:
|
||||
slack.reply:
|
||||
max: 1
|
||||
required: true
|
||||
```
|
||||
|
||||
The environment is named after the connected daemon and points at the directory setup ran in. `provider`, `model`, and `mode` are the runtime you chose from what that daemon reported, so the starter agent is a complete selection before its first run. `mode` is omitted for a provider that exposes none.
|
||||
`connection` is the app connection's slug in your organization. `target.daemon` is the connected daemon's slug and `target.cwd` is the absolute directory where you ran setup. `agent` contains the provider, model, and execution mode you selected from the daemon. The mode is required.
|
||||
|
||||
```yaml
|
||||
# .paseo/workflows/slack-help.yml
|
||||
name: slack-help
|
||||
on: slack.mention
|
||||
max_runtime: 2h
|
||||
filters:
|
||||
workspace: T01234567
|
||||
from_users:
|
||||
- U01234567
|
||||
steps:
|
||||
- id: work
|
||||
environment: my-macbook
|
||||
max_runtime: 90m
|
||||
idle_timeout: 10m
|
||||
agent: starter
|
||||
prompt:
|
||||
- text: |
|
||||
Answer with hub.reply, then complete this request and call hub.finish_execution when done.
|
||||
`continuation.mode: conversation` keeps follow-ups in the same provider conversation on the same agent. The prompt asks the agent to reply and then call `hub.finish_execution`; replying alone does not finish the execution.
|
||||
|
||||
<user-prompt>
|
||||
${{ paseo.prompt }}
|
||||
</user-prompt>
|
||||
allow_outputs:
|
||||
- type: slack.reply
|
||||
max: 1
|
||||
required: true
|
||||
```
|
||||
A Discord starter uses `discord.mention`, your Discord user ID, and `discord.reply`. A GitHub starter uses `github.issue_comment`, restricts the repository to the current GitHub remote, and requires both `@paseo` and your GitHub username. GitHub's starter has no explicit reply output declaration.
|
||||
|
||||
`filters` carries the identity each provider matches on: the Slack team and member ID above, the Discord guild and user ID for a Discord starter, and `owner/name` plus your login for GitHub.
|
||||
|
||||
A Discord starter is `discord-help.yml` and carries `discord.reply`, the counterpart of the `slack.reply` above. A GitHub starter is `github-help.yml` and declares no reply output; GitHub has no reply capability, so a step that must comment needs a [`github` block](/docs/hub/github) instead.
|
||||
|
||||
The generated workflow allows one user in one workspace. Read [Hub security](/docs/hub/security) before widening it.
|
||||
|
||||
## Sources
|
||||
|
||||
A configuration comes from one source:
|
||||
|
||||
- **GitHub source**: the complete `.paseo` bundle on the repository's default branch.
|
||||
- **Manual source**: source files edited and activated in the dashboard.
|
||||
- **CLI/API install**: a complete bundle sent with organization authority.
|
||||
|
||||
The **Configuration** tab shows the active revision, source files, and latest synchronization attempt.
|
||||
Setup asks before replacing the selected trigger file. It preserves other triggers and any existing legacy bundle. Read [Hub security](/docs/hub/security) before widening `from_users` or the agent's authority.
|
||||
|
||||
## Deploy from the CLI
|
||||
|
||||
Run from the project root:
|
||||
Run from the repository root:
|
||||
|
||||
```sh
|
||||
paseo hub login https://hub.example.com
|
||||
paseo hub deploy -p my-project --dry-run
|
||||
paseo hub deploy -p my-project
|
||||
paseo hub deploy --dry-run
|
||||
paseo hub deploy
|
||||
```
|
||||
|
||||
Both commands discover `.paseo/hub.yml`, every direct `.paseo/workflows/*.yml` file, and each referenced file below `.paseo/workflows/partials/`. Files are sent in deterministic path order through the same bundle request. Dry-run calls server-side validation and does not create or activate a revision.
|
||||
Both deploy commands discover direct `.paseo/triggers/*.yml` files in deterministic path order. The CLI rejects nested files, `.yaml` extensions, symlinked trigger paths, and unreadable files. It does not search parent directories.
|
||||
|
||||
The CLI rejects missing resource or workflow files, `.yaml` workflow extensions, nested workflow files, unsafe partial paths, symlinked bundle paths, and unreadable files before contacting Hub. Errors name paths but never print file contents or credentials.
|
||||
Dry-run validates each document against Hub without storing a revision. Deployment validates all documents first, then installs them one at a time through the organization trigger API. Installation creates or updates a trigger by its YAML `name`. If a later install fails, the error lists the files already installed; those revisions remain active. Errors name paths without printing file contents or credentials.
|
||||
|
||||
Origin precedence:
|
||||
|
||||
@@ -116,6 +93,21 @@ Credential precedence:
|
||||
|
||||
Flags and environment keys are not stored. Endpoint and credential behavior is unchanged between deploy and dry-run.
|
||||
|
||||
## Legacy project bundles
|
||||
|
||||
Existing project bundles use `.paseo/hub.yml`, direct `.paseo/workflows/*.yml` files, and referenced files below `.paseo/workflows/partials/`. `hub.yml` owns named environments and agents; each workflow owns its trigger and ordered steps.
|
||||
|
||||
Select the legacy deployment path explicitly:
|
||||
|
||||
```sh
|
||||
paseo hub deploy --project my-project --dry-run
|
||||
paseo hub deploy --project my-project
|
||||
```
|
||||
|
||||
These commands send the complete bundle through the project configuration API. Dry-run validates without recording or activating a revision. `paseo hub init` does not create or migrate these bundles.
|
||||
|
||||
The following source and revision behavior applies to legacy project bundles.
|
||||
|
||||
## GitHub sync
|
||||
|
||||
A push to the configuration repository's default branch starts a sync:
|
||||
|
||||
@@ -8,7 +8,7 @@ category: Hub
|
||||
|
||||
# Daemons in Hub
|
||||
|
||||
A daemon is one of your machines running the Paseo daemon. Enroll it once with your Hub organization, then any project can reference it.
|
||||
A daemon is one of your machines running the Paseo daemon. Enroll it once with your Hub organization, then triggers can reference it.
|
||||
|
||||
## Connect
|
||||
|
||||
@@ -20,7 +20,7 @@ paseo hub login https://hub.example.com
|
||||
|
||||
The CLI prints a URL and a verification code and opens your browser. The approved login is stored under `PASEO_HOME`.
|
||||
|
||||
In an interactive terminal, login then offers to finish setup: whether to connect this daemon, and whether to initialize and deploy a starter workflow. Both default to yes. Declining the connection prints `paseo hub connect <origin>; then paseo hub init`, since connecting alone leaves the project without a workflow. Declining only the starter prints `paseo hub init`. `--json` or non-TTY login only logs in. [Quickstart](/docs/hub/quickstart) walks through the questions.
|
||||
In an interactive terminal, login offers to connect this daemon and separately asks whether to allow Hub automations to run agents. Connection defaults to yes; execution permission defaults to no. It then links to **Triggers** and prints `paseo hub init` for creating a starter trigger as code. `--json` or non-TTY login only logs in. [Quickstart](/docs/hub/quickstart) walks through connection and initialization.
|
||||
|
||||
Enroll the daemon on its own when you declined, or when the machine is already logged in:
|
||||
|
||||
|
||||
@@ -20,7 +20,7 @@ A daemon runs agents on one machine, for you. Paseo Hub is the layer above your
|
||||
What that gives you today:
|
||||
|
||||
- Agents that start on their own, from activity in GitHub, Slack, and Discord.
|
||||
- Configuration that lives in a repository and deploys when you push.
|
||||
- Triggers you can keep in a repository and deploy from the CLI.
|
||||
- A record of everything that arrived, what it matched, and what ran.
|
||||
- One place for your team to see all of it.
|
||||
|
||||
@@ -28,16 +28,15 @@ Your daemons keep running agents where they always did. Hub decides when to ask
|
||||
|
||||
## What lives in your repository
|
||||
|
||||
Guided setup creates a project resource file for environments and agents, plus one safe starter workflow:
|
||||
`paseo hub init` creates one self-contained starter trigger:
|
||||
|
||||
```text
|
||||
.paseo/
|
||||
├── hub.yml
|
||||
└── workflows/
|
||||
└── triggers/
|
||||
└── slack-help.yml
|
||||
```
|
||||
|
||||
Guided setup deploys the bundle, and mentioning the bot starts an agent on your machine. [Quickstart](/docs/hub/quickstart) runs it end to end; the [generated starter bundle](/docs/hub/configuration#generated-starter-bundle) shows what it wrote, and [Workflows](/docs/hub/workflows) covers routing, prompt partials, and provider-specific replies.
|
||||
The file names the app connection, allowed user, daemon, working directory, agent runtime, prompt, and outputs. Setup validates it and asks whether to deploy. Mentioning the bot then starts an agent on your machine. [Quickstart](/docs/hub/quickstart) runs it end to end; the [generated starter trigger](/docs/hub/configuration#generated-starter-trigger) shows what setup wrote.
|
||||
|
||||
## Reading order
|
||||
|
||||
@@ -56,4 +55,4 @@ If a workflow accepts requests from GitHub, Slack, Discord, or the API, read [Hu
|
||||
|
||||
Start on your machine with the embedded database, then add PostgreSQL or a public deployment only when you need them. [Self-hosting](/docs/hub/self-hosting) covers each step.
|
||||
|
||||
[Hosted Hub](/docs/hub/hosted) uses the same projects, workflows, daemons, and activity model. [Sign in to start a free trial](https://hub.paseo.sh).
|
||||
[Hosted Hub](/docs/hub/hosted) uses the same triggers, daemons, and activity model. [Sign in to start a free trial](https://hub.paseo.sh).
|
||||
|
||||
@@ -8,7 +8,7 @@ category: Hub
|
||||
|
||||
# Hub quickstart
|
||||
|
||||
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.
|
||||
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 `paseo hub init` writes and deploys a starter trigger for you.
|
||||
|
||||
You need [Paseo installed and running](/docs), Node.js, and a Slack workspace where you can create an app.
|
||||
|
||||
@@ -20,7 +20,7 @@ npx @getpaseo/hub
|
||||
|
||||
Open the address it prints, normally <http://localhost:3000>, and create the operator account Hub asks for.
|
||||
|
||||
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.
|
||||
The first run needs no database, Docker, environment variables, or API keys. Hub creates an embedded database and your organization.
|
||||
|
||||
## 2. Connect Slack
|
||||
|
||||
@@ -42,37 +42,39 @@ GitHub and Discord can wait. Their setup stays available under **Apps**.
|
||||
paseo hub login http://localhost:3000
|
||||
```
|
||||
|
||||
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.
|
||||
Run it on the machine where your code lives, in the repository the agent should work in. Run the initializer below from that directory so it becomes the trigger's working directory.
|
||||
|
||||
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.
|
||||
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. Choose **Continue** when the daemon is connected.
|
||||
|
||||
## 4. Answer the setup questions
|
||||
## 4. Create the starter trigger
|
||||
|
||||
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.
|
||||
After approving login, answer **Yes** to **Connect this daemon to Paseo Hub?** and **Allow Hub automations to run agents on this daemon?**. Execution permission defaults to no, so enable it explicitly for this setup.
|
||||
|
||||
| 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. |
|
||||
Then run:
|
||||
|
||||
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.
|
||||
```sh
|
||||
paseo hub init
|
||||
```
|
||||
|
||||
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.
|
||||
Choose **Custom endpoint** and confirm `http://localhost:3000`. Setup reuses your login and daemon connection, then lists the app connections ready for this trigger. With one Slack workspace connected, it selects that connection automatically. With several usable connections, choose the **Trigger connection**. If none is ready, setup sends you to **Hub → Apps** and stops before selecting an agent or writing files.
|
||||
|
||||
[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.
|
||||
| Question | What it wants |
|
||||
| --------------------------------------- | -------------------------------------------------------------------------------------- |
|
||||
| Starter agent provider, model, and mode | A runtime available on your daemon. Suggested model and mode entries are its defaults. |
|
||||
| Your Slack member ID | `U01234567`, the only account allowed to trigger the bot. |
|
||||
| Deploy now? | Yes, to activate this trigger in Hub. |
|
||||
|
||||
Setup then validates the bundle, writes it, and deploys:
|
||||
Providers must expose a selectable model and execution mode. If there is no default mode, choose the one the agent should use. [Find your Slack IDs](/docs/hub/triggers/slack#find-your-slack-ids) explains how to copy your member ID. The Slack workspace comes from the selected app connection.
|
||||
|
||||
Setup validates the trigger and writes:
|
||||
|
||||
```text
|
||||
.paseo/
|
||||
├── hub.yml
|
||||
└── workflows/
|
||||
└── triggers/
|
||||
└── slack-help.yml
|
||||
```
|
||||
|
||||
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`.
|
||||
If `slack-help.yml` already exists, setup asks before replacing that file. Other files remain in place. If you decline deployment, run `paseo hub deploy` from this repository when ready.
|
||||
|
||||
## 5. Mention the bot
|
||||
|
||||
@@ -82,12 +84,12 @@ In the channel you invited the bot to:
|
||||
@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.
|
||||
Hub starts the agent on your daemon and posts its reply in the Slack thread. The terminal links to **Triggers**, where you can manage the trigger and inspect its runs. If nothing runs, [Activity](/docs/hub/activity) tells a filtered mention from one that never matched a trigger.
|
||||
|
||||
## 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.
|
||||
- [Generated starter trigger](/docs/hub/configuration#generated-starter-trigger) — the file 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.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user