BusinessOS

BusinessOS is the local-first desktop operating layer for running a business. It gives each workspace its own modules, apps, windows, roles, teams, and operational records.

Optimal Engine supplies governed knowledge, memory, search, and context. BusinessOS supplies the interface where people and agents use that context to perform work.

Start Here

The supported source-development path is:

git clone https://github.com/Miosa-osa/businessos-5.git
cd businessos-5
make onboard

make onboard performs the complete first run:

1. Checks every required tool and reports exact installation guidance.
2. Creates local environment files without replacing existing configuration.
3. Initializes an isolated PostgreSQL cluster under .run/.
4. Creates the local BusinessOS database when it is absent.
5. Starts isolated Redis and Optimal Engine services.
6. Installs frontend and desktop dependencies.
7. Builds and starts the Go backend, SvelteKit frontend, and Electron shell.
8. Verifies database migrations, schema health, service readiness, and the desktop process.

The first run downloads dependencies and Electron, so it takes longer than later starts.

Prerequisites

Use the versions declared by the repository where possible.

Tool	Required version	Purpose
Node.js	22	Frontend and Electron
pnpm	9.15.4	Frontend package manager
Go	1.26.2	Backend
PostgreSQL	14 or newer	Operational database
Redis	7 or newer	Cache, sessions, and coordination
Elixir and Mix	Current stable	Bundled Optimal Engine
Python	3	Detached local process launcher

On macOS:

brew install node@22 go postgresql@16 redis elixir python
corepack enable
corepack prepare pnpm@9.15.4 --activate

Do not start global PostgreSQL or Redis services for BusinessOS. The launcher runs isolated instances on repository-specific ports.

Daily Development

make dev-local           # Start the stack
make dev-local-verify    # Prove every required service is healthy
make dev-local-status    # Show service state and ports
make dev-local-logs      # Follow application logs
make dev-local-restart   # Restart after pulling changes
make dev-local-stop      # Stop services and preserve data

Default local endpoints:

Service	URL
Frontend	http://localhost:5273
Backend	http://localhost:8801
Optimal Engine	http://localhost:4200
PostgreSQL	127.0.0.1:25432
Redis	127.0.0.1:26379

Edit .env.dev to change local ports. The launcher synchronizes those values into generated frontend and backend environment files.

Local Data

Local runtime state lives under .run/. It is ignored by Git and preserved across normal stops and restarts.

Do not delete .run/pgdata to fix a startup problem. That directory contains the local PostgreSQL database.

The backend owns the migration ledger. Do not manually apply individual migration files or replay schema.sql against an existing database.

Use:

make db-schema-check
make check-schema

Authentication and Team Access

A clean local installation can create and use local accounts without shared secrets.

Google sign-in and Google integrations require OAuth credentials supplied out-of-band. Never commit OAuth credentials, API keys, database credentials, or generated environment files.

The canonical Google authentication callback is:

http://localhost:8801/api/auth/google/callback

Tool integrations have their own exact callback URLs. See Team Onboarding before configuring them.

Connect Optimal Engine

The launcher uses an engine already running on port 4200 when one is available. Otherwise, it starts the bundled engine with clean local data under .run/optimal-engine-data.

Inside BusinessOS:

1. Open Settings.
2. Select Optimal Engine.
3. Choose the built-in local engine or configure an existing engine URL.
4. Test the connection.
5. Select the engine workspace mapped to the BusinessOS workspace.

BusinessOS must never bundle Roberto's private OptimalOS data. Each downloaded installation starts with its own clean local engine.

Architecture

Electron desktop shell
        |
SvelteKit frontend :5273
        |
Go backend :8801
   |             |
PostgreSQL     Redis
   |
Optimal Engine :4200

Core directories:

desktop/             Electron shell and Go backend
frontend/            SvelteKit application
optimal-engine/      Optimal Engine subtree and SDKs
workspaces/          Workspace templates and private projections
docs/                Architecture, development, deployment, and operations
scripts/             Setup, verification, build, and release automation

Tests

make test-dev-local-launcher
make test-backend
make test-frontend
make check-schema

Before handing work to another developer, run:

make dev-local-verify
make test

Docker

Docker is an alternative deployment-shaped development path. It is not the primary Electron development workflow.

make setup
make status
make logs
make down

Documentation

• Documentation Index
• Developer Quick Start
• Team Onboarding
• Common Issues
• Local Runtime SOP
• Workspace and Engine Routing
• Contributing
• Security

Repository Policy

This repository contains private product and workspace material. The open-source mirror is produced through the governed sync workflow and .oss-exclude.

Licensing terms for redistributed components must be confirmed before publishing a release.