### Frontend Development Setup and Checks

Source: https://github.com/omnigent-ai/omnigent/blob/main/CONTRIBUTING.md

Navigate to the frontend directory, install Node.js dependencies, and run linting and build processes.

```bash
cd ap-web && npm install && npm run lint && npm run build
```

--------------------------------

### Start Electron Development Server

Source: https://github.com/omnigent-ai/omnigent/blob/main/ap-web/electron/README.md

Launches the Electron shell for development. The shell opens on the bundled setup page.

```bash
npm start
```

--------------------------------

### Quickstart Docker Compose Deployment

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/docker/README.md

Use this sequence to quickly set up and run the Omnigent server in single-user mode. It handles environment variable initialization and starts the services in detached mode.

```bash
cd deploy/docker
./bootstrap.sh                          # mints POSTGRES_PASSWORD + cookie secret into .env
docker compose up -d
docker compose logs -f omnigent       # ctrl-c when boot is clean
```

--------------------------------

### Start Vite Development Server

Source: https://github.com/omnigent-ai/omnigent/blob/main/ap-web/README.md

Installs dependencies and starts the Vite development server for the ap-web project. Run this in a separate terminal after navigating to the ap-web directory.

```bash
cd ap-web
npm install
npm run dev
```

--------------------------------

### Install Omnigent with a single command

Source: https://github.com/omnigent-ai/omnigent/blob/main/README.md

This command installs Omnigent and all its dependencies using a shell script. It's the quickest way to get started.

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

--------------------------------

### Start Agent Server

Source: https://github.com/omnigent-ai/omnigent/blob/main/omnigent/onboarding/agent/skills/omnigent-knowledge/SKILL.md

Use this command to start a local server with the agent pre-registered. Ensure the agent directory is correctly set up.

```bash
ap server --agent ./my-agent/
```

--------------------------------

### Install omnigent_client

Source: https://github.com/omnigent-ai/omnigent/blob/main/sdks/README.md

Install the headless HTTP/SSE client using pip.

```bash
pip install -e sdks/python-client
```

--------------------------------

### Install omnigent_ui_sdk

Source: https://github.com/omnigent-ai/omnigent/blob/main/sdks/README.md

Install the terminal UI SDK. This also installs `omnigent-client` as a dependency.

```bash
pip install -e sdks/ui
```

--------------------------------

### Minimal invocation of omnigent_client

Source: https://github.com/omnigent-ai/omnigent/blob/main/sdks/README.md

Basic example of initializing the client, starting a session, and printing events. Ensure the Omnigent server is running at the specified base URL.

```python
import asyncio
from omnigent_client import OmnigentClient

async def main():
    async with OmnigentClient(base_url="http://localhost:8080") as client:
        session = client.session(model="archer")
        async for event in session.send("hello"):
            print(event)

asyncio.run(main())
```

--------------------------------

### Run example agents on different harnesses

Source: https://github.com/omnigent-ai/omnigent/blob/main/README.md

Executes example agents using specified harnesses, such as 'pi', 'openai-agents', or 'cursor'. This demonstrates flexibility in agent execution environments.

```bash
omnigent run examples/polly/ --harness pi
```

```bash
omnigent run examples/debby/ --harness openai-agents
```

```bash
omnigent run examples/polly/ --harness cursor  # Cursor CLI (needs cursor-agent + CURSOR_API_KEY)
```

--------------------------------

### Install and Run OpenShell Tests

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/openshell/README.md

Installs the necessary packages for OpenShell and development, then runs the unit tests for onboarding sandboxes and managed hosts.

```bash
pip install -e '.[openshell,dev]'
pytest tests/onboarding/sandboxes/test_openshell.py tests/server/test_managed_hosts.py
```

--------------------------------

### Docker Environment Example

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md

Example environment file for Docker Compose.

```env
.env.example
```

--------------------------------

### Start OmniGent Server

Source: https://github.com/omnigent-ai/omnigent/blob/main/docs/POLICIES.md

Launch the OmniGent server using a specified configuration file. This command starts the server with the defined policies and modules.

```bash
omnigent server --config server_config.yaml
```

--------------------------------

### Install Electron Dependencies

Source: https://github.com/omnigent-ai/omnigent/blob/main/ap-web/electron/README.md

Installs Electron and electron-builder. Run this command from the ap-web/electron/ directory.

```bash
npm install
```

--------------------------------

### Start Omnigent Server with Agent

Source: https://github.com/omnigent-ai/omnigent/blob/main/ap-web/README.md

Starts the omnigent server and pre-registers an agent. Use this command in one terminal.

```bash
.venv/bin/omnigent server --agent examples/hello_world.yaml
```

--------------------------------

### Start a default Omnigent agent session

Source: https://github.com/omnigent-ai/omnigent/blob/main/README.md

Launches a default agent session in the terminal and starts a local web UI. Use this for a quick start with Omnigent.

```bash
omnigent
```

--------------------------------

### Install Omnigent directly from the repository

Source: https://github.com/omnigent-ai/omnigent/blob/main/README.md

Install Omnigent directly from its GitHub repository using `uv`. This method is useful for installing the latest development version.

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

--------------------------------

### Install omnigent-client

Source: https://github.com/omnigent-ai/omnigent/blob/main/sdks/python-client/README.md

Install the omnigent-client package using pip. This command installs the Python client SDK for the omnigent server API.

```bash
pip install omnigent-client
```

--------------------------------

### Install Dependencies and Login

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/cloudflare/README.md

Navigate to the Cloudflare deployment directory, install npm packages, and log in to your Cloudflare account.

```bash
cd deploy/cloudflare
npm install
npx wrangler login
```

--------------------------------

### Run example agents Polly and Debby

Source: https://github.com/omnigent-ai/omnigent/blob/main/README.md

Launches the example agents Polly (coding orchestrator) and Debby (brainstorming partner). These are useful for initial testing and understanding agent workflows.

```bash
omnigent run examples/polly/
```

```bash
omnigent run examples/debby/
```

--------------------------------

### Install OpenShell Runtime and CLI

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/openshell/README.md

Installs the OpenShell runtime and command-line interface. This script is designed for both Linux and Apple Silicon macOS.

```bash
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh
```

--------------------------------

### Start Omnigent server and host registration

Source: https://github.com/omnigent-ai/omnigent/blob/main/README.md

Starts the Omnigent local server and web UI in the background, and registers the current machine as a host. This is for users who prefer interacting via the browser.

```bash
omnigent server start   # start the local server and web UI in the background
```

```bash
omnigent host           # (separate terminal) register this machine as a host
```

--------------------------------

### Build Windows Distributable

Source: https://github.com/omnigent-ai/omnigent/blob/main/ap-web/electron/README.md

Builds an NSIS installer for Windows.

```bash
npm run build:win
```

--------------------------------

### Bring Up Omnigent Docker Compose Stack

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/docker/SKILL.md

Quick start commands to bring up the Omnigent Docker Compose stack. This includes copying the environment file, setting the database password, and starting the services in detached mode. It also shows how to view the logs.

```bash
cd deploy/docker
cp .env.example .env             # edit POSTGRES_PASSWORD at minimum
docker compose up -d --build
docker compose logs -f omnigent   # Ctrl-C when you see "Uvicorn running"
```

--------------------------------

### Create and Connect to a Cloud Sandbox via CLI

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md

Use the Omnigent CLI to create a sandbox environment with a specified provider and then connect to it. Ensure you have installed the necessary provider extra (e.g., `pip install 'omnigent[modal]'`).

```bash
omnigent sandbox create --provider modal     # or --provider daytona / islo / e2b
omnigent sandbox connect --provider modal --sandbox-id <id> --server https://your-host
```

--------------------------------

### MCP Server Configuration Example

Source: https://github.com/omnigent-ai/omnigent/blob/main/omnigent/onboarding/agent/skills/omnigent-knowledge/SKILL.md

MCP servers are configured using YAML files. This example shows the format for a GitHub MCP server configuration.

```yaml
transport: http
url: https://mcp-server.example.com/sse
headers:
  Authorization: Bearer ${GITHUB_TOKEN}
```

--------------------------------

### Install E2B CLI

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/e2b/README.md

Install the E2B command-line interface globally. This tool is required for building E2B templates.

```bash
npm i -g @e2b/cli
```

--------------------------------

### Install Omnigent with Modal SDK

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/modal/README.md

Install the Omnigent package with the necessary Modal SDK extra. This is a prerequisite for using Modal sandboxes.

```bash
pip install 'omnigent[modal]'
```

--------------------------------

### Example Skill Instructions

Source: https://github.com/omnigent-ai/omnigent/blob/main/omnigent/spec/AGENTSPEC.md

Markdown content providing specific instructions for a skill, to be passed to the model after frontmatter.

```markdown
When asked to research a topic:
1. Use search.web for general context.
2. Use arxiv.search for academic papers.
3. Collect at least 3 sources before synthesizing.
```

--------------------------------

### Server Configuration for Policy Modules

Source: https://github.com/omnigent-ai/omnigent/blob/main/docs/POLICIES.md

Example of how to register a custom policy module in the server configuration file using YAML.

```yaml
policy_modules:
  - myorg.policies
```

--------------------------------

### Get Omnigent Bot User ID

Source: https://github.com/omnigent-ai/omnigent/blob/main/docs/OMNIGENT_BOT_SETUP.md

Retrieves the numeric user ID for the omnigent-ci[bot] GitHub App. This is a one-time step completed during setup.

```bash
gh api users/omnigent-ci%5Bbot%5D --jq '.id'
# -> 294685417
```

--------------------------------

### Serve ap-web from Omnigent server

Source: https://github.com/omnigent-ai/omnigent/blob/main/ap-web/README.md

After building, run the Omnigent server with an example agent. Open the provided URL in your browser.

```bash
.venv/bin/omnigent server --agent examples/hello_world.yaml
# open http://localhost:6767/
```

--------------------------------

### Run Omnigent Locally

Source: https://github.com/omnigent-ai/omnigent/blob/main/CONTRIBUTING.md

Start the local server, register your machine as a host, and run the frontend development server in separate terminals.

```bash
# Terminal 1: local server on :6767
omnigent server

# Terminal 2: register your machine as a host
omnigent host --server http://localhost:6767

# Terminal 3: frontend dev server
cd ap-web
npm run dev
```

--------------------------------

### config.yaml Example

Source: https://github.com/omnigent-ai/omnigent/blob/main/omnigent/onboarding/agent/skills/omnigent-knowledge/SKILL.md

A sample `config.yaml` file demonstrating various configuration options for an Omnigent agent, including spec version, name, description, instructions, executor settings, OS environment access, guardrails, interaction modes, tools, and custom parameters.

```yaml
spec_version: 1               # REQUIRED, must be 1

name: my-agent                # Display name
description: Does X and Y.    # One-line summary

# Instructions — path to a file or inline text.
# Default: looks for AGENTS.md in the agent directory.
instructions: AGENTS.md

executor:
  # REQUIRED area. type must be one of: claude_sdk | agents_sdk | omnigent.
  # There is NO `llm` executor type.
  type: claude_sdk     # Anthropic Claude SDK, in-process (simplest)
  # type: agents_sdk   — OpenAI Agents SDK, in-process
  # type: omnigent     — subprocess harness; requires config.harness below

  # Only for type: omnigent — pick the harness that runs the loop.
  # One of: claude-native | claude-sdk | codex-native | codex |
  #         openai-agents | open-responses | pi
  # config:
  #   harness: claude-native
  #   permission_mode: bypassPermissions   # claude-native headless
  #   yolo: true                           # codex-native headless

  # Model is OPTIONAL — omit to use the configured provider's default.
  # Pin one directly on the executor when needed:
  # model: anthropic/claude-sonnet-4-20250514   # LiteLLM provider/model
  # model: databricks-claude-opus-4-7           # or a serving-endpoint name
  # connection:                                 # provider credentials
  #   api_key: ${ANTHROPIC_API_KEY}
  # auth:                                        # or Databricks profile auth
  #   type: databricks
  #   profile: oss

  timeout: 3600        # Task deadline in seconds (default: 3600)
  max_iterations: 1000 # Max LLM calls per task (default: 1000)

# os_env — grant filesystem/shell access (harness agents). Exposes
# sys_os_read / sys_os_write / sys_os_edit / sys_os_shell.
os_env:
  type: caller_process
  cwd: .
  sandbox:
    type: none         # or linux_bwrap / darwin_seatbelt to sandbox

# guardrails — runtime policy gates (optional).
guardrails:
  ask_timeout: 86400   # seconds to wait on an approval prompt
  policies:
    blast_radius:
      type: function
      function:
        path: omnigent.inner.nessie.policies.blast_radius

interaction:
  conversational: true   # Maintain turn history (default: true)
  modalities:
    input: [text, image, file]   # default: [text]
    output: [text]               # default: [text]

tools:
  # Sub-agents this agent can spawn (must match agents/ subdirectories)
  agents:
    - researcher
    - summarizer

  # Built-in tools — string name or dict with config
  builtins:
    - web_search                 # auto-detects backend based on model provider
    - terminal_run               # persistent bash shell scoped to the conversation
    - upload_file
    - search_conversations

  timeout: 60          # Default tool timeout in seconds

params:                # Arbitrary key-value (readable by skills/tools)
  max_results: 10

```

--------------------------------

### Frontend Development Server

Source: https://github.com/omnigent-ai/omnigent/blob/main/CONTRIBUTING.md

Navigate to the frontend directory and run the development server using npm.

```bash
cd ap-web
npm run dev
```

--------------------------------

### Install Omnigent with OpenShell Extra

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/openshell/README.md

Install the Omnigent package with the 'openshell' extra to enable OpenShell integration. This command installs the necessary dependencies for connecting to an OpenShell gateway.

```bash
pip install 'omnigent[openshell]'
```

--------------------------------

### Install Omnigent with Daytona SDK

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/daytona/README.md

Install the necessary Python package for Omnigent with Daytona support. This command installs the 'omnigent' package along with the 'daytona' extra dependencies.

```bash
pip install 'omnigent[daytona]'
```

--------------------------------

### Create Fly App and Volume, then Deploy

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/fly/README.md

Use these commands to create a new Fly.io application, provision a persistent volume for data, and deploy the Omnigent application using a specified configuration file.

```bash
# from the repo root
fly apps create <your-app>                                  # globally unique name
fly volumes create artifact_data --size 1 --region iad -a <your-app>   # match fly.toml region
fly deploy -c deploy/fly/fly.toml -a <your-app>
```

--------------------------------

### Build ap-web

Source: https://github.com/omnigent-ai/omnigent/blob/main/ap-web/README.md

Navigate to the ap-web directory and run the build command.

```bash
cd ap-web
npm run build
```

--------------------------------

### Install Omnigent package using uv or pip

Source: https://github.com/omnigent-ai/omnigent/blob/main/README.md

Manually install the omnigent package using the `uv` package manager or `pip`. Ensure Python 3.12+ is installed.

```bash
uv tool install omnigent        # or: pip install "omnigent"
```

--------------------------------

### Minimal REPL with omnigent_ui_sdk

Source: https://github.com/omnigent-ai/omnigent/blob/main/sdks/README.md

Sets up a basic terminal REPL using `omnigent_ui_sdk`. It starts a local server, initializes the client, and defines an input handler for user messages.

```python
import asyncio
from omnigent_client import (
    OmnigentClient, LocalServer, BlockStream,
    pipe, skip_intermediate_ends,
)
from omnigent_ui_sdk import RichBlockFormatter, TerminalHost

async def main():
    async with LocalServer(agent_path="./my-agent/") as server:
        client = server.client
        session = client.session(model="my-agent")
        block_stream = BlockStream()
        fmt = RichBlockFormatter()
        host = TerminalHost(model_name="my agent")

        async def on_input(text):
            host.output(fmt.user_message(text))
            async for block in pipe(
                block_stream.stream(session, text),
                skip_intermediate_ends(),
            ):
                for item in fmt.format(block):
                    host.output(item)
                await asyncio.sleep(0)

        async with host:
            host.output(fmt.welcome("my agent"))
            await host.run(on_input)

asyncio.run(main())
```

--------------------------------

### Run Local Omnigent Server

Source: https://github.com/omnigent-ai/omnigent/blob/main/ap-web/electron/README.md

Starts a local Omnigent server for testing purposes. Ensure you are in the repository root and have the project's virtual environment activated.

```bash
# from the repo root, with the project venv:
.venv/bin/python -m omnigent.server   # serves on http://localhost:8000
```

--------------------------------

### Cloudflare Worker Script Example

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/README.md

Example of a Cloudflare Worker script for fronting the Omnigent container.

```javascript
src/index.js
```

--------------------------------

### Install omnigent-ui-sdk

Source: https://github.com/omnigent-ai/omnigent/blob/main/sdks/ui/README.md

Install the omnigent-ui-sdk package using pip. This package is released in lockstep with the core omnigent package.

```bash
pip install omnigent-ui-sdk
```

--------------------------------

### Connect CLI-launched Sandbox to Server

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/modal/README.md

Register a provisioned Modal sandbox as a host with your Omnigent server. This command holds the connection open in your terminal.

```bash
omnigent sandbox connect --provider modal \
  --sandbox-id <id-printed-by-create> \
  --server https://your-host
```

--------------------------------

### Clone Repository and Install Dependencies

Source: https://github.com/omnigent-ai/omnigent/blob/main/CONTRIBUTING.md

Clone the Omnigent repository and set up the local Python development environment using uv. Activate the virtual environment for subsequent commands.

```bash
git clone https://github.com/omnigent-ai/omnigent.git
cd omnigent

uv python install
uv venv --python "$(cat .python-version)"
uv sync --extra all --extra dev
source .venv/bin/activate    # or prefix commands with `uv run`
```

--------------------------------

### Install Islo CLI and Login

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/islo/README.md

Installs the Islo CLI using a curl script and initiates the one-time browser-based login process.

```bash
curl -fsSL https://islo.dev/install.sh | sh
islo login
```

--------------------------------

### Create a CLI-launched Modal Sandbox

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/modal/README.md

Provision a new Modal sandbox and overlay your local Omnigent checkout onto it. This sandbox will run your local code.

```bash
omnigent sandbox create --provider modal
```

--------------------------------

### Install Omnigent with Databricks extra

Source: https://github.com/omnigent-ai/omnigent/blob/main/README.md

Install Omnigent with the `databricks` extra to enable Databricks workspace integration. This requires the Databricks CLI for authentication.

```bash
uv tool install "omnigent[databricks]"
```

--------------------------------

### Tool Call Event Example

Source: https://github.com/omnigent-ai/omnigent/blob/main/docs/POLICIES.md

An example of the event dictionary structure for a 'tool_call' phase, including target, data, context, and session state.

```json
{
  "type": "tool_call",
  "target": "sys_os_shell",
  "data": {
    "name": "sys_os_shell",
    "arguments": {"command": "rm -rf /tmp/data"}
  },
  "context": {
    "actor": {"run_as": "alice@example.com", "client_id": "oauth_abc"},
    "usage": {
      "input_tokens": 1520,
      "output_tokens": 340,
      "total_tokens": 1860,
      "total_cost_usd": 0.012
    }
  },
  "session_state": {"call_count": 5},
  "request_data": null
}
```

--------------------------------

### Triage Agent Configuration Example

Source: https://github.com/omnigent-ai/omnigent/blob/main/designs/issue-triage-proposal.md

Example configuration for the triage agent, specifying the Claude SDK harness and Databricks gateway for LLM credentials.

```yaml
llm_provider: "claude"
llm_api_key: $secrets.LLM_API_KEY
gateway_base_url: $secrets.GATEWAY_BASE_URL

# Other configuration options for classification, deduplication, etc.
components:
  - comp:server
  - comp:runner
  - comp:repr
  - comp:web-ui
  - comp:policies
  - comp:harnesses

priorities:
  - P0-critical
  - P1-high
  - P2-medium
  - P3-low
```

--------------------------------

### Create an OpenShell Sandbox

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/openshell/README.md

Use this command to provision a new sandbox environment. It builds your local code and overlays it onto the host image.

```bash
omnigent sandbox create --provider openshell --server https://your-host
```

--------------------------------

### Install Omnigent with E2B extra

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/e2b/README.md

Install the Omnigent Python package with the E2B SDK extra. This command is necessary for using Omnigent with E2B sandboxes.

```bash
pip install 'omnigent[e2b]'
```

--------------------------------

### Install Omnigent using Homebrew

Source: https://github.com/omnigent-ai/omnigent/blob/main/README.md

Install Omnigent via the official Homebrew tap. This is a convenient option for macOS and Linux users who use Homebrew.

```bash
brew install omnigent-ai/tap/omnigent
```

--------------------------------

### Policy Response Example

Source: https://github.com/omnigent-ai/omnigent/blob/main/docs/POLICIES.md

An example of a response dictionary returned by a policy callable. The 'result' field is required, and 'state_updates' can be used to modify session state.

```json
{
  "result": "DENY",
  "reason": "Destructive shell command blocked.",
  "state_updates": [
    {"key": "call_count", "action": "increment", "value": 1}
  ]
}
```

--------------------------------

### Set Environment Variables and Run Agent

Source: https://github.com/omnigent-ai/omnigent/blob/main/omnigent/onboarding/agent/AGENTS.md

Before running your agent, set any required environment variables that are referenced in the agent's configuration. Then, use `omnigent chat` to test the agent.

```bash
export OPENAI_API_KEY="your-key-here"
ap chat /tmp/my-agent/
```

--------------------------------

### Authenticate and Register Host with CLI

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/kubernetes/README.md

Authenticate the Omnigent CLI with the server and register the current machine as a host.

```bash
omnigent login https://omnigent.example.com          # authenticate the CLI
omnigent host  --server https://omnigent.example.com # register this machine
```

--------------------------------

### Install Ingress-Nginx and Cert-Manager on Kubernetes

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/kubernetes/README.md

Install ingress-nginx and cert-manager to enable ingress and TLS certificate management. Use the provider-specific manifest for ingress-nginx. Ensure both add-ons are ready before proceeding.

```bash
kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/main/deploy/static/provider/kind/deploy.yaml

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/latest/download/cert-manager.yaml

kubectl wait -n ingress-nginx --for=condition=Ready pod 
  -l app.kubernetes.io/component=controller --timeout=180s
kubectl wait -n cert-manager --for=condition=Available deployment --all --timeout=180s
```

--------------------------------

### Install Omnigent with CoreWeave Sandbox Extra

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/cwsandbox/README.md

Install the Omnigent package with the cwsandbox extra to enable CoreWeave Sandbox functionality. This should be done in your environment where you plan to run the Omnigent launcher.

```bash
pip install 'omnigent[cwsandbox]'
```

--------------------------------

### Create CLI-launched Sandbox

Source: https://github.com/omnigent-ai/omnigent/blob/main/deploy/e2b/README.md

Provisions a new sandbox environment using the 'omnigent sandbox create' command. This command builds wheels from your local checkout and overlays them onto the sandbox.

```bash
omnigent sandbox create --provider e2b
```