@rizom/ops 0.2.0-alpha.1 → 0.2.0-alpha.100
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +9 -2
- package/dist/age-key-bootstrap.d.ts +17 -0
- package/dist/brains-ops.js +279 -150
- package/dist/cert-bootstrap.d.ts +22 -0
- package/dist/content-repo.d.ts +13 -0
- package/dist/default-user-runner.d.ts +1 -1
- package/dist/deploy.js +3 -170
- package/dist/entries/deploy.d.ts +2 -2
- package/dist/index.d.ts +7 -0
- package/dist/index.js +279 -150
- package/dist/load-registry.d.ts +22 -3
- package/dist/observed-status.d.ts +12 -0
- package/dist/onboard-user.d.ts +2 -2
- package/dist/origin-ca.d.ts +1 -0
- package/dist/parse-args.d.ts +4 -0
- package/dist/push-secrets.d.ts +9 -0
- package/dist/push-target.d.ts +2 -0
- package/dist/reconcile-all.d.ts +2 -2
- package/dist/reconcile-cohort.d.ts +2 -2
- package/dist/reconcile-lib.d.ts +4 -2
- package/dist/run-command.d.ts +10 -0
- package/dist/run-subprocess.d.ts +6 -0
- package/dist/schema.d.ts +113 -6
- package/dist/secrets-encrypt.d.ts +29 -0
- package/dist/secrets-push.d.ts +13 -0
- package/dist/ssh-key-bootstrap.d.ts +26 -0
- package/dist/user-add.d.ts +15 -0
- package/dist/user-runner.d.ts +5 -0
- package/dist/verify-user.d.ts +19 -0
- package/package.json +7 -3
- package/templates/rover-pilot/.env.schema +16 -2
- package/templates/rover-pilot/.github/workflows/build.yml +14 -5
- package/templates/rover-pilot/.github/workflows/deploy.yml +80 -20
- package/templates/rover-pilot/.github/workflows/reconcile.yml +16 -2
- package/templates/rover-pilot/README.md +8 -2
- package/templates/rover-pilot/deploy/scripts/decrypt-user-secrets.ts +78 -0
- package/templates/rover-pilot/deploy/scripts/provision-server.ts +1 -1
- package/templates/rover-pilot/deploy/scripts/resolve-deploy-handles.ts +15 -4
- package/templates/rover-pilot/deploy/scripts/resolve-user-config.ts +12 -12
- package/templates/rover-pilot/deploy/scripts/sync-content-repo.ts +179 -0
- package/templates/rover-pilot/deploy/scripts/update-dns.ts +14 -4
- package/templates/rover-pilot/docs/onboarding-checklist.md +40 -7
- package/templates/rover-pilot/docs/operator-playbook.md +140 -0
- package/templates/rover-pilot/docs/user-onboarding.md +339 -0
- package/templates/rover-pilot/package.json +3 -0
- package/templates/rover-pilot/pilot.yaml +3 -0
- package/templates/rover-pilot/users/alice.yaml +5 -1
- package/dist/user-secret-names.d.ts +0 -6
- package/templates/rover-pilot/.kamal/hooks/pre-deploy +0 -9
- package/templates/rover-pilot/deploy/Dockerfile +0 -15
- package/templates/rover-pilot/deploy/kamal/deploy.yml +0 -39
|
@@ -1,10 +1,43 @@
|
|
|
1
1
|
# Onboarding Checklist
|
|
2
2
|
|
|
3
3
|
1. Run `bun install` so the repo uses its pinned `@rizom/ops` version.
|
|
4
|
-
2.
|
|
5
|
-
3.
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
4
|
+
2. Run `bunx brains-ops age-key:bootstrap <repo> --push-to gh`.
|
|
5
|
+
3. Fill in `pilot.yaml`.
|
|
6
|
+
- keep your pinned `brainVersion`
|
|
7
|
+
- confirm shared selectors for `aiApiKey`, `gitSyncToken`, and `contentRepoAdminToken`
|
|
8
|
+
- use different tokens for `contentRepoAdminToken` and `gitSyncToken`: admin creates/checks content repos; sync is used by runtime directory-sync
|
|
9
|
+
- confirm `agePublicKey`
|
|
10
|
+
4. Run `bunx brains-ops user:add <repo> <handle> --cohort <cohort>`.
|
|
11
|
+
- Discord is enabled by default for pilot users.
|
|
12
|
+
- if the user should be an anchor there, add `--anchor-id <discord-user-id>`.
|
|
13
|
+
- the command creates `users/<handle>.yaml`, `users/<handle>.secrets.yaml`, and the cohort membership without duplicating existing entries.
|
|
14
|
+
5. Edit the generated user file if the anchor profile needs richer metadata.
|
|
15
|
+
- For browser/CMS-first onboarding, add `setup.delivery: email` and `setup.email` to the user file.
|
|
16
|
+
- Ensure `SETUP_EMAIL_API_KEY` and `SETUP_EMAIL_FROM` exist as GitHub Secrets before deploying any email-setup user.
|
|
17
|
+
6. Run `bunx brains-ops render <repo>`.
|
|
18
|
+
7. Run `bunx brains-ops ssh-key:bootstrap <repo> --push-to gh`.
|
|
19
|
+
8. Run `bunx brains-ops cert:bootstrap <repo> --push-to gh`.
|
|
20
|
+
9. Keep raw user secret material locally for now (`.env.local`, file-backed env vars, or equivalent local inputs), including `CONTENT_REPO_ADMIN_TOKEN` for operator onboarding.
|
|
21
|
+
10. Run `bunx brains-ops secrets:encrypt <repo> <handle>`.
|
|
22
|
+
11. Commit and push `users/<handle>.secrets.yaml.age`.
|
|
23
|
+
12. Run `bunx brains-ops onboard <repo> <handle>`.
|
|
24
|
+
13. Verify the deployed Rover contract:
|
|
25
|
+
- all presets:
|
|
26
|
+
- `https://<handle>.rizom.ai/health` returns `200`
|
|
27
|
+
- unauthenticated `POST https://<handle>.rizom.ai/mcp` returns the expected auth failure
|
|
28
|
+
- background jobs are not repeatedly failing, except for expected missing optional integrations
|
|
29
|
+
- for `presetOverride: default` users:
|
|
30
|
+
- `https://<handle>.rizom.ai/` loads the browser/site surface
|
|
31
|
+
- `https://<handle>.rizom.ai/cms` loads the CMS/login surface
|
|
32
|
+
- initial site build completes
|
|
33
|
+
- content repo exists and runtime sync is healthy
|
|
34
|
+
- passkey setup/handoff is completed
|
|
35
|
+
14. For fleet upgrades, edit `pilot.yaml.brainVersion` and push once; CI rebuilds the shared image tag, refreshes generated user env files, and redeploys affected users.
|
|
36
|
+
15. For Discord users, hand the Discord setup details to the user. For email-setup users, confirm they received the setup email and completed passkey registration.
|
|
37
|
+
16. Hand over the browser defaults:
|
|
38
|
+
- Dashboard: `https://<handle>.rizom.ai/`
|
|
39
|
+
- CMS: `https://<handle>.rizom.ai/cms`
|
|
40
|
+
- GitHub token guidance for CMS access to the user's private content repo
|
|
41
|
+
17. If they need direct client access, use OAuth/passkey-capable clients where possible.
|
|
42
|
+
18. If you are also giving them a content repo workflow, describe it as optional and frame git/Obsidian as an advanced file-based path, not the default.
|
|
43
|
+
19. Send `docs/user-onboarding.md` to the user as the pilot handoff guide.
|
|
@@ -33,6 +33,24 @@ When a push changes only deploy contract files and no generated `users/<handle>/
|
|
|
33
33
|
|
|
34
34
|
They are scaffolded from `@rizom/ops`, then versioned in this repo like any other deploy contract.
|
|
35
35
|
|
|
36
|
+
## Bootstrap flow
|
|
37
|
+
|
|
38
|
+
For this fleet, operator-local secret material remains the source of truth during onboarding and rotation. The repo stores encrypted per-user secrets, not raw values.
|
|
39
|
+
|
|
40
|
+
For a new pilot user, the operator bootstrap order is:
|
|
41
|
+
|
|
42
|
+
1. `bunx brains-ops age-key:bootstrap <repo> --push-to gh`
|
|
43
|
+
2. `bunx brains-ops ssh-key:bootstrap <repo> --push-to gh`
|
|
44
|
+
3. `bunx brains-ops cert:bootstrap <repo> --push-to gh`
|
|
45
|
+
4. `bunx brains-ops secrets:encrypt <repo> <handle>`
|
|
46
|
+
5. `bunx brains-ops onboard <repo> <handle>`
|
|
47
|
+
|
|
48
|
+
`age-key:bootstrap` keeps a repo-local canonical age identity under `.brains-ops/age/identity.txt`, writes the matching public recipient to `pilot.yaml.agePublicKey`, and can push the private key to GitHub as `AGE_SECRET_KEY`.
|
|
49
|
+
|
|
50
|
+
The shared cert bootstrap writes local cert artifacts under `.brains-ops/certs/shared/`, which stays repo-local and ignored by git.
|
|
51
|
+
|
|
52
|
+
Preview hosts use the shape `<handle>-preview.rizom.ai`, so one wildcard origin cert for `*.rizom.ai` covers both the primary and preview hosts for every pilot user.
|
|
53
|
+
|
|
36
54
|
## Upgrading operator behavior
|
|
37
55
|
|
|
38
56
|
When `@rizom/ops` changes the scaffolded deploy contract:
|
|
@@ -42,6 +60,128 @@ When `@rizom/ops` changes the scaffolded deploy contract:
|
|
|
42
60
|
3. review the resulting changes to `.env.schema`, `deploy/scripts/`, and workflows in git
|
|
43
61
|
4. commit the updated deploy artifacts together
|
|
44
62
|
|
|
63
|
+
## Rover verification notes
|
|
64
|
+
|
|
65
|
+
Use the verification script after deploy:
|
|
66
|
+
|
|
67
|
+
```sh
|
|
68
|
+
bunx brains-ops verify-user . <handle>
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
It checks every Rover preset:
|
|
72
|
+
|
|
73
|
+
- `https://<handle>.rizom.ai/health` should return `200`
|
|
74
|
+
- unauthenticated `POST https://<handle>.rizom.ai/mcp` should return the expected auth failure
|
|
75
|
+
- background jobs should not be repeatedly failing, except for expected missing optional integrations
|
|
76
|
+
|
|
77
|
+
Additional `rover:core` note:
|
|
78
|
+
|
|
79
|
+
- Rover core is MCP-only; a bare `GET /` may return `401`, which does not indicate a bad deploy.
|
|
80
|
+
|
|
81
|
+
For `preset: default`, the script also checks:
|
|
82
|
+
|
|
83
|
+
- `https://<handle>.rizom.ai/` loads the browser/site surface
|
|
84
|
+
- `https://<handle>.rizom.ai/cms` loads the CMS/login surface
|
|
85
|
+
|
|
86
|
+
Manual checks that remain:
|
|
87
|
+
|
|
88
|
+
- initial site build is correct for the expected content/theme
|
|
89
|
+
- content repo exists and runtime sync is healthy beyond the basic `/health` response
|
|
90
|
+
- passkey setup/handoff is completed from the setup email
|
|
91
|
+
|
|
92
|
+
## One-user `rover:default` baseline canary
|
|
93
|
+
|
|
94
|
+
Run this before adding custom site/theme packages or rolling a larger browser/CMS-first cohort.
|
|
95
|
+
|
|
96
|
+
1. Create or choose a canary cohort with the default preset:
|
|
97
|
+
|
|
98
|
+
```yaml
|
|
99
|
+
presetOverride: default
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
2. Add exactly one canary user to that cohort.
|
|
103
|
+
3. For browser/CMS-first onboarding, configure setup email in `users/<handle>.yaml`:
|
|
104
|
+
|
|
105
|
+
```yaml
|
|
106
|
+
setup:
|
|
107
|
+
delivery: email
|
|
108
|
+
email: user@example.com
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
4. Encrypt the user's secrets and commit only the `.age` file.
|
|
112
|
+
5. Run `bunx brains-ops onboard . <handle>`.
|
|
113
|
+
6. Run `bunx brains-ops verify-user . <handle>` with no custom site/theme overrides.
|
|
114
|
+
7. Ask the user to complete passkey setup from the setup email.
|
|
115
|
+
8. Continue to visual customization only after the canary is healthy.
|
|
116
|
+
|
|
117
|
+
Rollback:
|
|
118
|
+
|
|
119
|
+
- move the canary back to a core cohort, or remove `presetOverride: default` from the cohort
|
|
120
|
+
- reconcile generated outputs
|
|
121
|
+
- rebuild/redeploy the affected user
|
|
122
|
+
|
|
123
|
+
## Setup email checklist
|
|
124
|
+
|
|
125
|
+
Use this for browser/CMS-first users who should receive their own first-passkey setup link by email.
|
|
126
|
+
|
|
127
|
+
1. Add setup delivery to the user file:
|
|
128
|
+
|
|
129
|
+
```yaml
|
|
130
|
+
setup:
|
|
131
|
+
delivery: email
|
|
132
|
+
email: user@example.com
|
|
133
|
+
```
|
|
134
|
+
|
|
135
|
+
2. Configure these GitHub Secrets before deploy:
|
|
136
|
+
- `SETUP_EMAIL_API_KEY`
|
|
137
|
+
- `SETUP_EMAIL_FROM`
|
|
138
|
+
|
|
139
|
+
3. Reconcile/deploy the user or cohort:
|
|
140
|
+
- `bunx brains-ops onboard . <handle>`
|
|
141
|
+
- or `bunx brains-ops reconcile-cohort . <cohort>`
|
|
142
|
+
|
|
143
|
+
4. Verify the generated `users/<handle>/brain.yaml` contains `auth-service.setupEmail` and `email-resend` config.
|
|
144
|
+
5. Ask the user to complete passkey setup from the email link, then use:
|
|
145
|
+
- Dashboard: `https://<handle>.rizom.ai/`
|
|
146
|
+
- CMS: `https://<handle>.rizom.ai/cms`
|
|
147
|
+
|
|
148
|
+
Notes:
|
|
149
|
+
|
|
150
|
+
- The setup URL is generated and sent by the running brain; operators should not scrape logs or SSH into the instance to retrieve it.
|
|
151
|
+
- The auth service owns setup email dedupe. It should not resend for the same persisted setup token after restart, but should retry failed delivery and resend after token rotation.
|
|
152
|
+
- `SETUP_EMAIL_FROM` is not marked required because fleets without email setup can omit it, but it is required for users with `setup.delivery: email`.
|
|
153
|
+
|
|
154
|
+
## Discord bot token checklist
|
|
155
|
+
|
|
156
|
+
Use this when enabling Discord for a pilot user.
|
|
157
|
+
|
|
158
|
+
1. Pick the user handle (for example `smoke`).
|
|
159
|
+
2. Open the Discord Developer Portal.
|
|
160
|
+
3. Create a **new application** for that user's rover.
|
|
161
|
+
4. Add a **Bot** to the application.
|
|
162
|
+
5. Copy the bot token.
|
|
163
|
+
6. Put that value in `.env` or `.env.local` in this repo as `DISCORD_BOT_TOKEN=...` while onboarding that user.
|
|
164
|
+
7. Keep `discord.enabled: true` in `users/<handle>.yaml` unless you explicitly want to disable the primary pilot interface.
|
|
165
|
+
8. Encrypt the current per-user secret payload:
|
|
166
|
+
- `bunx brains-ops secrets:encrypt . <handle>`
|
|
167
|
+
9. Reconcile/deploy the user or cohort:
|
|
168
|
+
|
|
169
|
+
- `bunx brains-ops onboard . <handle>`
|
|
170
|
+
- or `bunx brains-ops reconcile-cohort . <cohort>`
|
|
171
|
+
|
|
172
|
+
11. In the Discord Developer Portal, generate an install URL and invite the bot to the right server.
|
|
173
|
+
12. Send a test message in Discord and confirm the rover responds.
|
|
174
|
+
|
|
175
|
+
Notes:
|
|
176
|
+
|
|
177
|
+
- Use **one bot token per user/rover**.
|
|
178
|
+
- Do not reuse the same Discord bot token across multiple pilot users.
|
|
179
|
+
- Discord is the default pilot interface moving forward.
|
|
180
|
+
- The encrypted `users/<handle>.secrets.yaml.age` file is the durable checked-in deploy input; your local env is only the operator staging source.
|
|
181
|
+
- Direct MCP client access should use OAuth/passkey-capable clients where possible.
|
|
182
|
+
- When explaining the content workflow, describe it first as a normal **git repo** of **markdown/text files**.
|
|
183
|
+
- Position **Obsidian** as optional: it is just one possible editor for those same files, not the default requirement.
|
|
184
|
+
|
|
45
185
|
## Recovery notes
|
|
46
186
|
|
|
47
187
|
Document known failure modes, recovery steps, and operator notes here.
|
|
@@ -0,0 +1,339 @@
|
|
|
1
|
+
# Rover Pilot User Onboarding
|
|
2
|
+
|
|
3
|
+
Welcome to the Rover pilot.
|
|
4
|
+
|
|
5
|
+
This guide is for first-time Rover users. You do not need prior experience with Rover, MCP, git, GitHub, or Obsidian to get started.
|
|
6
|
+
|
|
7
|
+
## What Rover is
|
|
8
|
+
|
|
9
|
+
Rover is your private AI assistant for working with your own notes, links, and ideas.
|
|
10
|
+
|
|
11
|
+
For the current pilot, the normal core experience is:
|
|
12
|
+
|
|
13
|
+
- **Passkey setup email** — your secure first step
|
|
14
|
+
- **Discord** — the main chat interface when enabled for your pilot
|
|
15
|
+
- **Dashboard** — your browser overview at `https://<handle>.rizom.ai/`
|
|
16
|
+
- **MCP** — optional direct access from OAuth/passkey-capable AI clients
|
|
17
|
+
|
|
18
|
+
Some users may also receive:
|
|
19
|
+
|
|
20
|
+
- **CMS** access at `https://<handle>.rizom.ai/cms`
|
|
21
|
+
- **GitHub/content repo** access for editing the underlying markdown files
|
|
22
|
+
- **Obsidian** instructions for a local file-based workflow
|
|
23
|
+
|
|
24
|
+
If we did not explicitly give you CMS, GitHub, MCP, or Obsidian instructions, you can ignore those sections for now.
|
|
25
|
+
|
|
26
|
+
## Start here: setup
|
|
27
|
+
|
|
28
|
+
1. Open the setup email from Rover.
|
|
29
|
+
2. Click the passkey setup link.
|
|
30
|
+
3. Register a passkey in your browser.
|
|
31
|
+
4. Open your Dashboard: `https://<handle>.rizom.ai/`.
|
|
32
|
+
5. If Discord is enabled for you, send Rover a first message there.
|
|
33
|
+
6. If we asked you to test MCP, use the separate MCP connection instructions we sent for your pilot.
|
|
34
|
+
|
|
35
|
+
## Your setup email
|
|
36
|
+
|
|
37
|
+
The setup email contains a single-use passkey setup link.
|
|
38
|
+
|
|
39
|
+
Treat that link like a temporary password:
|
|
40
|
+
|
|
41
|
+
- do not forward it
|
|
42
|
+
- use it once
|
|
43
|
+
- expect it to expire
|
|
44
|
+
- ask us for help if it has expired or does not work
|
|
45
|
+
|
|
46
|
+
After you register your passkey, the setup link closes. Your passkey becomes the sign-in method for Rover's browser and OAuth-capable client flows.
|
|
47
|
+
|
|
48
|
+
If your Rover already existed before you received this email, nothing is being reset. The email is just the secure handoff for registering your own passkey so you can sign in yourself.
|
|
49
|
+
|
|
50
|
+
## Your first Rover session
|
|
51
|
+
|
|
52
|
+
Start in **Discord** if it is enabled for your pilot. That is the normal first interface.
|
|
53
|
+
|
|
54
|
+
### 1. Say hello
|
|
55
|
+
|
|
56
|
+
Send:
|
|
57
|
+
|
|
58
|
+
> What can you help me do, and what should I use you for?
|
|
59
|
+
|
|
60
|
+
Rover should answer with a short overview of what it can do.
|
|
61
|
+
|
|
62
|
+
### 2. Create your first note
|
|
63
|
+
|
|
64
|
+
Ask Rover to save a simple note:
|
|
65
|
+
|
|
66
|
+
> Save a note: I am trying Rover because I want a better way to collect ideas, links, and questions in one place.
|
|
67
|
+
|
|
68
|
+
Or:
|
|
69
|
+
|
|
70
|
+
> Help me save my first note.
|
|
71
|
+
|
|
72
|
+
### 3. Add your first link
|
|
73
|
+
|
|
74
|
+
Send Rover a link you want to remember:
|
|
75
|
+
|
|
76
|
+
> Save this link and tell me why it might be useful later: https://example.com
|
|
77
|
+
|
|
78
|
+
Or:
|
|
79
|
+
|
|
80
|
+
> Add this as a link about tools I want to revisit: https://example.com
|
|
81
|
+
|
|
82
|
+
Rover should save the link and, when possible, keep a short description of why it matters.
|
|
83
|
+
|
|
84
|
+
### 4. Upload an existing Markdown doc
|
|
85
|
+
|
|
86
|
+
If you already have notes or docs in Markdown, you do not need to retype them.
|
|
87
|
+
|
|
88
|
+
Upload a `.md` file and ask Rover to save or import it:
|
|
89
|
+
|
|
90
|
+
> Save this Markdown doc in my notes.
|
|
91
|
+
|
|
92
|
+
Or:
|
|
93
|
+
|
|
94
|
+
> Import this doc and tell me what it is about.
|
|
95
|
+
|
|
96
|
+
This is often the fastest way to give Rover useful context.
|
|
97
|
+
|
|
98
|
+
### 5. Ask Rover about what you just added
|
|
99
|
+
|
|
100
|
+
After you have saved a note, link, or Markdown doc, ask Rover to reflect it back:
|
|
101
|
+
|
|
102
|
+
> What have I added so far?
|
|
103
|
+
|
|
104
|
+
Or:
|
|
105
|
+
|
|
106
|
+
> What do you know about what I am interested in so far?
|
|
107
|
+
|
|
108
|
+
This is the basic Rover loop: add material, then ask Rover to help you think with it.
|
|
109
|
+
|
|
110
|
+
### 6. Try a more useful task
|
|
111
|
+
|
|
112
|
+
Once Rover has a little context, try one of these:
|
|
113
|
+
|
|
114
|
+
> Summarize my notes so far.
|
|
115
|
+
|
|
116
|
+
> What themes do you see in what I have added?
|
|
117
|
+
|
|
118
|
+
> Turn my rough note into a clearer paragraph.
|
|
119
|
+
|
|
120
|
+
> Help me make a small reading list from the links I saved.
|
|
121
|
+
|
|
122
|
+
These examples show the main scope of Rover: saving material, organizing it, reflecting on it, and helping you make something from it.
|
|
123
|
+
|
|
124
|
+
### 7. Ask another agent
|
|
125
|
+
|
|
126
|
+
If your pilot has agent-to-agent access enabled, we will tell you which other agents you can address and how to talk to them. Otherwise Rover should clearly say that this workflow is not available yet.
|
|
127
|
+
|
|
128
|
+
## The default mental model
|
|
129
|
+
|
|
130
|
+
If you remember only one thing, remember this:
|
|
131
|
+
|
|
132
|
+
- **Discord** = talk to Rover, when enabled
|
|
133
|
+
- **Dashboard** = browser overview
|
|
134
|
+
- **MCP** = optional direct client integration through OAuth/passkey login
|
|
135
|
+
- **CMS / git / Obsidian** = optional content-editing workflows when we enable them for you
|
|
136
|
+
|
|
137
|
+
## What you will receive from us
|
|
138
|
+
|
|
139
|
+
Depending on your pilot cohort, we will send you some or all of these:
|
|
140
|
+
|
|
141
|
+
- a passkey setup email from Rover
|
|
142
|
+
- this onboarding guide, or a link to it
|
|
143
|
+
- confirmation that Discord is enabled for you, plus the invite/setup steps
|
|
144
|
+
- your **Dashboard URL**: `https://<handle>.rizom.ai/`
|
|
145
|
+
- CMS URL and GitHub token instructions, if CMS editing is enabled
|
|
146
|
+
- private content repo access, if file-based editing is enabled
|
|
147
|
+
- separate MCP connection instructions, if MCP testing is enabled
|
|
148
|
+
- any extra instructions if we are testing a specific workflow with your cohort
|
|
149
|
+
|
|
150
|
+
Keep setup links, GitHub tokens, and any MCP credentials separate. Do not paste the passkey setup link into an MCP client.
|
|
151
|
+
|
|
152
|
+
## Discord
|
|
153
|
+
|
|
154
|
+
Discord is the default chat interface when it is enabled for your pilot. It is separate from the passkey setup email: the email sets up browser/client identity, while Discord is where many users chat with Rover day to day.
|
|
155
|
+
|
|
156
|
+
Use it to:
|
|
157
|
+
|
|
158
|
+
- save quick notes
|
|
159
|
+
- drop in links
|
|
160
|
+
- ask questions
|
|
161
|
+
- use Rover day to day without setting up a separate client
|
|
162
|
+
|
|
163
|
+
If Discord is enabled, we will send the exact invite/setup steps separately.
|
|
164
|
+
|
|
165
|
+
## Dashboard basics
|
|
166
|
+
|
|
167
|
+
The Dashboard is the browser landing page for your Rover.
|
|
168
|
+
|
|
169
|
+
Open it at:
|
|
170
|
+
|
|
171
|
+
```text
|
|
172
|
+
https://<handle>.rizom.ai/
|
|
173
|
+
```
|
|
174
|
+
|
|
175
|
+
Use it to confirm your Rover is up, see available endpoints, and orient yourself before using optional tools. This is not meant to be a public marketing website.
|
|
176
|
+
|
|
177
|
+
## Optional: Working in the CMS
|
|
178
|
+
|
|
179
|
+
If CMS is enabled for you, open:
|
|
180
|
+
|
|
181
|
+
```text
|
|
182
|
+
https://<handle>.rizom.ai/cms
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
The CMS is a browser editor for your Rover content. It may ask for GitHub access because your content lives in a private GitHub repo.
|
|
186
|
+
|
|
187
|
+
Use the CMS when you want to:
|
|
188
|
+
|
|
189
|
+
- create or edit notes in the browser
|
|
190
|
+
- add existing Markdown docs
|
|
191
|
+
- browse structured content collections
|
|
192
|
+
- make cleaner edits than you would in chat
|
|
193
|
+
|
|
194
|
+
A good first CMS task is:
|
|
195
|
+
|
|
196
|
+
1. open the **Notes** collection
|
|
197
|
+
2. create a note titled `Why I’m using Rover`
|
|
198
|
+
3. write 3 to 5 sentences
|
|
199
|
+
4. save it
|
|
200
|
+
5. refresh the CMS and confirm the note is still there
|
|
201
|
+
|
|
202
|
+
If the CMS asks for GitHub access, use the fine-grained GitHub token for your private Rover content repo. If you were not given CMS/GitHub instructions, skip this section.
|
|
203
|
+
|
|
204
|
+
## Optional: direct MCP access
|
|
205
|
+
|
|
206
|
+
MCP is an optional way to connect Rover directly to an AI client that supports remote HTTP MCP.
|
|
207
|
+
|
|
208
|
+
Use MCP only if we ask you to test it or if you already use a client that supports remote HTTP / Streamable HTTP MCP servers.
|
|
209
|
+
|
|
210
|
+
We will send MCP connection details separately when MCP testing is enabled. The normal hosted MCP path is `https://<handle>.rizom.ai/mcp`, but use the exact server URL we send for your pilot.
|
|
211
|
+
|
|
212
|
+
### What the MCP login flow looks like
|
|
213
|
+
|
|
214
|
+
If your client supports OAuth / browser login, the normal flow is:
|
|
215
|
+
|
|
216
|
+
1. In your MCP client, add a remote MCP server.
|
|
217
|
+
2. Enter the Rover MCP server URL we sent you.
|
|
218
|
+
3. The client discovers Rover's OAuth settings automatically.
|
|
219
|
+
4. The client opens a browser window for Rover login.
|
|
220
|
+
5. You sign in with your passkey.
|
|
221
|
+
6. Rover asks you to approve client access.
|
|
222
|
+
7. The client receives an access token automatically.
|
|
223
|
+
8. You can use Rover tools from that client.
|
|
224
|
+
|
|
225
|
+
You should not need to copy a setup link into the client. The setup link is only for registering your first passkey.
|
|
226
|
+
|
|
227
|
+
If your client asks for a token or other credential, use only the MCP instructions we sent separately. Treat any MCP credentials like a password. Do not share them.
|
|
228
|
+
|
|
229
|
+
### Client-specific notes
|
|
230
|
+
|
|
231
|
+
Different MCP clients support remote HTTP and OAuth at different speeds. If you are using Claude Desktop, Cursor, VS Code, MCP Inspector, or another client, tell us the exact version before assuming it should work.
|
|
232
|
+
|
|
233
|
+
### If MCP does not work
|
|
234
|
+
|
|
235
|
+
Send us:
|
|
236
|
+
|
|
237
|
+
- the client name
|
|
238
|
+
- the client version
|
|
239
|
+
- the exact error message
|
|
240
|
+
- a screenshot if possible
|
|
241
|
+
- the server URL you entered, without any secret token
|
|
242
|
+
|
|
243
|
+
Do not paste your passkey setup link into an MCP client.
|
|
244
|
+
|
|
245
|
+
## Optional: git, text files, and Obsidian
|
|
246
|
+
|
|
247
|
+
Rover content can also live as normal markdown/text files in a private GitHub repo.
|
|
248
|
+
|
|
249
|
+
This workflow is optional. Use it only if we explicitly enabled it for you or if you want more control.
|
|
250
|
+
|
|
251
|
+
If enabled, we will:
|
|
252
|
+
|
|
253
|
+
1. create or confirm your private content repo
|
|
254
|
+
2. invite your GitHub account to that repo
|
|
255
|
+
3. send you the repo URL
|
|
256
|
+
4. explain whether to use GitHub Desktop, command-line git, Obsidian, or the CMS
|
|
257
|
+
|
|
258
|
+
You do not need GitHub repo access just to use Rover in Discord.
|
|
259
|
+
|
|
260
|
+
## Wishlist: when Rover cannot do something yet
|
|
261
|
+
|
|
262
|
+
Rover has a built-in wishlist.
|
|
263
|
+
|
|
264
|
+
If you ask for something Rover cannot do yet, it should explain the limitation and save the request as a wish. This helps us see which missing capabilities matter most.
|
|
265
|
+
|
|
266
|
+
## What to expect in the pilot
|
|
267
|
+
|
|
268
|
+
This is a real working system, but it is still an early pilot. Expect some rough edges, setup steps that may still be a bit manual, and improvements during the pilot.
|
|
269
|
+
|
|
270
|
+
## Privacy and boundaries
|
|
271
|
+
|
|
272
|
+
For the pilot:
|
|
273
|
+
|
|
274
|
+
- your Rover is deployed specifically for you
|
|
275
|
+
- browser/client access uses passkeys/OAuth where supported
|
|
276
|
+
- if you are using MCP, we will send separate access instructions
|
|
277
|
+
- your content repo is private when repo access is enabled
|
|
278
|
+
- avoid putting highly sensitive material into the pilot unless we have explicitly agreed that it is in scope
|
|
279
|
+
|
|
280
|
+
If you are unsure whether something belongs in Rover, ask us first.
|
|
281
|
+
|
|
282
|
+
## Troubleshooting
|
|
283
|
+
|
|
284
|
+
### I did not receive the setup email
|
|
285
|
+
|
|
286
|
+
Check spam/promotions first. If it is not there, tell us which email address we should use.
|
|
287
|
+
|
|
288
|
+
### The setup link expired or does not work
|
|
289
|
+
|
|
290
|
+
Reply to your Rover operator. We can rotate/reissue setup.
|
|
291
|
+
|
|
292
|
+
### I opened the domain and it does not look like a normal public site
|
|
293
|
+
|
|
294
|
+
That is expected. The root URL is your Dashboard, not a public marketing site.
|
|
295
|
+
|
|
296
|
+
### The browser asks me to use a passkey
|
|
297
|
+
|
|
298
|
+
That is expected after setup. Use the same passkey you registered from the setup email.
|
|
299
|
+
|
|
300
|
+
### My MCP client cannot connect
|
|
301
|
+
|
|
302
|
+
Send us the client name, version, exact error message, and a screenshot if possible.
|
|
303
|
+
|
|
304
|
+
### The CMS asks for GitHub auth and I am not sure what to do
|
|
305
|
+
|
|
306
|
+
That is expected only if CMS is enabled for you. Use the GitHub token instructions we sent for your private Rover content repo. If you did not receive those instructions, ask us before continuing.
|
|
307
|
+
|
|
308
|
+
## What feedback helps us most
|
|
309
|
+
|
|
310
|
+
We especially want to hear:
|
|
311
|
+
|
|
312
|
+
- what was confusing during setup
|
|
313
|
+
- whether the setup email and passkey flow made sense
|
|
314
|
+
- whether Discord and Dashboard made sense
|
|
315
|
+
- what felt useful immediately
|
|
316
|
+
- what felt weak, awkward, or unclear
|
|
317
|
+
- what you expected Rover to do but could not get it to do
|
|
318
|
+
- whether you would keep using it after the pilot
|
|
319
|
+
|
|
320
|
+
Short, honest feedback is perfect.
|
|
321
|
+
|
|
322
|
+
## Quick handoff template
|
|
323
|
+
|
|
324
|
+
When we onboard you, the message will look roughly like this:
|
|
325
|
+
|
|
326
|
+
```text
|
|
327
|
+
Setup email: sent to <email>
|
|
328
|
+
Onboarding guide: attached / linked
|
|
329
|
+
Dashboard URL: https://<handle>.rizom.ai/
|
|
330
|
+
Discord enabled: yes/no
|
|
331
|
+
Discord setup: <invite link or setup steps>
|
|
332
|
+
MCP access: optional / enabled / not enabled
|
|
333
|
+
MCP setup: sent separately if enabled
|
|
334
|
+
CMS enabled: yes/no
|
|
335
|
+
CMS URL: https://<handle>.rizom.ai/cms
|
|
336
|
+
Content repo access: yes/no
|
|
337
|
+
```
|
|
338
|
+
|
|
339
|
+
If anything is unclear, reply with the exact error text or a screenshot and we will help.
|
|
@@ -1,9 +0,0 @@
|
|
|
1
|
-
#!/usr/bin/env bash
|
|
2
|
-
set -euo pipefail
|
|
3
|
-
|
|
4
|
-
BRAIN_FILE="${BRAIN_YAML_PATH:-brain.yaml}"
|
|
5
|
-
SSH_USER="$(ruby -e 'require "yaml"; config = YAML.load_file("deploy/kamal/deploy.yml") || {}; puts(config.dig("ssh", "user") || "root")')"
|
|
6
|
-
IFS=',' read -ra HOSTS <<< "$KAMAL_HOSTS"
|
|
7
|
-
for host in "${HOSTS[@]}"; do
|
|
8
|
-
scp -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null "$BRAIN_FILE" "${SSH_USER}@${host}:/opt/brain.yaml"
|
|
9
|
-
done
|
|
@@ -1,15 +0,0 @@
|
|
|
1
|
-
ARG BUN_VERSION=1.3.10
|
|
2
|
-
FROM oven/bun:${BUN_VERSION}-slim
|
|
3
|
-
|
|
4
|
-
ARG BRAIN_VERSION
|
|
5
|
-
WORKDIR /app
|
|
6
|
-
|
|
7
|
-
RUN test -n "$BRAIN_VERSION" \
|
|
8
|
-
&& printf '{"name":"rover-pilot-runtime","private":true}\n' > package.json \
|
|
9
|
-
&& bun add @rizom/brain@$BRAIN_VERSION
|
|
10
|
-
|
|
11
|
-
ENV XDG_DATA_HOME=/data
|
|
12
|
-
ENV XDG_CONFIG_HOME=/config
|
|
13
|
-
RUN mkdir -p /app/brain-data /data /config && chmod -R 777 /app/brain-data /data /config
|
|
14
|
-
|
|
15
|
-
CMD ["sh", "-c", "exec ./node_modules/.bin/brain start"]
|
|
@@ -1,39 +0,0 @@
|
|
|
1
|
-
service: rover
|
|
2
|
-
image: <%= ENV['IMAGE_REPOSITORY'] %>
|
|
3
|
-
|
|
4
|
-
servers:
|
|
5
|
-
mcp:
|
|
6
|
-
hosts:
|
|
7
|
-
- <%= ENV['SERVER_IP'] %>
|
|
8
|
-
|
|
9
|
-
proxy:
|
|
10
|
-
ssl:
|
|
11
|
-
certificate_pem: CERTIFICATE_PEM
|
|
12
|
-
private_key_pem: PRIVATE_KEY_PEM
|
|
13
|
-
hosts:
|
|
14
|
-
- <%= ENV['BRAIN_DOMAIN'] %>
|
|
15
|
-
app_port: 3333
|
|
16
|
-
healthcheck:
|
|
17
|
-
path: /health
|
|
18
|
-
|
|
19
|
-
registry:
|
|
20
|
-
server: ghcr.io
|
|
21
|
-
username: <%= ENV['REGISTRY_USERNAME'] %>
|
|
22
|
-
password:
|
|
23
|
-
- KAMAL_REGISTRY_PASSWORD
|
|
24
|
-
|
|
25
|
-
builder:
|
|
26
|
-
arch: amd64
|
|
27
|
-
|
|
28
|
-
env:
|
|
29
|
-
clear:
|
|
30
|
-
NODE_ENV: production
|
|
31
|
-
secret:
|
|
32
|
-
- AI_API_KEY
|
|
33
|
-
- GIT_SYNC_TOKEN
|
|
34
|
-
- MCP_AUTH_TOKEN
|
|
35
|
-
- DISCORD_BOT_TOKEN
|
|
36
|
-
|
|
37
|
-
volumes:
|
|
38
|
-
- /opt/brain-data:/app/brain-data
|
|
39
|
-
- /opt/brain.yaml:/app/brain.yaml
|