@shinobiapps/shinobi 0.1.6 → 0.2.1
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/CHANGELOG.md +92 -0
- package/LICENSE +21 -21
- package/README.md +50 -17
- package/dist/cli.js +23 -1
- package/dist/cli.js.map +1 -1
- package/dist/dashboard/auth.d.ts.map +1 -1
- package/dist/dashboard/auth.js +6 -3
- package/dist/dashboard/auth.js.map +1 -1
- package/dist/dashboard/server.d.ts +10 -1
- package/dist/dashboard/server.d.ts.map +1 -1
- package/dist/dashboard/server.js +28 -2
- package/dist/dashboard/server.js.map +1 -1
- package/dist/lib/db.d.ts.map +1 -1
- package/dist/lib/db.js +6 -2
- package/dist/lib/db.js.map +1 -1
- package/dist/lib/migrations.d.ts +2 -0
- package/dist/lib/migrations.d.ts.map +1 -1
- package/dist/lib/migrations.js +49 -4
- package/dist/lib/migrations.js.map +1 -1
- package/dist/lib/paths.d.ts +26 -0
- package/dist/lib/paths.d.ts.map +1 -0
- package/dist/lib/paths.js +68 -0
- package/dist/lib/paths.js.map +1 -0
- package/dist/lib/rate-limit.d.ts +25 -0
- package/dist/lib/rate-limit.d.ts.map +1 -0
- package/dist/lib/rate-limit.js +75 -0
- package/dist/lib/rate-limit.js.map +1 -0
- package/dist/models/decision_drafts.d.ts.map +1 -1
- package/dist/models/decision_drafts.js +2 -1
- package/dist/models/decision_drafts.js.map +1 -1
- package/dist/models/decisions.d.ts.map +1 -1
- package/dist/models/decisions.js +12 -3
- package/dist/models/decisions.js.map +1 -1
- package/dist/models/notes.d.ts.map +1 -1
- package/dist/models/notes.js +2 -1
- package/dist/models/notes.js.map +1 -1
- package/dist/models/subtasks.d.ts.map +1 -1
- package/dist/models/subtasks.js +2 -1
- package/dist/models/subtasks.js.map +1 -1
- package/dist/server/http.d.ts +17 -0
- package/dist/server/http.d.ts.map +1 -0
- package/dist/server/http.js +42 -0
- package/dist/server/http.js.map +1 -0
- package/dist/server/mcp.d.ts +14 -0
- package/dist/server/mcp.d.ts.map +1 -1
- package/dist/server/mcp.js +19 -1
- package/dist/server/mcp.js.map +1 -1
- package/dist/server/tools/projects.d.ts.map +1 -1
- package/dist/server/tools/projects.js +16 -2
- package/dist/server/tools/projects.js.map +1 -1
- package/dist/server/tools/workflow.d.ts.map +1 -1
- package/dist/server/tools/workflow.js +27 -3
- package/dist/server/tools/workflow.js.map +1 -1
- package/dist/services/auth/magic-link.d.ts.map +1 -1
- package/dist/services/auth/magic-link.js +3 -0
- package/dist/services/auth/magic-link.js.map +1 -1
- package/docs/configuration.md +21 -0
- package/docs/deploy-gcp-free.md +205 -0
- package/docs/getting-started.md +94 -0
- package/docs/recovery-runbook.md +162 -0
- package/docs/remote-mcp.md +132 -0
- package/migrations/0001_initial_schema.sql +284 -284
- package/migrations/0002_activity_and_links.sql +26 -26
- package/package.json +11 -5
|
@@ -0,0 +1,132 @@
|
|
|
1
|
+
# Remote mode: one Shinobi brain for every device
|
|
2
|
+
|
|
3
|
+
By default Shinobi runs local-first: the MCP server speaks stdio and the
|
|
4
|
+
SQLite database lives in `~/.shinobi/` on one machine. Remote mode exposes the
|
|
5
|
+
same 37 tools over MCP **streamable HTTP** so any MCP client — Claude Code
|
|
6
|
+
(desktop *and* web/mobile sessions), Cursor, Cline, Continue.dev, Zed — can
|
|
7
|
+
share a single brain hosted on a server you control.
|
|
8
|
+
|
|
9
|
+
```
|
|
10
|
+
laptop: VS Code + Claude Code ──┐
|
|
11
|
+
├──► https://your-host/mcp ──► one SQLite brain
|
|
12
|
+
phone: Claude Code web session ─┘ (token auth)
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Decisions logged from your desk are known to the session you open from your
|
|
16
|
+
phone, and vice versa. Sessions stay disposable; the memory doesn't.
|
|
17
|
+
|
|
18
|
+
## How it works
|
|
19
|
+
|
|
20
|
+
`shinobi serve` starts the dashboard and mounts the MCP endpoint at `/mcp` in
|
|
21
|
+
the same process (same port). The endpoint is stateless — every POST gets a
|
|
22
|
+
fresh server over the shared tool registry — so it survives restarts and works
|
|
23
|
+
behind load balancers.
|
|
24
|
+
|
|
25
|
+
Auth reuses the dashboard token middleware:
|
|
26
|
+
|
|
27
|
+
- loopback bind (`127.0.0.1`) → auth off, same as the local dashboard
|
|
28
|
+
- any other bind → token auth **on automatically**; clients send
|
|
29
|
+
`Authorization: Bearer <token>`
|
|
30
|
+
- the token comes from `SHINOBI_DASHBOARD_TOKEN`, or is generated once and
|
|
31
|
+
stored at `<config-dir>/dashboard-token`
|
|
32
|
+
|
|
33
|
+
> **Never** expose a non-authenticated bind to the internet. The MCP tools
|
|
34
|
+
> can read and write your entire project memory. Always front the endpoint
|
|
35
|
+
> with HTTPS (reverse proxy or your platform's TLS).
|
|
36
|
+
|
|
37
|
+
> 💸 Want this for $0/month? Follow the step-by-step
|
|
38
|
+
> [GCP free tier + Cloudflare Tunnel walkthrough](deploy-gcp-free.md).
|
|
39
|
+
|
|
40
|
+
## Quickstart: Docker on a VPS
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
docker build -t shinobi .
|
|
44
|
+
docker run -d --name shinobi --restart unless-stopped \
|
|
45
|
+
-p 127.0.0.1:8765:8765 \
|
|
46
|
+
-v shinobi-data:/data \
|
|
47
|
+
-e SHINOBI_DASHBOARD_TOKEN="$(openssl rand -hex 24)" \
|
|
48
|
+
shinobi
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
The volume on `/data` is **mandatory in practice** — the SQLite database
|
|
52
|
+
lives there (`SHINOBI_CONFIG_DIR=/data`); without it every restart wipes your
|
|
53
|
+
memory.
|
|
54
|
+
|
|
55
|
+
Then put HTTPS in front, e.g. Caddy:
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
shinobi.example.com {
|
|
59
|
+
reverse_proxy 127.0.0.1:8765
|
|
60
|
+
}
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
## Quickstart: bare Node (no Docker)
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
npm install -g @shinobiapps/shinobi
|
|
67
|
+
SHINOBI_DASHBOARD_TOKEN="$(openssl rand -hex 24)" \
|
|
68
|
+
shinobi serve --host 0.0.0.0 --port 8765
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Same rules: non-loopback bind enables token auth; front with HTTPS.
|
|
72
|
+
|
|
73
|
+
## Connecting clients
|
|
74
|
+
|
|
75
|
+
**Claude Code (CLI / VS Code extension):**
|
|
76
|
+
|
|
77
|
+
```bash
|
|
78
|
+
claude mcp add --transport http shinobi https://shinobi.example.com/mcp \
|
|
79
|
+
--header "Authorization: Bearer YOUR_TOKEN"
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
**Claude Code on the web:** add the same URL + header in your environment's
|
|
83
|
+
MCP server configuration.
|
|
84
|
+
|
|
85
|
+
**Cursor / Cline / Continue.dev / Zed** (any client supporting remote MCP):
|
|
86
|
+
|
|
87
|
+
```json
|
|
88
|
+
{
|
|
89
|
+
"mcpServers": {
|
|
90
|
+
"shinobi": {
|
|
91
|
+
"url": "https://shinobi.example.com/mcp",
|
|
92
|
+
"headers": { "Authorization": "Bearer YOUR_TOKEN" }
|
|
93
|
+
}
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
**Make every session start informed** — add to your project's `CLAUDE.md`
|
|
99
|
+
(or rules file):
|
|
100
|
+
|
|
101
|
+
```markdown
|
|
102
|
+
At the start of each session, call the shinobi `agent_bootstrap` tool for the
|
|
103
|
+
active project to load decisions, dead ends, context and open tasks. Before
|
|
104
|
+
implementing a new approach, call `check_dead_ends`. Log decisions and dead
|
|
105
|
+
ends as you go; call `session_closeout` before finishing.
|
|
106
|
+
```
|
|
107
|
+
|
|
108
|
+
## Environment reference
|
|
109
|
+
|
|
110
|
+
| Variable | Default | Purpose |
|
|
111
|
+
| --- | --- | --- |
|
|
112
|
+
| `SHINOBI_MCP_HTTP` | `off` | Set `on` to expose `/mcp` from `shinobi dashboard` (the `serve` command implies it) |
|
|
113
|
+
| `SHINOBI_DASHBOARD_HOST` | `127.0.0.1` | Bind address (`serve --host` overrides) |
|
|
114
|
+
| `SHINOBI_DASHBOARD_PORT` | `8765` | Port (`serve --port` overrides) |
|
|
115
|
+
| `SHINOBI_DASHBOARD_TOKEN` | generated | Bearer token for dashboard + `/mcp` |
|
|
116
|
+
| `SHINOBI_DASHBOARD_AUTH` | auto | `on`/`off` override; auto = on for non-loopback binds |
|
|
117
|
+
| `SHINOBI_CONFIG_DIR` | `~/.shinobi` | Database + config location (Docker image sets `/data`) |
|
|
118
|
+
| `SHINOBI_DB_PATH` | `<config-dir>/shinobi.db` | Explicit database file override |
|
|
119
|
+
|
|
120
|
+
## FAQ
|
|
121
|
+
|
|
122
|
+
**Does local mode still work?** Yes, nothing changes — stdio (`shinobi mcp`)
|
|
123
|
+
remains the default and the npm install flow is untouched. Remote mode is the
|
|
124
|
+
same binary with a different transport.
|
|
125
|
+
|
|
126
|
+
**Can I keep a local copy of the brain?** Yes — `shinobi sync` (git snapshot
|
|
127
|
+
push/pull) works on the server like anywhere else, so the hosted database can
|
|
128
|
+
be backed up to a private git repo and pulled to any machine.
|
|
129
|
+
|
|
130
|
+
**Multiple people?** Remote mode is designed for one operator across many
|
|
131
|
+
devices. The token grants full read/write; don't share it as a team auth
|
|
132
|
+
scheme.
|