Skip to content

Self-hosted MCP server + dashboard giving Claude Code, Cursor & Hermes agents shared long-term memory over a git-backed markdown vault. Agent-native, Obsidian-compatible second brain — markdown RAG, no vector DB.

feat: add-repo-by-URL+token (PAT path) + deploy docs for both GitHub paths

Ronalds Palacisaa15c4319ace
diff --git a/.gitignore b/.gitignore
index 98ee58c..ea7dd92 100644
--- a/.gitignore
+++ b/.gitignore
@@ -11,7 +11,8 @@ next-env.d.ts
.DS_Store
.vercel
.gstack/
-# local app state (token hashes) — never commit
+# local app state (token hashes, github token, repo clones) — never commit
.cortex/
**/.cortex/
+.cortex-data/
sample-vault/.gitignore
diff --git a/DEPLOY.md b/DEPLOY.md
index 9e2c7f1..40d4cc0 100644
--- a/DEPLOY.md
+++ b/DEPLOY.md
@@ -1,58 +1,65 @@
# Deploying Cortex
-Cortex deploys as one container. The **app** repo is this repo; the **vault** is a separate
-remote repo the app clones + git-syncs into a volume. No machine keeps a local vault copy.
+Cortex deploys as one container (this repo). Vault repos are **connected in the dashboard**
+(Workspaces) — no repo lives in this repo, and no laptop keeps a vault copy. The active
+workspace is what the dashboard shows and what agents read/write.
## 1. Push this repo to GitHub
-Already a git repo. Create a remote (private is fine) and push `main`.
+Already a git repo — create a remote and push `main`.
-## 2. Create the vault repo (if you don't have one)
-A separate repo of markdown (e.g. `youruser/second-brain`). Cortex clones it into its volume.
-Give it the folders in `SCHEMA.md` (`clients/`, `decisions/`, …).
+## 2. Dashboard login — Google OAuth
+1. Google Cloud Console → Credentials → Create OAuth client ID → Web application.
+2. Redirect URI: `https://<your-app>.up.railway.app/api/auth/callback`
+3. Copy the Client ID + Secret.
-## 3. Google OAuth (dashboard login)
-1. Google Cloud Console → **APIs & Services → Credentials → Create OAuth client ID** → **Web application**.
-2. **Authorized redirect URI:** `https://<your-app>.up.railway.app/api/auth/callback`
-3. Copy the **Client ID** and **Client secret**.
-
-## 4. Railway
-1. **New Project → Deploy from GitHub repo** → this repo. It builds via the root `Dockerfile`.
+## 3. Railway
+1. **New Project → Deploy from GitHub repo** → this repo (builds via root `Dockerfile`).
2. **Add a Volume**, mount path `/data`.
3. **Variables:**
| Variable | Value |
|---|---|
| `NEXT_PUBLIC_APP_NAME` | e.g. `Klyiro Brain` |
-| `VAULT_DIR` | `/data` |
-| `GIT_REMOTE` | the vault repo URL (`https://github.com/youruser/second-brain.git`) |
-| `GIT_TOKEN` | GitHub token with **push** access to the vault repo |
-| `GIT_SYNC_ENABLED` | `true` |
+| `CORTEX_DATA_DIR` | `/data` (app state + vault clones live here) |
+| `GIT_SYNC_ENABLED` | `true` (auto commit+push the active vault) |
| `GIT_AUTHOR_NAME` / `GIT_AUTHOR_EMAIL` | commit identity |
-| `AUTH_SECRET` | `openssl rand -base64 32` |
+| `AUTH_SECRET` | `openssl rand -base64 32`, or Railway "Generate" |
| `APP_URL` | `https://<your-app>.up.railway.app` |
-| `ALLOWED_EMAILS` | comma-separated team emails |
-| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | from step 3 |
-| `MCP_TOKEN` | a long random string (agents send this) |
-| `ANTHROPIC_API_KEY` | for `brain_capture` (optional) |
+| `ALLOWED_EMAILS` | comma-separated team emails (Google login) |
+| `GOOGLE_CLIENT_ID` / `GOOGLE_CLIENT_SECRET` | from step 2 |
+| `ANTHROPIC_API_KEY` + `HARNESS_ENABLED=true` | optional, for `brain_capture` |
+| `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` | optional — see step 5 (OAuth path) |
+
+Deploy, then sign in with Google.
+
+## 4. Connect a vault repo (in the dashboard → Workspaces)
+Two ways — pick one:
+
+- **URL + token (zero setup):** paste the repo URL + a GitHub token with access. Works with
+ no GitHub OAuth app — the simplest path, especially for self-hosting.
+- **Connect GitHub (nicer):** if you set the GitHub OAuth app in step 5, click *Connect GitHub*
+ and pick a repo from a list.
-4. Deploy. On first boot the app clones `GIT_REMOTE` into `/data`. The dashboard is gated by
- Google login (allowlist); the MCP is gated by `MCP_TOKEN`.
+Add repos, switch the active one, remove — all in the UI. MCP tokens (per teammate/agent) are
+created on the **Connect** page.
-## 5. Connect agents to the MCP
-**Claude Code:**
+## 5. (Optional) GitHub OAuth app — for the "Connect GitHub" flow
+Each deployment uses **its own** GitHub OAuth app (secrets can't be shared, and the callback is
+host-specific — so there's no shared central app for self-hosters):
+1. GitHub → Settings → Developer settings → **OAuth Apps → New OAuth App**.
+2. **Authorization callback URL:** `https://<your-app>.up.railway.app/api/github/callback`
+3. Set `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET` in Railway.
+
+Skip this entirely if you use the URL + token path in step 4.
+
+## 6. Connect agents to the MCP
+Dashboard → **Connect** → copy the command. Agents always hit the same endpoint and only ever
+see the **active** vault:
```bash
claude mcp add --transport http cortex https://<your-app>.up.railway.app/api/mcp \
- --header "Authorization: Bearer $MCP_TOKEN"
-```
-**Hermes** (`~/.hermes/config.yaml`):
-```yaml
-mcp_servers:
- cortex:
- url: https://<your-app>.up.railway.app/api/mcp
- headers:
- Authorization: "Bearer <MCP_TOKEN>"
+ --header "Authorization: Bearer <token from the Connect page>"
```
## Notes
-- **No auth locally:** leave `AUTH_SECRET` empty (or `AUTH_DISABLED=true`) and the dashboard is open.
-- **Security:** never expose the MCP without `MCP_TOKEN`. Rotate `GIT_TOKEN` if leaked.
+- **No auth locally:** leave `AUTH_SECRET` empty (or `AUTH_DISABLED=true`) and the dashboard is open; the MCP is open until a token exists.
+- Git tokens are stored **encrypted** at rest (keyed off `AUTH_SECRET`); token hashes and vault clones live under `CORTEX_DATA_DIR`, never in a vault repo.
diff --git a/app/(app)/workspaces/page.tsx b/app/(app)/workspaces/page.tsx
index 909ad1a..fe0b9e2 100644
--- a/app/(app)/workspaces/page.tsx
+++ b/app/(app)/workspaces/page.tsx
@@ -31,6 +31,7 @@ export default function WorkspacesPage() {
const { mutate } = useSWRConfig();
const [busy, setBusy] = useState<string | null>(null);
const [err, setErr] = useState("");
+ const [manual, setManual] = useState({ url: "", token: "", name: "" });
const repos = reposData?.repos ?? [];
const addedNames = new Set(repos.map((r) => r.fullName));
@@ -51,6 +52,31 @@ export default function WorkspacesPage() {
setBusy(null);
}
}
+ async function addManual() {
+ if (!manual.url.trim()) return;
+ setBusy("manual");
+ setErr("");
+ try {
+ const res = await fetch("/api/repos", {
+ method: "POST",
+ headers: { "content-type": "application/json" },
+ body: JSON.stringify({
+ cloneUrl: manual.url.trim(),
+ token: manual.token.trim() || undefined,
+ name: manual.name.trim() || undefined,
+ }),
+ });
+ const d = await res.json();
+ if (!res.ok) setErr(d.error || "add failed");
+ else {
+ setManual({ url: "", token: "", name: "" });
+ refresh(mutate);
+ }
+ } finally {
+ setBusy(null);
+ }
+ }
+
async function switchTo(id: string) {
await fetch("/api/repos/active", { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify({ id }) });
refresh(mutate);
@@ -123,9 +149,48 @@ export default function WorkspacesPage() {
)}
</section>
+ <section className="mt-8 space-y-2">
+ <h2 className="text-sm font-medium">Add a repo by URL + token</h2>
+ <p className="text-sm text-muted-foreground">
+ Paste a repo URL and a GitHub token with access to it. Works without connecting GitHub — the
+ zero-setup path for self-hosting.
+ </p>
+ {err && <p className="text-xs text-destructive">{err}</p>}
+ <div className="space-y-2">
+ <input
+ value={manual.url}
+ onChange={(e) => setManual((m) => ({ ...m, url: e.target.value }))}
+ placeholder="https://github.com/you/vault.git"
+ className="w-full rounded-md border border-border bg-background px-2.5 py-1.5 text-sm outline-none placeholder:text-muted-foreground"
+ />
+ <input
+ value={manual.token}
+ onChange={(e) => setManual((m) => ({ ...m, token: e.target.value }))}
+ type="password"
+ placeholder="GitHub token with repo access (for private repos / push)"
+ className="w-full rounded-md border border-border bg-background px-2.5 py-1.5 text-sm outline-none placeholder:text-muted-foreground"
+ />
+ <div className="flex gap-2">
+ <input
+ value={manual.name}
+ onChange={(e) => setManual((m) => ({ ...m, name: e.target.value }))}
+ placeholder="name (optional)"
+ className="w-56 rounded-md border border-border bg-background px-2.5 py-1.5 text-sm outline-none placeholder:text-muted-foreground"
+ />
+ <button
+ onClick={addManual}
+ disabled={busy === "manual"}
+ className="rounded-md bg-primary px-3 py-1.5 text-sm font-medium text-primary-foreground disabled:opacity-50"
+ >
+ {busy === "manual" ? "Adding…" : "Add repo"}
+ </button>
+ </div>
+ </div>
+ </section>
+
{gh?.connected && (
<section className="mt-8 space-y-2">
- <h2 className="text-sm font-medium">Add a repo</h2>
+ <h2 className="text-sm font-medium">Add from GitHub</h2>
{err && <p className="text-xs text-destructive">{err}</p>}
<div className="scrollbar-none max-h-96 overflow-y-auto overflow-hidden rounded-lg border border-border">
<table className="w-full text-sm">
diff --git a/app/api/repos/route.ts b/app/api/repos/route.ts
index 7a66d89..a168304 100644
--- a/app/api/repos/route.ts
+++ b/app/api/repos/route.ts
@@ -9,17 +9,23 @@ export function GET() {
}
export async function POST(req: Request) {
- const { fullName, cloneUrl, branch, setActive } = await req.json().catch(() => ({}));
- const url = cloneUrl || (fullName ? `https://github.com/${fullName}.git` : "");
- if (!url) return Response.json({ error: "cloneUrl or fullName required" }, { status: 400 });
+ const b = await req.json().catch(() => ({}));
+ const url = b.cloneUrl || b.url || (b.fullName ? `https://github.com/${b.fullName}.git` : "");
+ if (!url) return Response.json({ error: "repo url or fullName required" }, { status: 400 });
+ // "owner/repo" derived from the URL, for a nice default name.
+ const derived = String(url)
+ .replace(/^https?:\/\/[^/]+\//, "")
+ .replace(/^git@[^:]+:/, "")
+ .replace(/\.git$/, "");
try {
const repo = await addRepo({
- name: fullName || url,
- fullName,
+ name: b.name || b.fullName || derived || url,
+ fullName: b.fullName || (derived.includes("/") ? derived : undefined),
url,
- token: githubToken() ?? undefined,
- branch,
- setActive,
+ // Explicit pasted token (PAT path) wins; else the OAuth-connected token.
+ token: b.token || githubToken() || undefined,
+ branch: b.branch,
+ setActive: b.setActive,
});
rebuildIndex();
return Response.json({ ok: true, repo });