Magent/docs/LOCAL_DEVELOPMENT.md

Foreground installation: Linux, macOS and Windows

This runs Magent directly from source without Docker or Portainer. It is useful for local evaluation and development; closing the terminals stops the services. For a Linux service that starts at boot, use native production. No Windows Service or macOS launchd package is supplied. Use a private local directory, not a shared/synced folder containing real production data.

Install Python 3.14, Node.js 24 with npm, and Git. The commands below are split by shell; do not paste Bash line continuations into PowerShell. Do not connect a development checkout to production credentials/databases.

Get the source and dependencies

Linux/macOS (Bash/zsh):

git clone --branch release --single-branch https://git.amslabs.net/Rephl3x/Magent.git magent
cd magent
python3.14 -m venv .venv
.venv/bin/python -m pip install -r backend/requirements.txt

Windows (PowerShell, with Python's py launcher installed):

git clone --branch release --single-branch https://git.amslabs.net/Rephl3x/Magent.git magent
Set-Location magent
py -3.14 -m venv .venv
& .\.venv\Scripts\python.exe -m pip install -r backend\requirements.txt

If py is unavailable, use the full path to your Python 3.14 executable instead. No activation script or machine-wide execution-policy change is required. Confirm node --version reports 24.x. Native dependency installation may need compiler prerequisites when wheels are unavailable for your CPU/OS.

Configure the backend

For a fresh local database, generate three independent values in your private terminal. Replace python3.14 below with py -3.14 on Windows:

python3.14 -c "import secrets; print(secrets.token_urlsafe(48))"
python3.14 -c "import secrets; print(secrets.token_urlsafe(48))"
python3.14 -c "import base64,secrets; print(base64.urlsafe_b64encode(secrets.token_bytes(32)).decode())"

The first is JWT_SECRET, the second is SETUP_TOKEN, and the third is SETTINGS_ENCRYPTION_KEY. Do not paste them into chat/logs/issues. In an editor, create backend/.env with the following contents, replacing all three placeholders:

JWT_SECRET=PASTE_FIRST_RANDOM_VALUE
SETUP_TOKEN=PASTE_SECOND_RANDOM_VALUE
SETTINGS_ENCRYPTION_KEY=PASTE_THIRD_RANDOM_VALUE
MAGENT_MANAGED_SECRETS=false
MAGENT_APPLICATION_URL=http://127.0.0.1:3000
CORS_ALLOW_ORIGIN=http://127.0.0.1:3000
AUTH_COOKIE_SECURE=false
API_DOCS_ENABLED=false
SQLITE_PATH=data/magent.db
LOG_FILE=data/magent.log
BRANDING_SOURCE=data

On Linux/macOS restrict the file with chmod 600 backend/.env and use a private checkout (umask 077 before creating local data). On Windows restrict the folder and .env to your account using NTFS security permissions; Unix chmod is not a substitute for Windows ACLs. The repository ignores backend/.env and backend/data/, but Git ignore rules are not encryption or access control.

Use the same keys and database when restarting. Do not recreate .env during an upgrade. For isolated testing without background imports, add BACKGROUND_TASKS_ENABLED=false; omit it for normal operation after setup. Keep ADMIN_PASSWORD and MAGENT_RUNTIME_MANAGED unset.

These examples deliberately use 127.0.0.1, not localhost. Open that exact origin in the browser; mixing the names can break origin checks/cookies.

Terminal 1: start the API

Start in the checkout root. The working directory below puts all local data in backend/data. --env-file explicitly loads the private file; the application does not discover it automatically.

Linux/macOS:

cd backend
../.venv/bin/python -m uvicorn app.main:app --env-file .env --host 127.0.0.1 --port 8000 --workers 1

Windows PowerShell:

Set-Location backend
& ..\.venv\Scripts\python.exe -m uvicorn app.main:app --env-file .env --host 127.0.0.1 --port 8000 --workers 1

Leave this process running. There must be only one backend instance using the database. --reload is intentionally not used for installation/restore checks.

Terminal 2: build and start the web frontend

Open a second terminal at the checkout root. The API address must be set before building because it is compiled into the frontend's rewrites. The application URL must also be present in the frontend runtime for this deliberate HTTP mode. Do not load the backend .env into this terminal.

Linux/macOS:

cd frontend
export BACKEND_INTERNAL_URL=http://127.0.0.1:8000
export NEXT_PUBLIC_API_BASE=/api
export NEXT_TELEMETRY_DISABLED=1
export MAGENT_APPLICATION_URL=http://127.0.0.1:3000
npm ci --include=dev
NODE_ENV=production npm run build
cp -R public .next/standalone/
cp -R .next/static .next/standalone/.next/
HOSTNAME=127.0.0.1 PORT=3000 NODE_ENV=production node .next/standalone/server.js

Windows PowerShell:

Set-Location frontend
$env:BACKEND_INTERNAL_URL = 'http://127.0.0.1:8000'
$env:NEXT_PUBLIC_API_BASE = '/api'
$env:NEXT_TELEMETRY_DISABLED = '1'
$env:MAGENT_APPLICATION_URL = 'http://127.0.0.1:3000'
$env:NODE_ENV = 'production'
npm.cmd ci --include=dev
npm.cmd run build
Copy-Item -LiteralPath public -Destination .next\standalone\ -Recurse -Force
Copy-Item -LiteralPath .next\static -Destination .next\standalone\.next\ -Recurse -Force
$env:HOSTNAME = '127.0.0.1'
$env:PORT = '3000'
node .next\standalone\server.js

Only continue to the next command after the previous one succeeds. The standalone server needs both copied asset directories; a successful HTML response without them can still produce an unstyled, unusable page.

For actual frontend development, stop the standalone server and use npm run dev -- --hostname 127.0.0.1 --port 3000 with the same backend/public URL variables. On PowerShell set $env:NODE_ENV = 'development' first and use npm.cmd run dev -- --hostname 127.0.0.1 --port 3000; on POSIX prefix the command with NODE_ENV=development. Do not expose the development server publicly or treat a dev-mode test as a production-build test.

Verify, set up and retain data

Open http://127.0.0.1:3000/api/health (expect {"status":"ok"}), then http://127.0.0.1:3000/setup. Enter your SETUP_TOKEN, create the administrator and configure apps. The setup help dialog's container command is not used here; use the token from your manual .env. Remove only SETUP_TOKEN after creating the administrator and restart the API.

Inspect the browser console/network panel for failed scripts, styles or API requests. Check /api/setup/status and a successful sign-in. Restart both processes and verify the account and settings remain; do not create a second database accidentally by starting the backend from a different directory.

Ctrl+C stops each process. Keep backend/data and backend/.env together for this local installation. Source deletion, git clean or a new checkout does not preserve untracked data for you. For upgrades, back up first, stop both processes, update the source/dependencies, rebuild and copy the frontend assets again, then restart with the original state and keys.

Portable backup/restore works here too. Restart the API process after staging a restore and recheck the destination URL. Take offline snapshots only while the backend is stopped. To move a trial into production, follow the native/container guide for a fresh destination and restore a compatible encrypted backup; do not copy a Windows venv or native frontend dependencies into a Linux installation.