# Onit

> OnIt is an AI agent framework for automation.

- **Type:** MCP server
- **Install:** `agentstack add mcp-sibyl-oracles-onit`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [sibyl-oracles](https://agentstack.voostack.com/s/sibyl-oracles)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [sibyl-oracles](https://github.com/sibyl-oracles)
- **Source:** https://github.com/sibyl-oracles/onit

## Install

```sh
agentstack add mcp-sibyl-oracles-onit
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# OnIt

*OnIt* — the AI is working on the given task and will deliver the results shortly.

OnIt is an intelligent agent for task automation and assistance. It connects to private [vLLM](https://github.com/vllm-project/vllm) servers, [OpenRouter.ai](https://openrouter.ai/), and [Ollama cloud](https://ollama.com) for hosted models — and uses [MCP](https://modelcontextprotocol.io/) tools for web search, file operations, and more. It also supports the [A2A](https://a2a-protocol.org/) protocol for multi-agent communication.

## Getting Started

### 1. Install

```bash
pip install onit
```

Or from source:

```bash
git clone https://github.com/sibyl-oracles/onit.git
cd onit
pip install -e ".[all]"
```

### 2. Setup

```bash
onit setup
```

The setup wizard walks you through configuring your LLM endpoint, API keys, and preferences. Secrets are stored securely in your OS keychain. Settings are saved to `~/.onit/config.yaml`.

To review your configuration at any time:

```bash
onit setup --show
```

### 3. Run

```bash
onit
```

That's it. MCP tools start automatically, and you get an interactive chat with tool access.

## CLI at a Glance

```
onit                                          # interactive terminal chat
onit setup                                    # configure LLM endpoint, API keys
onit resume [TAG_OR_ID]                       # continue a previous session
onit sessions                                 # list saved sessions

onit serve a2a                                # A2A protocol server (port 9001)
onit serve web                                # Gradio web UI (port 9000)
onit serve gateway [telegram|viber|auto]      # Telegram or Viber bot
onit serve loop "task" --period 60            # repeat a task on a timer

onit ask "what is the weather in Manila"      # send a task to a running A2A server

onit --rules                                  # load coding rules from ONIT.md
onit --rules path/to/rules.md                # load coding rules from a custom file
onit --container                              # run in a hardened Docker container
onit --sandbox                                # delegate code execution to a sandbox
onit --unrestricted                           # unrestricted host filesystem access
```

## Configuration

`onit setup` is the recommended way to configure OnIt. It stores:

- **Settings** in `~/.onit/config.yaml` (LLM endpoint, theme, ports, timeout)
- **Secrets** in your OS keychain (API keys, bot tokens)

You can also use environment variables or a project-level YAML config:

```bash
# Environment variables
export ONIT_HOST=https://openrouter.ai/api/v1
export OPENROUTER_API_KEY=sk-or-v1-...

# Or a custom config file
onit --config configs/default.yaml
```

Priority order: CLI flags > environment variables > `~/.onit/config.yaml` > project config file.

### Example config (`configs/default.yaml`)

```yaml
serving:
  host: https://openrouter.ai/api/v1
  host_key: sk-or-v1-your-key-here   # or set OPENROUTER_API_KEY env var
  # model: auto-detected from endpoint. Set explicitly for OpenRouter:
  # model: google/gemini-2.5-pro
  think: true
  max_tokens: 32768   # max output tokens per response (fits any single answer)
  # Sampling parameters (all optional — sensible defaults apply):
  # temperature: 1.0
  # top_p: 0.95
  # top_k: 20
  # presence_penalty: 1.5
  # repetition_penalty: 1.0

verbose: false
timeout: 600
sandbox: false

web_port: 9000
a2a_port: 9001

theme: white         # or "dark"
topic: ~             # default topic context, e.g. "machine learning"
template_path: ~     # custom prompt template YAML
documents_path: ~    # local documents directory
data_path: ~         # working directory for file operations (default: system temp)

mcp:
  servers:
    - name: PromptsMCPServer
      url: http://127.0.0.1:18200/sse
      enabled: true
    - name: ToolsMCPServer
      url: http://127.0.0.1:18201/sse
      enabled: true
```

### Sampling parameters

Sampling parameters (`temperature`, `top_p`, `top_k`, `min_p`, `presence_penalty`, `repetition_penalty`) are set in `configs/default.yaml` under `serving:`. They are not exposed as CLI flags to keep the command line clean.

**Recommended parameters for Qwen3.5:**

| Mode | Use case | `temperature` | `top_p` | `top_k` | `presence_penalty` |
|------|----------|:---:|:---:|:---:|:---:|
| Thinking (`think: true`) | General | `1.0` | `0.95` | `20` | `1.5` |
| Thinking (`think: true`) | Precise coding | `0.6` | `0.95` | `20` | `0.0` |
| Instruct (no think) | General | `0.7` | `0.8` | `20` | `1.5` |
| Instruct (no think) | Reasoning | `1.0` | `1.0` | `40` | `2.0` |

Set `repetition_penalty: 1.0` in all cases.

## CLI Reference

### Interactive chat (default)

```bash
onit [OPTIONS]
```

Starts an interactive terminal chat with tool access. MCP servers start automatically.

| Flag | Description | Default |
|------|-------------|---------|
| `--config FILE` | Path to YAML configuration file | `configs/default.yaml` |
| `--host URL` | LLM serving host URL. Overrides config and `ONIT_HOST` | — |
| `--model NAME` | Model name. Skips auto-detection from endpoint | — |
| `--verbose` | Enable verbose logging | `false` |
| `--think` | Enable thinking/reasoning mode (CoT) | `false` |
| `--no-stream` | Disable token streaming | `false` |
| `--show-logs` | Show tool execution logs | `false` |
| `--rules [FILE]` | Load a coding-rules `.md` file to guide the agent's behaviour. Defaults to `ONIT.md` in the current directory when no path is given | `ONIT.md` |
| `--resume TAG_OR_ID` | Resume a previous session by tag, UUID, or `last` | — |
| `--sandbox` | Delegate code execution to an external MCP sandbox provider | `false` |
| `--unrestricted` | Unrestricted host filesystem access (trusted environments only) | `false` |
| `--container` | Run the entire OnIt process inside a hardened Docker container | `false` |
| `--mcp-sse URL` | Add an external MCP server (SSE transport, repeatable) | — |
| `--mcp-server URL` | Add an external MCP server (Streamable HTTP transport, repeatable) | — |

### `onit setup`

Interactive setup wizard. Configures the LLM endpoint, API keys, and preferences. Stores settings in `~/.onit/config.yaml` and secrets in the OS keychain.

```bash
onit setup           # run the wizard
onit setup --show    # print current configuration
```

### `onit sessions`

List and manage saved sessions.

```bash
onit sessions                          # list recent sessions (default: 20)
onit sessions --limit 50               # list up to 50 sessions
onit sessions --tag abc123 "my-chat"   # tag a session for easy recall
onit sessions --rebuild                # rebuild session index from JSONL files
onit sessions --clear                  # delete all session history
```

### `onit resume`

Resume a previous session by tag or UUID.

```bash
onit resume              # resume the most recent session
onit resume my-chat      # resume by tag
onit resume abc123       # resume by session UUID prefix
```

Equivalent to `onit --resume TAG_OR_ID`.

### `onit ask`

Send a single task to a running OnIt A2A server and print the response. Useful for scripting, pipelines, or one-shot queries without starting a local agent.

```bash
onit ask "what is the weather in Manila"
onit ask "summarize this document" --file report.pdf
onit ask "describe this image" --image photo.jpg
onit ask "write a script" --server http://192.168.1.10:9001
```

| Argument / Flag | Description | Default |
|-----------------|-------------|---------|
| `task` (positional) | Task to send to the server | required |
| `--file PATH` | File to upload along with the task | — |
| `--image PATH` | Image file for vision processing (model must be a VLM) | — |
| `--server URL` | A2A server URL | `http://localhost:9001` |

### `onit serve`

Run OnIt in a persistent server or daemon mode. All serve modes run indefinitely until interrupted (Ctrl+C).

#### `onit serve a2a`

Run OnIt as an [A2A protocol](https://a2a-protocol.org/) server so other agents or clients can send tasks.

```bash
onit serve a2a                 # listen on port 9001 (default)
onit serve a2a --port 9100     # custom port
```

| Flag | Description | Default |
|------|-------------|---------|
| `--port PORT` | A2A server port | `9001` (or `a2a_port` in config) |

The agent card is available at `http://localhost:9001/.well-known/agent.json`.

**Send a task from another agent (Python A2A SDK):**

```python
from a2a.client import ClientFactory, create_text_message_object
from a2a.types import Role
import asyncio

async def main():
    client = await ClientFactory.connect("http://localhost:9001")
    message = create_text_message_object(role=Role.user, content="What is the weather?")
    async for event in client.send_message(message):
        print(event)

asyncio.run(main())
```

#### `onit serve web`

Launch the Gradio web chat UI.

```bash
onit serve web                 # open on port 9000 (default)
onit serve web --port 9500     # custom port
```

| Flag | Description | Default |
|------|-------------|---------|
| `--port PORT` | Web UI port | `9000` (or `web_port` in config) |

Supports optional Google OAuth2 authentication — see [docs/WEB_AUTHENTICATION.md](docs/WEB_AUTHENTICATION.md).

#### `onit serve gateway`

Run OnIt as a Telegram or Viber bot. Configure bot tokens via `onit setup` or environment variables.

```bash
onit serve gateway                                      # auto-detect from env vars
onit serve gateway telegram                             # Telegram bot
onit serve gateway viber --webhook-url https://...      # Viber bot
```

| Argument / Flag | Description | Default |
|-----------------|-------------|---------|
| `gateway_type` (positional) | `telegram`, `viber`, or `auto` | `auto` |
| `--webhook-url URL` | Public HTTPS URL for Viber webhook (or set `VIBER_WEBHOOK_URL`) | — |
| `--port PORT` | Local port for Viber webhook server | `8443` (or `viber_port` in config) |

Required environment variables (set via `onit setup` or export):
- Telegram: `TELEGRAM_BOT_TOKEN`
- Viber: `VIBER_BOT_TOKEN`, `VIBER_WEBHOOK_URL`

Install gateway dependencies if not using `[all]`:

```bash
pip install "onit[gateway]"
```

#### `onit serve loop`

Repeat a task on a configurable timer. Useful for monitoring, polling, or autonomous scheduled work.

```bash
onit serve loop "check the weather in Manila" --period 60
onit serve loop "summarize today's news" --period 3600
```

| Argument / Flag | Description | Default |
|-----------------|-------------|---------|
| `task` (positional) | Task to execute repeatedly | required |
| `--period SECONDS` | Seconds between iterations | `10` (or `period` in config) |

## Coding Rules (`--rules`)

`--rules` injects a Markdown rules file into the agent's system prompt, giving it explicit coding guidelines to follow throughout the session. This is the primary way to improve and customise the agent's coding behaviour.

```bash
onit --rules                       # load ONIT.md from the current directory (default)
onit --rules path/to/RULES.md      # load a custom rules file
onit --rules --host http://localhost:8000/v1   # combine with any other flags
```

When no file is specified, `--rules` reads `ONIT.md` in the current working directory. The file contents are wrapped in a `` block and prepended to the system prompt:

```
You are an expert coding agent.
Follow these rules precisely when writing, reviewing, or modifying code.

... contents of ONIT.md ...

```

**Creating your own rules file:**

Place an `ONIT.md` at the root of your project and run `onit --rules`. The agent will follow your rules automatically for every task in that session.

Example `ONIT.md`:

```markdown
## Style
- Use snake_case for all identifiers.
- Maximum line length: 88 characters.

## Tests
- Every public function must have a test.
- Tests must assert the business intent, not just the return value.

## Safety
- Never silence exceptions. Log and re-raise.
- Validate all external inputs at the boundary.
```

**With a vLLM or OpenRouter backend:**

```bash
onit --rules --host http://localhost:8000/v1
onit --rules --host https://openrouter.ai/api/v1 --model google/gemini-2.5-pro
```

**With Ollama cloud:**

```bash
onit --rules --host https://api.ollama.com --model glm-5.1:cloud
```

## Isolation Modes

OnIt offers three isolation levels. They can be combined (e.g. `--container --sandbox`).

### `--sandbox`

Delegates individual code-execution tool calls to an external MCP sandbox provider. Complementary to `--container`.

```bash
onit --sandbox
onit --container --sandbox   # defense in depth
```

Requires an MCP server that provides sandbox tools (`sandbox_run_code`, `sandbox_install_packages`, `sandbox_stop`). Set `sandbox: true` in `config.yaml` to enable by default.

### `--container`

Runs the entire OnIt process inside a hardened Docker container so a breach cannot reach the host OS.

```bash
onit --container                                          # interactive terminal in container
onit --container serve web                                # web UI, port 9000 published
onit --container serve a2a --port 9100                    # A2A server on custom port
onit --container --container-gpus all                     # NVIDIA GPU pass-through
onit --container --container-mount "$HOME/docs:/home/onit/documents:ro" \
  serve web                                               # expose host path read-only
onit --container --sandbox                                # combine with per-tool sandboxing
```

The first run auto-builds the `onit:local` image from the repo `Dockerfile`. Subsequent runs reuse the image.

**Container sub-flags:**

| Flag | Description |
|------|-------------|
| `--container-gpus SPEC` | NVIDIA GPU pass-through (e.g. `all`, `"device=0,1"`). Requires NVIDIA Container Toolkit. |
| `--container-mount HOST:CONTAINER[:ro]` | Extra bind mount. Repeatable. Prefer `:ro`. |
| `--container-memory SIZE` | Hard memory cap (e.g. `16g`). Default: unlimited. |
| `--container-shm-size SIZE` | `/dev/shm` size (default: `4g`). Raise for PyTorch DataLoader. |
| `--container-tmp-size SIZE` | `/tmp` tmpfs size (default: `16g`). Backed by host RAM. |

**Isolation posture:** non-root user, read-only rootfs, `--cap-drop=ALL`, no host mounts by default, outbound network allowed.

**What crosses the boundary:**

| Resource | Default behavior |
|---|---|
| `~/.onit/config.yaml` | Bind-mounted read-only |
| Host keychain secrets | Passed as ephemeral env vars |
| Session data | Named volume `onit-data` (writable, persistent) |
| Ports | Published only for the active mode |
| Host filesystem | Nothing beyond config/secrets unless `--container-mount` is set |

**Published ports by mode:**

| Mode | Default port | Override |
|---|---|---|
| (terminal) | — (no ports) | — |
| `serve web` | `9000:9000` | `--port` |
| `serve a2a` | `9001:9001` | `--port` |
| `serve gateway viber` | `8443:8443` | `--port` |

See [docs/DOCKER.md](docs/DOCKER.md) for full details.

### `--unrestricted`

Runs OnIt with lifted filesystem restrictions on the host — the agent can read/write any path, use any working directory, and install packages freely (pip, apt, brew, etc.). Use only in trusted, isolated environments.

```bash
onit --unrestricted
```

Catastrophic commands (disk wipe, reboot, kernel module loading) are always blocked regardless of this flag.

## MCP Tool Integration

MCP servers start automatically. Tools are auto-discovered and available to the agent.

| Server | Description |
|--------|-------------|
| PromptsMCPServer | Prompt templates for instruction generation |
| ToolsMCPServer | Web search, bash commands, file operations, and document tools |

Connect to additional external MCP servers:

```bash
onit --mcp-sse http://localhost:8080/sse
onit --mcp-server http://localhost:8080/mcp
```

## Model Serving

### Private vLLM

Serve models locally with [vLLM](https://github.com/vllm-project/vllm):

```bash
CUDA_VISIBLE_DEVICES=0,1,2,3 v

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [sibyl-oracles](https://github.com/sibyl-oracles)
- **Source:** [sibyl-oracles/onit](https://github.com/sibyl-oracles/onit)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-sibyl-oracles-onit
- Seller: https://agentstack.voostack.com/s/sibyl-oracles
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.