Install Omnigent with uv or Homebrew for Remote Access

What Omnigent is and what this installation provides

Omnigent is an open-source meta-harness for running and coordinating AI agents. Rather than tying every workflow to one agent implementation, it provides a common orchestration layer over supported tools such as Claude Code, Codex, Cursor, OpenCode, Hermes, Pi, and agents defined by the user. Its interface can bring sessions, messages, sub-agents, terminals, and files into a shared workflow that can be reached from a terminal, browser, phone, or supported native application.

The distinction between Omnigent itself and the agent harnesses it coordinates is important during installation. Installing the omnigent package gives you the Omnigent command and server components, but a particular agent workflow may still depend on a compatible harness, its own account or model-provider authorization, and additional tooling. A successful package installation therefore proves that Omnigent is available. It does not automatically prove that every optional harness, provider, sandbox, or cloud integration is ready.

For this guide, the critical verified endpoint is the local browser interface. Running the documented omnigent command launches a web UI at http://localhost:6767. We will treat that local result as the installation acceptance test. Remote access comes later because tunneling an unverified or incorrectly configured service makes diagnosis harder and can expose an interface before its authentication and permissions have been reviewed.

Prerequisites and installation planning

Omnigent requires Python 3.12 or newer for a manual installation. The project also identifies uv and Git as required tools in its installation guidance. The exact supporting tools you need after installation depend on how you intend to run agents. In particular, coding-harness command-line tools and the web UI have Node.js-related requirements, while native terminal wrappers have platform-specific sandbox and terminal dependencies.

Decide which installation method you want before changing the system. The uv tool installation is a good fit when you already manage Python command-line applications with uv. Homebrew provides a concise installation path on a machine where Homebrew is available. The project also documents pip, a bootstrap script for POSIX environments, and direct installation from its Git repository. This guide concentrates on uv and Homebrew but documents the other confirmed paths so you can understand the available choices.

Node.js, npm, and pnpm

A basic package installation and the full agent development toolchain are not identical. Omnigent's documented prerequisites specify Node.js 22 LTS or newer with npm for coding-harness command-line tools installed by omnigent run, and pnpm for the web UI toolchain. If your installation reports that pnpm is missing, the project identifies either of these general setup paths:

corepack enable

Or:

npm install -g pnpm

Run only one appropriate pnpm setup method, then open a new shell if your environment does not immediately recognize the executable. The exact Node.js installation procedure depends on your operating system and package-management policy, so this guide does not prescribe an unverified platform-specific command.

Native terminal wrappers on Linux and macOS

Native terminal wrappers require tmux. On Linux, the wrappers and the Pi harness also rely on bubblewrap for operating-system sandboxing. Omnigent treats that Linux isolation as mandatory for those terminals, so a missing bwrap binary causes them to fail to start. The project documentation gives apt install bubblewrap as an example for distributions that use apt. Package names and installation commands can differ on other distributions.

macOS uses its built-in seatbelt sandbox and does not require bubblewrap. That statement applies to the documented Omnigent sandbox path, not to every optional agent or integration that you might install.

Windows support boundaries

Omnigent runs natively on Windows in what its documentation calls a degraded mode. The server, web UI, and SDK-based harnesses are available, and agents use a Windows Job Object for process-tree containment. The POSIX bootstrap script is not the Windows installation path. Native Windows users should install with uv directly.

The supplied project documentation states that some native terminal-wrapper functionality is unavailable on Windows and recommends Linux, macOS, or WSL for those workflows. Before choosing native Windows, identify the exact harness you plan to run and confirm that it belongs to the supported SDK-based path rather than assuming every wrapper behaves the same way.

Install Omnigent with uv, Homebrew, pip, or Git

Use one primary installation path. Installing the same command with multiple package managers can leave several omnigent executables on the system, after which your shell might run a different copy than the one you intended to update. If you are replacing an earlier installation method, first determine which executable your shell resolves and remove the obsolete installation with the package manager that created it.

Option 1: Install with uv

For a manual uv installation, first confirm that Python 3.12 or newer and uv are available. Then install Omnigent as a managed command-line tool:

uv tool install omnigent

uv places tool applications in its managed environment and exposes their commands through its tool executable directory. If installation succeeds but the shell cannot find omnigent, the likely issue is command discovery rather than the package itself. Follow uv's displayed guidance for adding its executable directory to your environment, then restart the terminal or reload the relevant shell configuration.

On native Windows, the project documents direct uv installation with Python 3.12:

uv tool install --python 3.12 omnigent

This avoids the POSIX-only bootstrap script. Remember that native Windows remains a degraded-mode deployment, so installation success should be followed by a compatibility check for the specific harness you intend to use.

Option 2: Install with Homebrew

If Homebrew is already installed and appropriate for your machine, install Omnigent from its documented tap:

brew install omnigent-ai/tap/omnigent

Let Homebrew complete the package and dependency installation. If the command is later unavailable, inspect Homebrew's own output and environment setup rather than installing a second Omnigent copy immediately. A shell that cannot find Homebrew-managed binaries may also fail to find Omnigent even though the formula installation completed.

Option 3: Install with pip

The project also documents a pip installation:

pip install "omnigent"

Make sure this pip belongs to Python 3.12 or newer. Python systems often contain multiple interpreters and pip executables, so verify the selected environment before installation. This guide does not invent a universal virtual-environment layout because Python command names and environment policies vary across operating systems.

Option 4: Install directly from the Git repository

To install the current repository version through uv rather than a packaged release, use the documented Git URL:

uv tool install -q --python 3.12 git+https://github.com/omnigent-ai/omnigent.git

Repository installations can contain changes newer than the latest release. That may be useful for testing a fix, but it also makes repeatability harder because the default branch can move. For a stable team environment, record exactly what was installed and test upgrades before replacing a working instance.

Optional installation extras

Omnigent publishes optional extras for selected model providers, sandbox providers, SDK harnesses, storage systems, and memory integrations. Examples documented by the project include Databricks, Bedrock, Vertex, Modal, Daytona, Blaxel, Boxlite, CoreWeave sandbox support, E2B, OpenShell, Kubernetes, Antigravity, Copilot, Cursor, Agents SDK, S3, and Hindsight.

With uv, extras use standard Python package-extra syntax. For example, the project provides this pattern for Databricks and Modal:

uv tool install "omnigent[databricks,modal]"

Treat that as an example, not a recommendation to install every integration. Extra dependencies increase the number of components that must be updated and secured. Select only integrations that are part of the planned deployment.

POSIX bootstrap installer

On a POSIX environment, the project's quick-start path is its bootstrap script:

curl -fsSL https://raw.githubusercontent.com/omnigent-ai/omnigent/main/scripts/install_oss.sh | sh

A downloaded script piped directly into a shell executes immediately. In a controlled environment, review installation scripts and their origin before running them. The bootstrap path is included for completeness, but uv and Homebrew remain the primary methods in this guide, and Windows users must not use this POSIX-only installer.

Prepare an agent workflow without guessing configuration

Omnigent can coordinate several harnesses, custom YAML agents, model providers, and sandbox services. There is no single credential or agent configuration that is correct for every installation. A Claude-based workflow, a Codex workflow, a custom agent, and a cloud sandbox can each require different software, authorization, and policy decisions.

For that reason, the safe initial configuration sequence is to choose one supported workflow, satisfy only its documented dependencies, sign in through that provider or harness's supported mechanism, and test it locally. Do not copy API keys into shell history, project files, screenshots, tunnel URLs, or browser addresses. If a tool supports environment-based credentials, operating-system credential storage, or its own sign-in command, use the method documented for that exact integration.

Start Omnigent and verify the local web UI

Installation should be verified locally before any tunnel is created. This separates package, process, and application problems from remote connectivity problems. The documented startup command is:

omnigent

Once the process starts, open this address from a browser on the same machine:

http://localhost:6767

A working page at that address confirms four useful facts: the shell found an Omnigent executable, the process started, the local server is listening on its documented port, and a browser on the host can reach the web interface. It does not yet prove that an agent provider is authorized, a native wrapper has all sandbox dependencies, or a remote client can connect.

Local verification checklist

• The omnigent command starts without an immediate missing-command error.
• The process remains running rather than exiting after displaying an exception.
• http://localhost:6767 loads in a browser on the Omnigent host.
• The interface can create or open a low-risk test workflow appropriate to the selected harness.
• Required approval prompts and policy controls remain available during the test.
• Restart behavior is understood before the service is relied upon remotely.

Keep the terminal visible during the first launch. If the browser shows no page, the terminal output is usually more useful than changing tunnel settings. An immediate Python error points toward the environment or package. A missing command points toward installation or shell path resolution. A running process with an unavailable page suggests a local service or port issue.

Routine operation, upgrades, and local service management

A development launch in an interactive terminal is useful for testing, but a remotely accessed service needs an intentional lifecycle. Omnigent is available only while its process is running. A Localtonet tunnel is also available only while the selected Localtonet client is connected and that tunnel is running. Treat those as two separate processes with separate health checks.

Starting and stopping

Start Omnigent with the documented omnigent command and verify the local page after every significant configuration or package change. When stopping a test instance, terminate it through the normal process control provided by the shell or service manager you use. No specific production service-manager unit is supplied in the evidence for this article, so we do not provide an invented systemd, launchd, or Windows service definition.

If you need automatic startup, build it according to your operating system's service-management practices and the environment in which the verified command works. Preserve the same user identity, executable path, working environment, and access to required provider credentials. Test a complete machine restart before considering automatic startup reliable.

Upgrading safely

Use the package manager that installed Omnigent to manage its lifecycle. Before upgrading, note the current working behavior, review the project's release notes, and preserve any configuration or agent definitions according to the project's current guidance. Alpha releases can introduce substantial changes, so test upgrades on non-critical sessions first.

After an upgrade, repeat the local acceptance test at http://localhost:6767. Then test one representative agent session, its approval behavior, its sandbox, and any provider authorization. Only after those checks should you restart or re-enable public access.

Backups and secrets

The supplied evidence does not define a universal Omnigent data directory or backup command, so this guide does not invent one. Identify the storage and configuration locations used by your installed version before creating a backup procedure. Keep agent definitions, policy files, and operational documentation under appropriate access controls, but do not commit credentials or provider tokens to a source repository.

If your workflow handles customer code, private repositories, terminal sessions, or model-provider credentials, include those assets in your threat model. A backup may contain information just as sensitive as the running service. Encrypt sensitive backups, restrict access, and test recovery rather than assuming that copying an undocumented folder is sufficient.

Expose the verified Omnigent UI with a Localtonet HTTP tunnel

After Omnigent works locally, you can make the HTTP interface reachable from outside the LAN with Localtonet. Our client application establishes an outbound connection from the device to a Localtonet relay server. This means you do not need inbound router port forwarding, firewall changes, a VPN setup, or a public IP address for the standard tunnel workflow.

Omnigent presents a local HTTP endpoint, so an HTTP tunnel is the appropriate Localtonet family for this workflow. The tunnel points to the local IP address and port reachable from the device running our client. For an Omnigent process on the same machine, the documented application port is 6767, and the local verification address is http://localhost:6767.

HTTP tunnels can use a Random Sub Domain, Custom Sub Domain, or Custom Domain process type. Each serves the same target content at a public HTTPS address. Availability can vary by current product configuration or subscription, so select only an option shown in your dashboard. Exact custom-domain DNS requirements must be checked against the current documentation rather than inferred.

For the current dashboard sequence and fields, consult our Localtonet HTTP tunnel documentation. Use the values displayed in your own dashboard for the device, server, hostname, and any plan-dependent options.

Security checklist before allowing remote access

Remote access changes the trust boundary. A page previously reachable only through localhost can become available at a public HTTPS address. HTTPS protects the public web connection at the tunnel edge, but it does not decide who should be permitted to control an AI agent, view a terminal, inspect files, or use provider credentials. Application authorization and least-privilege agent policies remain essential.

Troubleshooting installation, startup, and remote access

The shell says omnigent is not found

First determine which installation method completed successfully. If uv reported success, the uv tool executable directory may not be present in the current shell environment. If Homebrew reported success, the Homebrew binary path may not be initialized for that shell. Open a fresh terminal after applying the package manager's path guidance.

Avoid immediately installing through pip as a second workaround. That can hide the path issue by creating another copy and make later upgrades unpredictable. Resolve which executable should run before adding another package-manager layer.

The installer reports an unsupported Python version

Manual Omnigent installation requires Python 3.12 or newer. Verify that the interpreter selected by uv or pip meets that requirement. Installing a new interpreter does not necessarily change the interpreter used by an existing pip command, so pay attention to the environment identified by the installation output.

The web page at localhost:6767 does not load

Return to the terminal that launched omnigent. Confirm that the process is still running and inspect its visible error output. Do not troubleshoot Localtonet until the local page works. Also check whether another process already uses port 6767. The supplied documentation confirms port 6767 as the normal endpoint but does not establish a supported alternative-port command for this article, so we do not invent one.

The UI works, but a native harness does not start

This usually indicates that the core server and the selected harness have different unmet requirements. Confirm Node.js 22 LTS or newer where required, npm, pnpm for the web toolchain, and tmux for native terminal wrappers. On Linux, verify that bubblewrap is installed for affected wrappers. On native Windows, confirm that the workflow is among the supported SDK-based paths rather than an unavailable native wrapper.

An agent starts but cannot access its model provider

Provider authorization is separate from installing Omnigent. Confirm that the selected harness or provider has been configured through its supported sign-in mechanism and that required extras were installed if the integration uses one. Do not print full credentials while debugging. Redact secrets from logs before sharing them.

The local UI works, but the public URL does not

Check the layers in order. Confirm that Omnigent still loads locally. Confirm our client is running and the correct device is connected. Confirm the HTTP tunnel points to the reachable local address and port 6767. Finally, confirm that the tunnel was started, since tunnel creation alone does not make it active.

The public page loads incorrectly or shows an unexpected service

Recheck the tunnel's local target. Another process may be using the selected address or port, or the client may be running on a different device from the Omnigent host. The target must be reachable from the device running our client. Never expose an unexpected page while investigating. Stop the tunnel first, correct the local target, verify locally, and then restart it.

The tunnel stopped after the host restarted

A Localtonet tunnel requires the selected client device to be connected and the tunnel to be running. Omnigent also requires its own process to be running. Verify both application startup and client startup after a reboot, then inspect the tunnel state in the dashboard. Do not assume that creating a tunnel permanently starts every local dependency.

Frequently asked questions