GitHub - tam159/next-role: 🚀 Level up your career with GenAI. 📄 Tailor your CV to any JD, 🔍 automate company research, and 🗓️ generate custom interview prep plans for your next role or internal promotion.

Shell-command approval. Risky execute (bash) commands pause in the UI for approve / edit / reject; a conservative read-only allowlist auto-approves trivial pokes. The gate applies in both sandbox modes below — isolation contains blast radius, not exfiltration or API misuse. On by default — set CAREER_AGENT_EXECUTE_APPROVAL=false only for offline evals or emergency rollback (env changes need docker compose up -d backend to recreate, not restart). Full policy in backend/agents/career_agent/README.md.

Sandbox. SANDBOX_PROVIDER picks where execute commands (and rendercv renders) run. local (default) executes on the backend host — right for local dev and a trusted team, zero extra moving parts. e2b runs every command in an isolated remote microVM over the E2B API: point SANDBOX_E2B_API_URL at a self-hosted CubeSandbox (open source, Apache-2.0 — your data never leaves your infra; provisioning + template guide in deploy/cubesandbox/), or leave it empty to use E2B Cloud with the same code path. CubeSandbox requires its own Linux host (custom PVM kernel or native KVM), so it is reached over HTTP rather than run inside docker compose.

Object storage. Binary artifacts (uploads + rendered PDFs) live in S3-compatible object storage. Locally that's the compose object-store service (SeaweedFS) and the presets work as-is: S3 API on OBJECT_STORE_LOCAL_PORT, a browsable bucket UI on OBJECT_STORE_UI_LOCAL_PORT, and placeholder credentials that the local emulator accepts but doesn't enforce. For the cloud, point OBJECT_STORE_ENDPOINT / OBJECT_STORE_BUCKET / credentials at a managed bucket — AWS S3, GCS, Azure, or any S3-compatible store — with no code changes. Note: the AWS_* variables are reserved for Bedrock models; the object store reads only OBJECT_STORE_*.

Secrets live only in .env (gitignored); gitleaks runs on every commit.

Models are swappable at runtime — no rebuild. Open the in-app Configuration dialog and set Main agent / Subagents to a <provider>:<model> string (e.g. anthropic:claude-sonnet-5); leave blank to use the defaults. Settings persist in your browser's local storage.

Recommended: Claude Sonnet 5, GPT-5.x, or Gemini 3.x — e.g. anthropic:claude-sonnet-5, openai:gpt-5.6-terra, google_genai:gemini-3.5-flash.

Run it for free or fully local:

• Tavily and LlamaCloud both include a generous monthly free tier — plenty for local use.
• Google AI Studio offers a free tier for Gemini flash / lite models.
• Fully local — point OPENAI_API_BASE at LM Studio or Ollama (both expose an OpenAI-compatible API) and fill your local model in the UI.

Output quality tracks the model you pick — smaller local models trade some quality for zero cost.

• Code edits hot-reload in both containers — just save the file.
• Add a frontend dep: pnpm --dir frontend add <pkg> → docker compose restart frontend
• Add a backend dep: uv add <pkg> → docker compose up -d --build backend
• Change .env: docker compose restart <service>
• Stop: docker compose down (add -v to wipe the DB, Redis & object-storage volumes)

1. Intake — the agent asks for your CV, the JD (file, URL, or pasted text), your prep timeline, and any extra context.
2. Process documents — uploads are parsed to markdown via LlamaParse (parse_document); JD URLs are pulled via Tavily (extract_jd). Results land in /processed/, alongside a persisted intake note.
3. Research — the hiring-recon subagent gathers company + role intel and a match analysis → /research/<resume>/<jd>.md.
4. Tailor & coach (parallel) — resume-tailor rewrites the CV as a rendercv YAML and renders a PDF; interview-coach writes a structured prep doc (self-intro + per-round STAR stories).
5. Battlecard — the main agent assembles a one-page-per-round JSON and renders it to a day-of PDF via WeasyPrint.
6. Multi-turn updates — ask for changes in chat; the owning agent reads the existing file, preserves everything you didn't name, and re-renders.

The full procedure (file layout, update routing, source-of-truth conventions) lives in backend/agents/career_agent/README.md. Per-feature design docs are in docs/prd/ — an OKF knowledge bundle you can render as an interactive graph; see docs/prd/README.md.

The agent's behavior is configured by files, not hardcoded — making it easy to read, diff, and extend:

Subagents only receive the tools they opt into in YAML — tool whitelisting keeps interview-coach, for example, from inheriting the main agent's full toolset.

A single CompositeBackend gives the agent one virtual filesystem while routing each path prefix to the right physical store — Postgres for text artifacts, S3-compatible object storage for uploads and rendered PDFs (SeaweedFS locally; S3 / GCS / Azure in the cloud), and a shell route for execute whose scratch space holds only render working files: a host shell backend by default, or an isolated remote sandbox (CubeSandbox / E2B) with SANDBOX_PROVIDER=e2b.

flowchart LR
    Agent["Agent filesystem tools<br/>read_file · write_file · edit_file<br/>ls · glob · grep · execute"]
    CB{{"CompositeBackend<br/>routes virtual paths"}}
    Agent --> CB
    subgraph Shell["Shell default route · SANDBOX_PROVIDER"]
        SH["`execute` — local: host subprocess,<br/>/virtual/path → on-disk path ·<br/>e2b: remote E2B microVM<br/>(CubeSandbox self-hosted / E2B Cloud)<br/>renders run in a throwaway scratch dir"]
    end
    subgraph Store["StoreBackend · Postgres + pgvector"]
        ST["/memory/ · /processed/ · /research/<br/>/interview_coach/<br/>/large_tool_results/ · /workspace/"]
    end
    subgraph Obj["ObjectStoreBackend · S3-compatible<br/>SeaweedFS local · S3/GCS/Azure cloud"]
        OB["/upload/ · /tailored_resume/<br/>/interview_battlecard/"]
    end
    CB -->|default: shell + scratch| Shell
    CB -->|KV routes| Store
    CB -->|artifact routes| Obj
    Sem["Semantic memory · CAREER_AGENT.md"] -. loaded into system prompt .-> Agent
    Proc["Procedural memory · skills/*/SKILL.md"] -. loaded on demand .-> Agent
    Work["Working memory · LangGraph thread"] -. drives .-> Agent
    Store --- Epi["Episodic memory · persisted artifacts<br/>(incl. /memory/ auto-memory)"]
    Obj --- Epi

Mapped to memory types:

• Working memory — the live LangGraph conversation thread.
• Semantic memory — CAREER_AGENT.md, always in the system prompt.
• Procedural memory — skills/*/SKILL.md, loaded on demand.
• Episodic memory — persisted artifacts in Postgres + disk, including auto-memory: standing preferences saved to the /memory/ route and auto-applied across sessions.

NextRole runs zero-login single-user by default — docker compose up and start prepping, no accounts. Flip on multi-user mode for a shared or cloud deployment and every user gets private threads, files, and memory.

• Login — Google OAuth and/or email + password, via self-hosted Better Auth inside the Next.js app (its tables live in your Postgres; no third-party auth vendor).
• Isolation — the agent server verifies a short-lived JWT (JWKS) on every request; threads/runs/crons are owner-scoped in SQL (unowned → 404), and store namespaces + object keys are scoped per user (users/<id>/…). Design details in backend/ARCHITECTURE.md §8.

Enable it — set these in .env, then docker compose up -d frontend backend:

1. AUTH_ENABLED=true and BETTER_AUTH_SECRET=$(openssl rand -base64 32).

2. Create the Better Auth tables once (it owns user / session / account / jwks, separate from backend/storage/migrations/):

   AUTH_DATABASE_URL="postgresql://<POSTGRES_USER>:<POSTGRES_PASSWORD>@localhost:<POSTGRES_LOCAL_PORT>/<POSTGRES_DB>" \
   BETTER_AUTH_SECRET=<same secret> \
     pnpm --dir frontend dlx @better-auth/cli@latest migrate --config src/lib/auth/server.ts

3. LANGGRAPH_AUTH — turns on backend enforcement. (Login without this is fine for trying the UI, but provides no isolation.) One line:

   LANGGRAPH_AUTH={"path": "/deps/next-role/backend/agents/auth.py:auth", "disable_studio_auth": true, "openapi": {"securitySchemes": {"bearerAuth": {"type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Better Auth session JWT. While signed in, the frontend's GET /api/auth/token returns one."}}, "security": [{"bearerAuth": []}], "paths": {"/ok": {"GET": []}, "/info": {"GET": []}, "/metrics": {"GET": []}, "/docs": {"GET": []}}}}

   The optional "openapi" block documents auth in the API reference: /docs gets a Bearer Token field for authenticated Test Requests (paste a JWT from the frontend's GET /api/auth/token), while the public meta endpoints (/ok, /info, /metrics, /docs) stay marked auth-free.

4. Optional Google sign-in: AUTH_GOOGLE_ENABLED=true + GOOGLE_AUTH_CLIENT_ID / GOOGLE_AUTH_CLIENT_SECRET (OAuth client redirect URI http://localhost:<FRONTEND_LOCAL_PORT>/api/auth/callback/google). Email + password works without it.

Because NextRole ships its own agent server implementing the LangGraph Server API (see backend/ARCHITECTURE.md), the career_agent assistant is also reachable by other tools and agents — no extra code:

• MCP — exposed as Model Context Protocol tools at /mcp (Streamable HTTP), usable by any MCP-compliant client. → docs
• A2A — Google's Agent2Agent protocol at /a2a/{assistant_id} (JSON-RPC 2.0; message/send + message/stream). → docs
• The full server API is browsable at the /docs endpoint of your deployment.

In multi-user mode these endpoints are authentication-gated but not yet per-user authorized — disable them (disable_mcp / disable_a2a) in a shared deployment until that lands. See backend/ARCHITECTURE.md §8.

Set LANGCHAIN_API_KEY and LANGCHAIN_TRACING_V2=true in .env, and every run — each LLM call, tool call, and nested subagent — is traced at smith.langchain.com under the LANGCHAIN_PROJECT you configure. Optional, but invaluable for debugging the multi-agent flow.

# From the repo root — needs only Node.js (no install, no clone, no build):
npx --yes "https://github.com/Egonex-AI/Understand-Anything/releases/latest/download/understand-anything-viewer.tgz" .

Open the printed 🔑 Dashboard URL (include the ?token=… — the plain URL hits an access gate).

Using Claude Code? Install the understand-anything plugin and run /understand-dashboard in this repo instead.

The graph is for humans: AI coding assistants are configured to ignore .ua/ (Claude Code deny rules, .cursorignore, a CLAUDE.md instruction) so they keep reading the real source instead of a large generated snapshot.