euler

Quick start · How it works · Deploy · Development · Data and settings

Home is the launcher and avatar editor. Saving an avatar updates Euler's logo and the dock's Home icon; app icons keep their identities.

Quick start

Install Node.js 24 and Git. Node 22.13 or newer is supported. These commands work on Windows, macOS, and Linux:

git clone https://github.com/quirq-ai/euler.git
cd euler
npm ci
npm run setup
npm run build
npm start

Open http://localhost:2713. All three apps are enabled initially. Stop Euler with Ctrl+C in its terminal; closing the browser tab leaves it running.

Step	What it does
npm ci	Installs the root Nx and package-manager tools.
npm run setup	Installs each app from its committed lockfile.
npm run build	Compiles enabled apps for their /app/<name> routes.
npm start	Starts one HTTP server and mounts the enabled builds.

The app sources and routing changes are already included. No sibling repositories or patch-preparation step is required. For another port, use npm start -- --port 2800.

How it works

flowchart TB
    Browser["Browser · localhost:2713"] --> Euler["Euler · one Node.js server"]
    Euler --> Home["Home /<br/>Launcher + avatar editor"]
    Euler --> Manage["Manage /manage<br/>Enable · start · stop · logs"]
    Euler --> Innernet["/app/innernet<br/>Next.js pages + APIs"]
    Euler --> Quitter["/app/quitter/<br/>Built Vite app"]
    Euler --> Instants["/app/instants<br/>Next.js pages + APIs"]
    Dock["Shared floating dock<br/>Home · running apps · opacity"] -. "on every page" .-> Home
    Dock -.-> Manage
    Dock -.-> Innernet
    Dock -.-> Quitter
    Dock -.-> Instants
    style Euler fill:#dceaff,stroke:#5b82bc,color:#14253f
    style Dock fill:#e9e4fa,stroke:#8978b6,color:#302547

Apps render directly under Euler's address. Their page, asset, and API URLs stay within their own prefix; for example, Innernet's suggestions endpoint is /app/innernet/api/suggest. Euler dispatches to prepared Next.js handlers or built static files inside the same process.

The dock is added to HTML pages. API responses, assets, and React server component streams retain their original content. Switching uses normal links, enhanced by native document transitions where supported. The dock remembers each tab's last app route and window scroll position; arbitrary unsaved forms or component state may reset when navigating.

Use the workspace

Control	Behavior
Home	Launch running apps and customize Euler's avatar.
Dock appearance	Adjust the glass background opacity from 20–100%.
Manage apps	Open lifecycle controls at /manage.
Enable in Euler	Apply availability immediately and remember it for startup and default builds.
Start / Stop	Mount or unmount an app's existing build.
Restart	Reactivate the prepared build. Source changes still require rebuilding.
Logs	Inspect recent lifecycle output and errors.

Each app can be controlled separately. Home and the app pages retain the same dock.

Use Alt+0 for Home, Alt+1…9 for running apps, and arrow keys to move between focused dock items. Reduced-motion preferences are respected.

Deployment

Choose whether you need the complete Euler workspace or an independently hosted app. The current Euler host is designed for loopback access and local persistent storage. The deployment options below reflect that implementation.

Destination	What works with this repository	Instructions
Your Windows, macOS, or Linux machine	Complete Euler workspace	Quick start
Linux VM / VPS with SSH and persistent disk	Complete Euler workspace through a private SSH tunnel	Full Euler on a server
Vercel	Separate Quitter, Innernet demo, and Instants browser-session deployments	Vercel
Netlify / Cloudflare Pages	Standalone Quitter static app	Static hosts
Public container/PaaS services	Full Euler needs a hosting adapter first	Public hosting limits

Full Euler on a Linux server

Use a persistent Linux VM with Node 24, Git, and SSH access: for example, a DigitalOcean Droplet, Hetzner VM, AWS EC2 instance, or your own Linux server. Run as a normal account. Innernet indexes files on that server, not files on the computer viewing it.

1. Connect over SSH and run the quick-start commands on the server. Keep Euler's port bound to loopback.

2. In a terminal on your own computer, open a tunnel:

   ssh -N -o ExitOnForwardFailure=yes -L 127.0.0.1:2713:127.0.0.1:2713 user@your-server
   

3. Browse http://127.0.0.1:2713 on your computer. Keep the tunnel open while using Euler. You only need SSH exposed by the server; port 2713 stays private.

The forwarded port must match Euler's configured port because its request checks include the port. Stop another local Euler instance before opening this tunnel, or choose the same alternate port on both ends. See OpenSSH local forwarding.

On a Linux system with a systemd user session, first stop any foreground Euler process. Run the following from the built repository's root. The unit captures the current checkout and Node paths, including version-manager installations:

mkdir -p ~/.config/systemd/user
cat > ~/.config/systemd/user/euler.service <<EOF
[Unit]
Description=Euler app workspace
After=network.target

[Service]
Type=simple
WorkingDirectory=$PWD
ExecStart="$(command -v node)" "$PWD/bin/euler.mjs"
Environment=NODE_ENV=production
Restart=on-failure
RestartSec=5

[Install]
WantedBy=default.target
EOF
systemctl --user daemon-reload
systemctl --user enable --now euler

To keep the user service running after logout, an administrator can enable lingering for your account:

sudo loginctl enable-linger "$(id -un)"

Useful commands:

systemctl --user status euler
journalctl --user -u euler -f
systemctl --user stop euler
systemctl --user start euler

If you change the Node installation path, regenerate the unit and reload it. Reference: systemd service units.

For updates, stop the service, run git pull --ff-only, npm ci, npm run setup, and npm run build in the checkout, then start the service. Preserve the data directories across updates and backups.

Vercel: individual apps

The complete Euler host is not currently supported as a Vercel deployment by this repository. The app folders can be deployed as separate Vercel projects. Each gets its own URL and standalone app behavior; the Euler Home, shared dock, and host controls are not part of those deployments.

Import quirq-ai/euler once for each app you want. Select production branch main, Node 24.x, and the following settings. Root Directory is relative to the Git repository; build/output paths are relative to that app directory.

App	Root Directory	Framework	Install command	Build command	Output
Quitter	apps/quitter	Vite	npm ci	npm run build	dist
Innernet	apps/innernet	Next.js	npx --yes pnpm@9.12.3 install --frozen-lockfile	npm run build	Next.js default
Instants	apps/instants	Next.js	npm ci	npm run build	Next.js default

Use each app's build script, not the repository-root Euler build command. Leave QUIRQ_BASE_PATH, QUIRQ_DIST_DIR, INNERNET_BASE_PATH, INNERNET_DIST_DIR, INSTANTS_BASE_PATH, and INSTANTS_DIST_DIR unset: standalone deployments use / and their normal build output. Clear stale framework/output overrides when reusing an old Vercel project.

Keep Enable access to System Environment Variables turned on in the Vercel project's Environment Variables settings. Innernet and Instants use Vercel's VERCEL variable to select their hosted behavior. See Vercel system environment variables.

• Quitter: deploys its in-memory demonstration UI. It has no production collaboration backend.
• Innernet: Vercel selects public demo mode and uses the committed data/demo/index.json. It does not index your computer. No database is needed for the bundled demo; optional Neon configuration is described in the Innernet README.
• Instants: on Vercel, the existing adapter keeps the session journal in browser storage. It is a device-local prototype, not shared team persistence. See the Instants README.

After deployment, open the app, inspect browser/network errors, and refresh a nested route. For Instants, make a sample change and refresh to confirm browser persistence. Hosting instructions are provided here; this repository does not provision your Vercel projects or credentials.

Reference: Vercel monorepos and build configuration.

Netlify and Cloudflare Pages

Quitter is a static Vite app, so it can also be published independently:

Setting	Netlify	Cloudflare Pages
Repository	quirq-ai/euler	quirq-ai/euler
Production branch	main	main
Base / root directory	apps/quitter	apps/quitter
Build command	npm run build	npm run build
Publish / output directory	dist	dist
Build Node version	NODE_VERSION=24	NODE_VERSION=24

Set Netlify's Base directory explicitly to apps/quitter, so dependencies are installed there; it is not enough to select only its Package directory. The publish directory is relative to that base. Keep QUIRQ_BASE_PATH and QUIRQ_DIST_DIR unset. These deployments do not include Euler's Node server, dock, or the two Next.js apps.

Reference: Netlify monorepo settings and Cloudflare Pages build settings.

Public hosting limits

Euler currently binds to 127.0.0.1, accepts loopback Host/Origin values, and stores enabled settings and app data on local disk. It has no user-account or multi-tenant authentication layer. Setting a provider's PORT variable alone does not configure this host; use its explicit --port option for private deployments.

A full public deployment on Vercel, Render, Railway, Fly.io, or another container/function platform needs an intentional adapter: public-address and origin handling, authentication, durable app storage, and a deployment lifecycle suitable for the host's in-process Next runtimes. This repository does not yet supply that adapter or a ready-to-deploy container image. Use the private VM recipe for complete Euler today.

Development

The repository owns its manifest and app sources:

euler/
├── bin/euler.mjs           # executable
├── euler.workspace.json   # apps and build commands
├── nx.json                # task orchestration
├── src/                   # HTTP host, builds, settings, dock injection
├── public/                # Home, avatar editor, controls, shared dock
├── apps/
│   ├── innernet/           # Next.js
│   ├── quitter/            # Vite + React
│   └── instants/           # Next.js
└── tests/                 # host regression tests

Command	Purpose
npx nx show projects	List the host and three app projects.
npx nx run euler-app:start	Start Euler.
npx nx run euler-app:build	Build enabled apps.
npx nx run euler-innernet:build	Build Innernet for its Euler route.
npx nx run euler-quitter:dev	Start standalone Quitter development.
npm run build -- --app instants	Build one app even if disabled; leave its enabled setting unchanged.
npm test	Run the host test suite.

You can also cd apps/quitter and run npm run dev, or use the other apps' own commands. Standalone development uses the app's original port and root path. Euler builds go into .next-euler or dist-euler to keep development output separate. Stop Euler before rebuilding a build it is serving.

npm start resolves euler.workspace.json from this repository, regardless of your terminal's current directory. Use --workspace /path/to/euler or --config /path/to/euler.workspace.json to choose a custom installation. Nx runtime/build targets disable caching because local settings and data affect their