This repository is an unofficial Windows-focused fork of omnigent-ai/omnigent.
It is not the official Omnigent project, website, desktop app, hosted service, or release channel. The upstream project, name, assets, and official docs belong to the upstream maintainers. This fork exists to make local Windows development and collaboration easier while Windows support is still experimental upstream.
Use the official repository for general Omnigent documentation:
https://github.com/omnigent-ai/omnigent
This fork carries Windows runtime compatibility work on top of upstream Omnigent, including:
- avoiding Unix-only imports such as
resourceandfcntlduring Windows startup - using Windows-compatible subprocess process-group handling
- supporting per-conversation harness subprocesses over loopback TCP when Unix domain sockets are unavailable
- adding loopback-token protection for local TCP harness endpoints
- making host daemon terminal output safe for Windows console encodings
- making the default Windows sandbox posture explicit and fail-closed
- skipping POSIX-only terminal bridge tests on Windows
The package and CLI names remain upstream-compatible: omnigent and omni.
Validated on Windows with Python 3.12 using the Windows-relevant server, host, harness, sandbox, terminal bridge, and Claude bridge tests:
225 passed, 31 skipped
The skipped tests are POSIX terminal or tmux paths. Native Windows terminal session support is not complete in this fork.
Install these first:
- Windows 10 or 11
- PowerShell
- Git
- Python 3.12
- Node.js LTS, 22 or newer
uv
Typical install commands:
winget install -e --id Git.Git
winget install -e --id Python.Python.3.12
winget install -e --id OpenJS.NodeJS.LTS
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"Restart PowerShell after installing so git, python, node, npm, and uv
are on PATH.
If you have the official package installed as a uv tool, remove it first so the
fork is the one on your PATH:
uv tool uninstall omnigentInstall this fork directly from GitHub:
uv tool install --python 3.12 git+https://github.com/QwertyCoolMT/omnigent.gitCheck the CLI:
omnigent --help
omni --helpFor development from a clone:
git clone https://github.com/QwertyCoolMT/omnigent.git
cd omnigent
uv sync
uv run omnigent --helpRun the setup flow and add whichever provider credentials you use:
omnigent setupOmnigent can use provider API keys, compatible gateways, or supported local CLI subscriptions depending on the harness you choose. Keep credentials out of Git.
Start the local server and web UI:
omnigent server startOpen:
http://127.0.0.1:6767
Check status:
omnigent server status
omnigent host statusStop everything:
omnigent stopThe background server start command binds to 127.0.0.1, so other devices
cannot see it. For phone, tablet, or teammate access on the same trusted LAN,
run the foreground server bound to all local interfaces:
$env:OMNIGENT_AUTH_ENABLED = "1"
omnigent server --host 0.0.0.0 --port 6767 --admin-password "replace-with-a-real-password"Keep that PowerShell window open.
In a second PowerShell window, register this Windows machine as the local host that can run sessions:
omnigent host --server http://127.0.0.1:6767Find your LAN address:
ipconfigFrom another device on the same network, open:
http://YOUR-WINDOWS-LAN-IP:6767
Example:
http://192.168.5.194:6767
If Windows Firewall blocks the page, allow inbound TCP 6767 on the Private network profile:
New-NetFirewallRule `
-DisplayName "Omnigent Windows Fork 6767" `
-Direction Inbound `
-Protocol TCP `
-LocalPort 6767 `
-Action Allow `
-Profile PrivateDo not expose this server directly to the public internet. Use a VPN such as Tailscale, a private network, or a properly secured reverse proxy.
- Native POSIX terminal flows that require
tmux,pty,fcntl, or Unix signals are not Windows-native yet. - The Windows sandbox backend is intentionally fail-closed. The base install does not provide a Windows kernel sandbox equivalent to bubblewrap or macOS seatbelt.
- If an agent explicitly needs to run without a sandbox on Windows, set
os_env.sandbox.type: noneonly when you accept host-level execution risk. - Some upstream docs and examples assume Linux or macOS. Treat those as upstream behavior unless this README says otherwise.
The upstream README contains official project marketing, the official website, macOS desktop app links, broad deployment positioning, and upstream maintainer language. Those are not appropriate for this fork's front page.
This README intentionally focuses on:
- the fork's unofficial status
- Windows setup
- local collaboration on a trusted network
- current Windows limitations
Keep changes scoped to Windows enablement, Windows documentation, or fixes that are needed to keep the fork usable on Windows. General Omnigent changes should normally go upstream first.
Before publishing Windows runtime changes, run the targeted Windows checks:
$env:PYTHONUTF8 = "1"
python -m pytest `
tests\server\test_performance_metrics.py `
tests\server\integration\test_host_tunnel_route.py `
tests\server\integration\test_host_liveness_staleness_e2e.py `
tests\server\routes\test_host_launch.py `
tests\runtime\harnesses\test_process_manager.py `
tests\runtime\harnesses\test_runner.py `
tests\runtime\harnesses\test_scaffold.py `
tests\sandbox\test_sandbox.py `
tests\terminals\test_ws_bridge.py `
tests\test_claude_native_bridge.py `
tests\policies\builtins\test_enforce_sandbox.pyThis fork keeps the upstream Apache 2.0 license. See LICENSE.