FreeOS — a self-hosted multi-agent OS that grows its own AI workforce.

The loop · Run · License · Architecture

FreeOS is an independent open-source host. The data plane is derived from Octop (MIT). The organization control plane comes from openXYOS (Apache-2.0). They are complementary: FreeOS produces experts / assistants (not yet in a department), skills, plugins, and MCPs; those assets assemble into openXYOS as department employees; openXYOS blueprints, catalog, policies, and talent feed back into FreeOS as colleagues.

The web shell, README banner, favicons, and PWA icons use the FreeOS circular mark (gray ring, yellow / green / red teardrops, blue center).

Run the self-growth loop

This is the product path. One command compiles a blueprint into a colleague, promotes it draft → market → recruit → shadow → active, registers a FreeOS chat agent, publishes an asset pack, applies that pack onto openXYOS-shaped surfaces as department employees (live HTTP when OPENXYOS_BASE_URL is set, otherwise a durable local mirror), imports the control plane back, and proves governance still blocks high-risk tools.

git clone https://github.com/XYAIStudio/FreeOS.git
cd FreeOS
uv sync
uv run freeos org loop run

Equivalent: bash scripts/org-loop.sh.

CI / scripted proof of the same loop:

uv run pytest tests/e2e/test_org_growth_loop.py tests/unit/test_org_loop.py tests/unit/test_openxyos_apply.py tests/unit/test_colleague_spawn.py tests/unit/test_host_governance.py

When	What happens
OPENXYOS_BASE_URL unset / sidecar down	Uses tests/fixtures/org-loop/ and writes {FREEOS_HOME}/openxyos-mirror/
OPENXYOS_BASE_URL (or FREEOS_ORG_SIDECAR_URL) set	Also POST /api/freeos/ingest (employees, talent, plugins, skills) when the sidecar is healthy

High-risk tools (outbound, delete, pay, prod) are default-denied in the host tool path (OrgGovernanceMiddleware + xyos-governance-mcp). execute stays false until freeos org governance approve <id> and the agent re-checks with the same args.

Operator detail: docs/asset-loop.md.

Run FreeOS

Windows 用户：下载安装包 → 安装 → 打开即用 FreeOS（Octop壳+组织能力）

给非开发者的路径：

1. 打开 GitHub Releases，下载 FreeOS-desktop-windows-amd64-<version>.exe（普通 64 位电脑）或 FreeOS-desktop-windows-arm64-<version>.exe（ARM 电脑）。
2. 双击安装包。安装程序会放到「程序文件」并创建开始菜单和桌面快捷方式。
3. 打开 FreeOS。第一次启动会解压内置运行环境（可能要一两分钟），然后直接进入可用会话，无需先登录。
4. 保存、导出或发布到账号时再注册或登录。侧栏 Organization 使用宿主内组织能力，不必再装 Node，也不依赖本机 127.0.0.1:3780。完整 openXYOS Node 栈是可选项（导出/同步/高级部署）。

数据目录默认是 %USERPROFILE%\.freeos（可用环境变量 FREEOS_HOME 改）。旧版 Octop 的 ~/.octop 仍会被识别。卸载安装包会清空安装目录（默认为 Program Files\FreeOS）并删除快捷方式，但不会删除该用户数据目录；详见 desktop/README.md。

安装包由 CI 工作流 FreeOS Desktop Package（文件名仍是 .github/workflows/octop-desktop.yml，给现有发版脚本用）在 Windows runner 上打出来。本仓库的云环境打不出 .exe；合并后由该 job 产出。

Prerequisites

• Python 3.12+ (the project uses uv)
• Node.js 20.19+ only if you opt into the organization sidecar (FREEOS_ORG_SIDECAR=1) from source, or rebuild the dashboard. A fresh FreeOS install does not need Node.

From this repository

uv run freeos init
uv run freeos run

freeos is the product CLI. octop remains a package-compatible alias.

Open the dashboard (default listen port is printed by run, commonly http://127.0.0.1:18900). Complete the first-run wizard.

Data directory precedence:

1. FREEOS_HOME
2. OCTOP_HOME (legacy)
3. existing ~/.freeos
4. existing ~/.octop
5. new installs → ~/.freeos

Rebuild the dashboard (optional)

cd dashboard
npm install
npm run build

The Vite app in dashboard/ is what you edit; packaged builds land in src/octop/dashboard/.

Tests

uv run pytest tests/e2e/test_org_growth_loop.py tests/unit/test_org_loop.py tests/unit/test_org_module.py tests/unit/test_governance_mcp.py tests/unit/test_skill_bridge.py tests/unit/test_blueprint_compiler.py tests/unit/test_lifecycle.py tests/unit/test_asset_loop.py tests/unit/test_openxyos_apply.py tests/unit/test_colleague_spawn.py tests/unit/test_host_governance.py

Full host suite: uv run pytest / make test-fast (needs the usual extra services for marked tests).

Enable the organization module

The host stays Python. Organization first paint is the native dashboard page plus /api/org-module/* (catalog, ingest/import, growth loop, employees). The TypeScript sidecar under modules/openxyos/ is optional.

Surface	Action
Dashboard	Sidebar → Organization (in-host workbench)
CLI	uv run freeos org enable · uv run freeos org status · uv run freeos org loop run
Plugin	Admin → Plugins → Organization OS (org-os)
API	PATCH /api/org-module with { "enabled": true }
Standalone commercial site	uv run freeos org export-standalone --out dist/openxyos-web — see docs/org-export.md

Optional Node sidecar (export/sync/advanced deploy only):

FREEOS_ORG_SIDECAR=1 bash scripts/run-org-sidecar.sh

Default origin if opted in: http://127.0.0.1:3780. Organization and freeos org loop run do not wait for /api/health/livez.

Auth: FreeOS JWT users and openXYOS tenants are separate. The proxy forwards X-FreeOS-User* and X-FreeOS-Tenant-Id. One tenant = one workspace/sandbox — not prompt isolation.

Manual loop steps (the one command above already does this)

uv run freeos org enable
uv run freeos org governance enable --tenant-id 1
uv run freeos org assets import --catalog --blueprint tests/fixtures/org-loop/agent-blueprint.v1.json --tenant-id 1
uv run freeos org employee transition policy-analyst market
uv run freeos org employee transition policy-analyst recruit
uv run freeos org employee transition policy-analyst shadow
uv run freeos org employee transition policy-analyst active
uv run freeos org assets publish
uv run freeos org assets apply

Inbound import compiles the blueprint and registers a FreeOS agent (org-policy-analyst) so the colleague is addressable in chat. Governance is spliced into the host tool path — a pending/deny decision is a hard stop.

Host platform features (from Octop)

Unchanged in this fork: multi-user JWT, multi-agent chat, expert library, connectors, ACP, knowledge bases, bundled plugins, cron, terminal/browser/desktop surfaces. The Windows desktop installer is branded FreeOS and defaults to ~/.freeos / FREEOS_HOME. The Python package, octop CLI alias, OCTOP_* env vars, and octop.db stay for compatibility.

Longer host docs: docs/user-guide.md, docs/configuration.md, docs/architecture.md, README_CN.md.

License and attribution

Component	License	Location
FreeOS host + bridge	MIT	LICENSE, NOTICE
Octop-derived code	MIT	Copyright Octop contributors; no Tencent Cloud affiliation claimed
openXYOS tree	Apache-2.0	modules/openxyos/LICENSE, licenses/APACHE-2.0.txt

Remaining octop identifiers

Intentional for package compatibility (not a rebrand miss):

• Python package name octop and import octop
• CLI octop alongside freeos
• OCTOP_* environment variables (desktop also sets FREEOS_HOME)
• SQLite file octop.db inside the home directory
• CI workflow filename .github/workflows/octop-desktop.yml (display name is FreeOS Desktop Package)

See docs/architecture-integration.md for the control/data-plane split and the running self-growth loop.