Deep Notes — Setup & Operation Guide

Deep Notes is a local first notes app designed for pentesting/CTFs with the following features:

• Markdown editor and toolbar (bold, italic, headers, lists, code)
• Screenshot uploads (served locally and included in exports)
• Always-on AI chatbox (Hugging Face Inference Router)
• Preview modal for clean read-only view
• Export to a single self-contained HTML (images embedded)
• SQLite storage

1. Prerequisites

• Node.js 18+ (Node 20 or 22 recommended)
• npm 9+
• macOS, Linux, or Windows
• Internet access to call Hugging Face Inference Router

2. Hugging Face Account and Token

1. Create an account at https://huggingface.co/ if you don’t already have one.
2. Go to https://huggingface.co/settings/tokens and create a new token.
3. Choose token type “Fine-grained”.
4. Set permissions: enable only “Inference → Make calls to Inference Providers”.
5. Copy the token value hf_....

3. Environment Configuration

Firstly ensure you are in the server directory. Create server/.env with the following:

Commnds:

cp .env.example .env

nano .env

Ensure the .env has the following:

HF_TOKEN=hf_...your_token_here HF_BASE_URL=https://router.huggingface.co/v1 HF_MODEL=DeepHat/DeepHat-V1-7B:featherless-ai PORT=3001 DB_FILE=./ctf-notes.db

Notes:

• HF_TOKEN is required.
• PORT controls the server port.
• DB_FILE points to the SQLite database.

4. Production Mode

Build and run: npm install

npm run build

npm start

This serves both API and frontend at http://localhost:3001.

Health endpoint: http://localhost:3001/api/healthz returns {"ok":true}.

Screenshots are available at /uploads.

5. Using Deep Notes

• Create a note: click “New Note”.
• Edit note with Markdown toolbar.
• Upload screenshots: drag/drop or click “Upload screenshot”.
• Screenshots appear under “Screenshots”.
• Ask AI: type in the chatbox or highlight text and click “Ask DeepHat (HF)”.
• Preview: click “Preview” for a clean modal view.
• Export: click “Export” to download a standalone HTML file with embedded screenshots.
• Delete: click “Delete” to remove a selected note.

6. Data Storage

• Notes are stored in SQLite: server/ctf-notes.db
• Screenshots stored in server/uploads/
• To back up: copy both the database and uploads folder.

7. Troubleshooting

Black screen in client:

• Check console logs.
• Ensure index.html has
  .
• Ensure main.tsx mounts to #root.

Client proxy errors (ECONNREFUSED):

• Ensure server is running on PORT=3001.
• Open http://localhost:3001/api/healthz to verify.
• Ensure vite.config.ts has: proxy: { '/api': 'http://localhost:3001', '/uploads': 'http://localhost:3001' }

Screenshots not visible:

• Uploader must POST to /api/upload/attach/:noteId.
• Ensure attachments route is mounted in server/index.ts.
• Ensure express.static is serving /uploads.
• Verify by opening http://localhost:3001/uploads/.

TypeScript missing type errors:

• Client: npm i -D @types/markdown-it
• Server: npm i -D @types/better-sqlite3

Production server import error:

• Ensure server/package.json has no "type": "module".
• Ensure tsconfig.json uses "module": "CommonJS".
• Rebuild with npm run build.

Port conflicts:

• Change PORT in server/.env and match vite.config.ts proxy.