Skip to content

getting-started.md

Latest commit

 

History

History
145 lines (99 loc) · 3.99 KB

getting-started.md

File metadata and controls

145 lines (99 loc) · 3.99 KB
Raw

Getting Started

Prerequisites

margin has two parts: a backend (AI engine) and a frontend (editor interface). You'll need both running.

Backend (Python)

  • Python 3.10 or newer

    python --version      # macOS / Linux
python --version      # Windows (or python3 if using the Windows store alias)

    If you don't have Python, download it from python.org.

Frontend (Node.js)

  • Node.js 18 or newer

    node --version

    Download from nodejs.org if needed.

AI Provider (pick one)

margin needs an AI model to power its writing assistant. You have two options:

Option A -- Local (Private, Offline) Run a model entirely on your machine. No internet required, no data leaves your computer.

  • Ollama -- runs on http://localhost:11434
  • LM Studio -- runs on http://localhost:1234
  • Any OpenAI-compatible local server

Option B -- Cloud API Use an online provider. Your content is sent to their servers for processing.

All cloud providers require an API key. margin stores it securely in your local settings file.

::: tip You don't need to edit .env files -- everything is configured inside margin's settings UI. :::

Installation

Step 1: Clone the repository

git clone https://github.com/prxshetty/margin.git
cd margin

Step 2: Set up the backend

margin includes startup scripts that handle everything automatically. Pick the right one for your OS:

::: code-group

./start.sh
start.bat          # double-click, or run in cmd
powershell -ExecutionPolicy Bypass -File start.ps1

:::

The script will:

  1. Create a Python virtual environment (if one doesn't exist)
  2. Install Python dependencies
  3. Install frontend dependencies
  4. Launch both the API server and the editor UI in parallel

Manual setup (optional)

If you prefer to run things step by step:

::: code-group

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000
python -m venv .venv
.venv\Scripts\activate
pip install -r requirements.txt
copy .env.example .env
uvicorn api.main:app --reload --host 0.0.0.0 --port 8000

:::

The backend will be available at http://localhost:8000.

Step 3: Set up the frontend

If you used the startup script, this is already done. Otherwise, open a new terminal window and run:

cd ui
npm install
npm run dev

The editor will open at http://localhost:5173.

Step 4: Configure your AI provider

  1. Open margin in your browser.
  2. Click the gear icon to open Settings.
  3. Go to Endpoints tab.
  4. Choose your AI provider:
    • Click Add New Endpoint, give it a name (e.g., "Ollama"), enter the URL, and click Save Endpoint (or Import from .env if you already configured one in your .env file).
  5. Click Test Connection to verify everything works.
  6. Pick your endpoint as active from the assistant panel's harness menu (Endpoint flyout).

Step 5: Start writing

The default workspace (sample-workspace) is loaded automatically. It includes sample characters, a chapter, and style presets so you can start experimenting right away.

You can link your own workspace folder from Settings > Workspaces (or the workspace switcher in the file sidebar header).

Next Steps