### Quickstart Backend and Desktop Setup

Source: https://open-jarvis.github.io/OpenJarvis/downloads

Initializes the repository and runs the quickstart script to prepare the environment.

```bash
git clone https://github.com/open-jarvis/OpenJarvis.git && cd OpenJarvis
./scripts/quickstart.sh
```

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

### quickstart_cmd

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/cli/quickstart_cmd

The `quickstart_cmd` provides a guided 5-step setup process for new users of OpenJarvis.

```APIDOC
## CLI Command: quickstart_cmd

### Description
Provides a guided 5-step setup for new users.

### Method
CLI Command

### Endpoint
N/A (CLI command)

### Parameters
None explicitly listed for the command itself.

### Request Example
```bash
jarvis quickstart
```

### Response
N/A (CLI command output varies based on user interaction and setup progress.)
```

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

### Quickstart Implementation

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/cli/quickstart_cmd

The full implementation of the quickstart command, which performs hardware detection, configuration setup, engine validation, model checking, and a final connectivity test.

```python
@click.command()
@click.option("--force", is_flag=True, help="Redo all steps even if already done.")
def quickstart(force: bool) -> None:
    """Guided 5-step setup for new users."""
    console = Console()

    # Step 1: Detect hardware
    console.print("[bold cyan][1/5][/bold cyan] Detecting hardware...")
    hw = detect_hardware()
    console.print(f"  Platform : {hw.platform}")
    console.print(f"  CPU      : {hw.cpu_brand} ({hw.cpu_count} cores)")
    console.print(f"  RAM      : {hw.ram_gb} GB")
    if hw.gpu:
        console.print(
            f"  GPU      : {hw.gpu.name} ({hw.gpu.vram_gb} GB VRAM, x{hw.gpu.count})"
        )
    else:
        console.print("  GPU      : none detected")

    engine_key = recommend_engine(hw)

    # Step 2: Write config
    console.print()
    console.print("[bold cyan][2/5][/bold cyan] Writing config...")
    if DEFAULT_CONFIG_PATH.exists() and not force:
        console.print(
            f"  [dim]Config already exists at {DEFAULT_CONFIG_PATH} (skip)[/dim]"
        )
    else:
        toml_content = generate_default_toml(hw)
        DEFAULT_CONFIG_DIR.mkdir(parents=True, exist_ok=True)
        DEFAULT_CONFIG_PATH.write_text(toml_content)
        console.print(f"  [green]Config written to {DEFAULT_CONFIG_PATH}[/green]")

    # Step 3: Check engine
    console.print()
    console.print(f"[bold cyan][3/5][/bold cyan] Checking engine ({engine_key})...")
    active_engine = engine_key
    if not _check_engine_health(engine_key):
        fallbacks = [k for k in _discover_healthy_engines() if k != engine_key]
        if fallbacks:
            active_engine = fallbacks[0]
            console.print(
                f"  [yellow]Engine '{engine_key}' is not reachable; "
                f"falling back to '{active_engine}'.[/yellow]"
            )
        else:
            console.print(
                f"  [red bold]Engine '{engine_key}' is not reachable.[/red bold]"
            )
            console.print()
            console.print(f"  Start the {engine_key} server and try again.")
            console.print("  Run [bold]jarvis doctor[/bold] for detailed diagnostics.")
            raise SystemExit(1)
    else:
        console.print(f"  [green]Engine '{engine_key}' is healthy.[/green]")

    # Step 4: Verify model
    console.print()
    console.print("[bold cyan][4/5][/bold cyan] Checking for available models...")
    if not _check_model_available(active_engine):
        console.print("  [yellow]No models found.[/yellow]")
        console.print(
            "  Pull a model first (e.g. [bold]ollama pull qwen3.5:2b[/bold])."
        )
        raise SystemExit(1)
    console.print("  [green]Models available.[/green]")

    # Step 5: Test query
    console.print()
    console.print("[bold cyan][5/5][/bold cyan] Running test query...")
    response = _test_query(active_engine)
    console.print(f"  [green]Response:[/green] {response[:200]}")

    console.print()
    console.print(
        '[bold green]Setup complete![/bold green] Try: [bold]jarvis ask "Hello"[/bold]'
    )
```

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

### Setup Energy Monitor in Python

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/cli/bench_cmd

Handles the setup of an energy monitor, including installation and error handling. It checks for prerequisites and attempts to install the monitor, providing user feedback.

```python
extra_name = extra_hint.split("[")[1].rstrip("]")
        msg = (
            "[yellow]Energy monitor not available"
            " — energy metrics will be zero.[/yellow]\n"
            f"  Install: [bold]uv sync "
            f"--extra {extra_name}[/bold]\n"
        )
        if setup_energy and setup_script.exists():
            console.print("[cyan]Running energy monitor setup...[/cyan]")
            try:
                subprocess.run(
                    [str(setup_script)],
                    cwd=setup_script.parent.parent,
                    check=True,
                )
                from openjarvis.telemetry.energy_monitor import create_energy_monitor

                energy_monitor = create_energy_monitor(
                    prefer_vendor=config.telemetry.energy_vendor or None,
                )
                if energy_monitor is not None:
                    console.print("[green]Energy monitor installed.[/green]")
            except (subprocess.CalledProcessError, Exception) as exc:
                console.print(f"[red]Setup failed: {exc}[/red]")
                console.print(msg)
        else:
            console.print(msg)
```

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

### Browser App One-Command Setup

Source: https://open-jarvis.github.io/OpenJarvis/downloads

Clones the repository and executes the quickstart script for the browser-based interface.

```bash
git clone https://github.com/open-jarvis/OpenJarvis.git
cd OpenJarvis
./scripts/quickstart.sh
```

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

### Manual Browser App Setup

Source: https://open-jarvis.github.io/OpenJarvis/downloads

Step-by-step manual installation of dependencies, backend, and frontend services.

```bash
git clone https://github.com/open-jarvis/OpenJarvis.git
cd OpenJarvis
uv sync --extra server
cd frontend && npm install && cd ..
```

```bash
# Install from https://ollama.com if not already installed
ollama serve &
ollama pull qwen3:0.6b
```

```bash
uv run jarvis serve --port 8000
```

```bash
cd frontend
npm run dev
```

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

### Setup User and Installation Directory

Source: https://open-jarvis.github.io/OpenJarvis/deployment/systemd

Commands to create a dedicated system user and prepare the installation directory for OpenJarvis.

```bash
sudo useradd --system --create-home --home-dir /opt/openjarvis openjarvis
sudo -u openjarvis python3 -m venv /opt/openjarvis/.venv
sudo -u openjarvis git clone https://github.com/open-jarvis/OpenJarvis.git /opt/openjarvis/OpenJarvis
cd /opt/openjarvis/OpenJarvis && sudo -u openjarvis uv sync --extra server
```

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

### Install and Start the Service

Source: https://open-jarvis.github.io/OpenJarvis/deployment/systemd

Commands to deploy the systemd unit file and manage the service lifecycle.

```bash
sudo cp deploy/systemd/openjarvis.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable openjarvis
sudo systemctl start openjarvis
```

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

### Start API Server

Source: https://open-jarvis.github.io/OpenJarvis/getting-started/quickstart

Commands to install server dependencies and launch the OpenAI-compatible API server.

```bash
uv sync --extra server
```

```bash
jarvis serve --port 8000
```

```bash
jarvis serve --host 0.0.0.0 --port 8000 --engine ollama --model qwen3:8b --agent orchestrator
```

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

### FAISS Backend Setup and Usage

Source: https://open-jarvis.github.io/OpenJarvis/user-guide/memory

Installs the required dependencies and demonstrates basic usage for dense neural retrieval.

```bash
uv sync --extra memory-faiss
```

```python
backend = MemoryRegistry.create("faiss")
doc_id = backend.store("Neural networks are computational models")
results = backend.retrieve("deep learning architectures")
```

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

### Quickstart Browser App

Source: https://open-jarvis.github.io/OpenJarvis/user-guide/chat-simple

Starts both the OpenJarvis backend API server and the React frontend for the browser application. This command opens the app in your default browser.

```bash
./scripts/quickstart.sh

```

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

### BM25 Backend Setup and Usage

Source: https://open-jarvis.github.io/OpenJarvis/user-guide/memory

Installs the required dependencies and demonstrates usage for classic probabilistic keyword retrieval.

```bash
uv sync --extra memory-bm25
```

```python
backend = MemoryRegistry.create("bm25")
backend.store("Python is a programming language", source="intro.txt")
results = backend.retrieve("programming language")
```

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

### ColBERTv2 Backend Setup and Usage

Source: https://open-jarvis.github.io/OpenJarvis/user-guide/memory

Installs the required dependencies and initializes the ColBERTv2 backend for high-quality late-interaction retrieval.

```bash
uv sync --extra memory-colbert
```

```python
backend = MemoryRegistry.create(
    "colbert",
    checkpoint="colbert-ir/colbertv2.0",
    device="cpu",
)
```

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

### Start Gateway Command

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/cli/gateway_cmd

Starts the gateway daemon. Use the `--install` flag to generate and enable systemd or launchd services for automatic startup.

```python
@gateway.command()
@click.option(
    "--install",
    is_flag=True,
    help="Generate and enable systemd/launchd service",
)
def start(install: bool) -> None:
    """Start the gateway daemon."""
    if install:
        import platform as plat

        from openjarvis.daemon.service import (
            generate_launchd_plist,
            generate_systemd_service,
        )

        if plat.system() == "Darwin":
            plist_path = (
                Path.home() / "Library/LaunchAgents/com.openjarvis.gateway.plist"
            )
            generate_launchd_plist(plist_path)
            click.echo(f"Wrote {plist_path}")
            subprocess.run(
                ["launchctl", "load", str(plist_path)],
                check=False,
            )
        else:
            service_path = (
                Path.home() / ".config/systemd/user/openjarvis-gateway.service"
            )
            generate_systemd_service(service_path)
            click.echo(f"Wrote {service_path}")
            subprocess.run(
                ["systemctl", "--user", "daemon-reload"],
                check=False,
            )
            subprocess.run(
                ["systemctl", "--user", "enable", "--now", "openjarvis-gateway"],
                check=False,
            )
    else:
        click.echo("Starting OpenJarvis gateway (foreground)...")
        click.echo("Gateway started. Press Ctrl+C to stop.")

```

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

### Python SDK Installation and Usage

Source: https://open-jarvis.github.io/OpenJarvis/downloads

Installs the SDK and demonstrates basic usage for programmatic interaction.

```bash
git clone https://github.com/open-jarvis/OpenJarvis.git
cd OpenJarvis
uv sync
```

```python
from openjarvis import Jarvis

j = Jarvis()
print(j.ask("Explain quicksort in two sentences."))
j.close()
```

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

### Install Git

Source: https://open-jarvis.github.io/OpenJarvis/getting-started/macos

Installs Git for cloning the repository.

```bash
brew install git
```

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

### CLI Installation and Verification

Source: https://open-jarvis.github.io/OpenJarvis/downloads

Installs the CLI environment and verifies the installation version.

```bash
git clone https://github.com/open-jarvis/OpenJarvis.git
cd OpenJarvis
uv sync
```

```bash
jarvis --version
# jarvis, version 0.1.0
```

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

### Install Frontend Dependencies

Source: https://open-jarvis.github.io/OpenJarvis/getting-started/macos

Installs dependencies for the web interface.

```bash
cd frontend && npm install && cd ..
```

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

### Install and Initialize OpenJarvis

Source: https://open-jarvis.github.io/OpenJarvis/user-guide/chat-simple

Clones the OpenJarvis repository, installs dependencies, and initializes a simple chat preset. Navigate to the OpenJarvis directory after cloning.

```bash
git clone https://github.com/open-jarvis/OpenJarvis.git
cd OpenJarvis
uv sync
jarvis init --preset chat-simple

```

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

### Install and Initialize OpenJarvis

Source: https://open-jarvis.github.io/OpenJarvis/user-guide/deep-research

Clone the repository, install dependencies, and initialize the deep research agent configuration.

```bash
git clone https://github.com/open-jarvis/OpenJarvis.git
cd OpenJarvis
uv sync --extra dev
jarvis init --preset deep-research
```

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

### CLI Example with Agents and Tools

Source: https://open-jarvis.github.io/OpenJarvis/getting-started/quickstart

Example of using the CLI to ask a question with the 'orchestrator' agent and specifying 'calculator' and 'think' tools.

```bash
jarvis ask --agent orchestrator --tools calculator,think "What is 137 * 42?"

```

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

### Start llama.cpp Server

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/cli/ask

Use this command to start the llama.cpp server. Ensure you specify the path to your GGUF model.

```bash
llama-server -m <gguf>
```

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

### CLI Installation and Usage

Source: https://open-jarvis.github.io/OpenJarvis/getting-started/installation

Commands for installing, verifying, and interacting with the OpenJarvis CLI.

```bash
git clone https://github.com/open-jarvis/OpenJarvis.git
cd OpenJarvis
uv sync
uv run maturin develop -m rust/crates/openjarvis-python/Cargo.toml
```

```bash
jarvis --version
# jarvis, version 0.1.0
```

```bash
jarvis ask "What is the capital of France?"

jarvis ask --agent orchestrator --tools calculator "What is 137 * 42?"

jarvis serve --port 8000

jarvis doctor

jarvis model list

jarvis chat
```

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

### Install and Initialize Scheduled Monitor

Source: https://open-jarvis.github.io/OpenJarvis/user-guide/scheduled-monitor

Clone the repository, install dependencies, and initialize the scheduled monitor preset. This configures your settings for the operative agent.

```bash
git clone https://github.com/open-jarvis/OpenJarvis.git
cd OpenJarvis
uv sync --extra dev
jarvis init --preset scheduled-monitor
```

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

### Install Hugging Face CLI

Source: https://open-jarvis.github.io/OpenJarvis/getting-started/macos

Installs the Hugging Face CLI tool using uv.

```bash
uv tool install huggingface_hub
```

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

### CLI task list output example

Source: https://open-jarvis.github.io/OpenJarvis/user-guide/scheduler

Example output format for the task list command.

```text
ID               AGENT     TYPE       VALUE          STATUS   NEXT RUN
a3f9b12c4d8e    simple    cron       0 8 * * 1-5    active   2026-02-26T08:00:00+00:00
b7c2e56f1a3d    orchestr  interval   3600           active   2026-02-25T14:05:00+00:00
```

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

### Quickstart Function Signature

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/cli/quickstart_cmd

The function signature for the quickstart command, accepting an optional force flag to overwrite existing configurations.

```python
quickstart(force: bool) -> None
```

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

### GET /skills

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/server/api_routes

Lists all currently installed skills.

```APIDOC
## GET /skills

### Description
List installed skills.

### Method
GET

### Endpoint
/skills

### Response
#### Success Response (200)
- **skills** (array) - List of installed skill objects
```

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

### Define setup method for EnvironmentProvider

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/evals/core/environment

Initializes the environment and returns connection details as a dictionary.

```python
@abstractmethod
def setup(self) -> Dict[str, Any]:
    """Start the environment and return connection info.

    Returns a dict with environment-specific connection details
    (e.g., URLs, ports, credentials).
    """
```

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

### Complete SDK workflow

Source: https://open-jarvis.github.io/OpenJarvis/user-guide/python-sdk

A comprehensive example showing initialization, indexing, querying, tool usage, and cleanup.

```python
from openjarvis import Jarvis

# Initialize with auto-detected engine
j = Jarvis(model="qwen3:8b")

# Index documents for context-augmented responses
result = j.memory.index("./docs/")
print(f"Indexed {result['chunks']} chunks from {result['path']}")

# Simple query with memory context
response = j.ask("What are the main features?")
print(response)

# Detailed query with agent and tools
full_result = j.ask_full(
    "Calculate the square root of 256 and add 10",
    agent="orchestrator",
    tools=["calculator"],
)
print(f"Answer: {full_result['content']}")
print(f"Turns: {full_result['turns']}")
print(f"Tools used: {[t['tool_name'] for t in full_result['tool_results']]}")

# Search memory directly
results = j.memory.search("configuration")
for r in results:
    print(f"  [{r['score']:.3f}] {r['source']}")

# List available models
print("Models:", j.list_models())

# Clean up
j.close()
```

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

### Install and Initialize OpenJarvis

Source: https://open-jarvis.github.io/OpenJarvis/user-guide/code-assistant

Clone the repository and initialize the environment with the code-assistant preset.

```bash
git clone https://github.com/open-jarvis/OpenJarvis.git
cd OpenJarvis
uv sync --extra dev
jarvis init --preset code-assistant
```

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

### Initialize and Use SyncEngine

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/connectors/sync_engine

Demonstrates the typical usage of the SyncEngine for initiating and resuming connector syncs. It shows how to set up the KnowledgeStore, IngestionPipeline, and SyncEngine, and then how to perform sync operations and retrieve checkpoints.

```python
store = KnowledgeStore(db_path=":memory:")
pipeline = IngestionPipeline(store)
engine = SyncEngine(pipeline)

items = engine.sync(connector)        # first run
items = engine.sync(connector)        # resumes from saved cursor
cp = engine.get_checkpoint(connector.connector_id)
```

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

### GET /v1/models

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/server/routes

Retrieves a list of locally installed models. Note that cloud models are excluded from this list.

```APIDOC
## GET /v1/models

### Description
List locally installed models (Ollama). Cloud models are not included here.

### Method
GET

### Endpoint
/v1/models

### Response
#### Success Response (200)
- **data** (array) - List of model objects containing model IDs.

#### Response Example
{
  "data": [
    { "id": "llama3" },
    { "id": "mistral" }
  ]
}
```

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

### GET /embeddings/{chunk_id}

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/connectors/embedding_store

Loads a chunk's embedding from disk. Returns None if the chunk has no stored embedding or if torch is not installed.

```APIDOC
## GET /embeddings/{chunk_id}

### Description
Loads a chunk's embedding from disk. Returns `None` if the chunk has no stored embedding or if `torch` is not installed.

### Method
GET

### Endpoint
/embeddings/{chunk_id}

#### Path Parameters
- **chunk_id** (str) - Required - The unique identifier for the chunk.

### Response
#### Success Response (200)
- **tensor** (torch.Tensor or None) - The embedding tensor for the chunk, or None if not found or torch is not installed.

#### Response Example
```json
{
  "tensor": [0.1, 0.2, 0.3, ...]
}
```
```

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

### Start Cloudflare Tunnel

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/cli/tunnel_cmd

Initiates a Cloudflare tunnel to a specified local port. Requires `cloudflared` to be installed. Press Ctrl+C to stop the tunnel.

```python
@click.group("tunnel", invoke_without_command=True)
@click.option("--port", default=8000, help="Local port to tunnel.")
@click.pass_context
def tunnel(ctx: click.Context, port: int) -> None:
    """Start a Cloudflare tunnel or manage config."""
    if ctx.invoked_subcommand is not None:
        return
    # Default behavior: start the tunnel
    if not shutil.which("cloudflared"):
        click.echo("Error: cloudflared is not installed.")
        click.echo(
            "Install it from: "
            "https://developers.cloudflare.com/"
            "cloudflare-one/connections/"
            "connect-networks/downloads/"
        )
        sys.exit(1)

    click.echo(f"Starting Cloudflare tunnel to localhost:{port}...")
    click.echo("Press Ctrl+C to stop.\n")

    try:
        subprocess.run(
            [
                "cloudflared",
                "tunnel",
                "--url",
                f"http://localhost:{port}",
            ],
            check=True,
        )
    except KeyboardInterrupt:
        click.echo("\nTunnel stopped.")
    except subprocess.CalledProcessError as e:
        click.echo(f"Tunnel failed: {e}")
        sys.exit(1)

```

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

### Set Up Speech Backend

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/cli/serve

Discovers and initializes the speech backend based on the system configuration. Logs debug information if discovery fails.

```python
speech_backend = None
try:
    from openjarvis.speech._discovery import get_speech_backend

    speech_backend = get_speech_backend(config)
    if speech_backend:
        console.print(f"  Speech: [cyan]{speech_backend.backend_id}[/cyan]")
except Exception as exc:
    logger.debug("Speech backend discovery failed: %s", exc)
```

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

### Generate Hint for No Config File

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/cli/hints

Use this function when the OpenJarvis configuration file is not found. It suggests initializing the config or running a quickstart setup.

```python
def hint_no_config() -> str:
    """Return a suggestion when no config file is found."""
    return (
        "[yellow]Hint:[/yellow] No config file found.\n"
        "  Run [bold]jarvis init[/bold] to detect hardware and generate "
        "[cyan]~/.openjarvis/config.toml[/cyan].\n"
        "  Or run [bold]jarvis quickstart[/bold] for a guided setup."
    )
```

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

### Initialize OptimizationStore

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/learning/optimize

Initializes the store with a database path, enabling WAL mode and creating necessary tables.

```python
def __init__(self, db_path: Union[str, Path]) -> None:
    self._db_path = str(db_path)
    self._conn = sqlite3.connect(self._db_path, check_same_thread=False)
    self._conn.execute("PRAGMA journal_mode=WAL")
    self._conn.execute(_CREATE_RUNS)
    self._conn.execute(_CREATE_TRIALS)
    self._conn.commit()
    self._migrate()
```

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

### Connect to Twitter API

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/channels/twitter

Builds a tweepy Client and optionally starts polling for mentions. Requires tweepy to be installed. Handles connection errors and logs status.

```python
def connect(self) -> None:
    """Build a tweepy Client and optionally start polling for mentions."""
    if not self._bearer_token:
        logger.warning("No Twitter bearer token configured")
        self._status = ChannelStatus.ERROR
        return

    self._stop_event.clear()

    try:
        import tweepy  # noqa: F401

        self._client = tweepy.Client(
            bearer_token=self._bearer_token,
            consumer_key=self._api_key or None,
            consumer_secret=self._api_secret or None,
            access_token=self._access_token or None,
            access_token_secret=self._access_secret or None,
        )
        self._status = ChannelStatus.CONNECTED
        logger.info("Twitter channel connected")

        if self._access_token:
            self._poll_thread = threading.Thread(
                target=self._poll_loop,
                daemon=True,
            )
            self._poll_thread.start()
    except ImportError:
        logger.info("tweepy not installed; Twitter channel unavailable")
        self._status = ChannelStatus.ERROR
    except Exception:
        logger.debug("Twitter connect failed", exc_info=True)
        self._status = ChannelStatus.ERROR
```

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

### Get Google Calendar Authorization URL

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/connectors/gcalendar

Generates a Google OAuth consent URL for read-only calendar access. If client ID is missing, it directs to the Google Cloud Console for credentials setup.

```python
def auth_url(self) -> str:
    """Return a Google OAuth consent URL requesting ``calendar.readonly`` scope."""
    tokens = load_tokens(self._credentials_path)
    client_id = ""
    if tokens:
        client_id = tokens.get("client_id", "")
    if not client_id:
        return "https://console.cloud.google.com/apis/credentials"
    return build_google_auth_url(
        client_id=client_id,
        scopes=GOOGLE_ALL_SCOPES,
    )
```

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

### Desktop App Setup and Maintenance

Source: https://open-jarvis.github.io/OpenJarvis/getting-started/installation

Commands for initializing the desktop environment and resolving macOS quarantine issues.

```bash
git clone https://github.com/open-jarvis/OpenJarvis.git
cd OpenJarvis
./scripts/quickstart.sh
```

```bash
xattr -cr /Applications/OpenJarvis.app
```

```bash
git clone https://github.com/open-jarvis/OpenJarvis.git
cd OpenJarvis/desktop
npm install
npm run tauri build
```

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

### Propose Initial Configuration with LLMOptimizer

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/optimize/llm_optimizer

Proposes a starting configuration using the LLM backend. Raises a ValueError if the optimizer_backend is not set.

```python
def propose_initial(self) -> TrialConfig:
    """Propose a reasonable starting config from the search space."""
    if self.optimizer_backend is None:
        raise ValueError("optimizer_backend is required to propose configurations")

    prompt = self._build_initial_prompt()
    response = self.optimizer_backend.generate(
        prompt,
        model=self.optimizer_model,
        system="You are an expert AI systems optimizer.",
        temperature=0.7,
        max_tokens=2048,
    )
    return self._parse_config_response(response)
```

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

### Add Extra Dependencies to OpenJarvis Image

Source: https://open-jarvis.github.io/OpenJarvis/deployment/docker

Modify the `RUN` command in your Dockerfile to include additional Python packages using `uv pip install`. This example adds support for vLLM and ColBERT memory backends.

```dockerfile
RUN pip install --no-cache-dir uv && \
    uv pip install --system ".[server,inference-vllm,memory-colbert]"

```

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

### Initialize TraceStore

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/traces

Initializes the SQLite database connection, sets up the schema, and enables WAL mode. It uses secure file creation if the path is not in-memory.

```python
def __init__(self, db_path: str | Path) -> None:
    self._db_path = str(db_path)
    if self._db_path != ":memory:":
        from openjarvis.security.file_utils import secure_create

        secure_create(Path(self._db_path))
    # check_same_thread=False is safe with WAL mode.  The
    # AgenticRunner dispatches agent work to a ThreadPoolExecutor
    # (for Playwright compat), so trace writes may originate from
    # a different thread than the one that opened the connection.
    self._conn = sqlite3.connect(self._db_path, check_same_thread=False)
    self._conn.execute("PRAGMA journal_mode=WAL")
    self._conn.execute(_CREATE_TRACES)
    self._conn.execute(_CREATE_STEPS)
    self._conn.execute(_CREATE_FTS)
    self._conn.execute(_FTS_SYNC_INSERT)
    # Migrate: add messages column if missing (pre-existing databases)
    try:
        self._conn.execute(
            "ALTER TABLE traces ADD COLUMN messages TEXT NOT NULL DEFAULT '[]'"
        )
    except sqlite3.OperationalError:
        pass  # Column already exists
    self._conn.commit()
```

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

### Connect Telegram Channel

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/channels/telegram

Starts listening for incoming messages via long polling. Logs a warning if no bot token is configured and sets the status to ERROR. Requires python-telegram-bot to be installed for full functionality; otherwise, it operates in send-only mode.

```python
connect() -> None
```

```python
def connect(self) -> None:
    """Start listening for incoming messages via long polling."""
    if not self._token:
        logger.warning("No Telegram bot token configured")
        self._status = ChannelStatus.ERROR
        return

    self._stop_event.clear()
    self._status = ChannelStatus.CONNECTING

    try:
        from telegram.ext import ApplicationBuilder  # noqa: F401

        self._listener_thread = threading.Thread(
            target=self._poll_loop,
            daemon=True,
        )
        self._listener_thread.start()
        self._status = ChannelStatus.CONNECTED
        logger.info("Telegram channel connected (long polling)")
    except ImportError:
        # python-telegram-bot not installed — send-only mode
        logger.info(
            "python-telegram-bot not installed; send-only mode",
        )
        self._status = ChannelStatus.CONNECTED
```

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

### Connect to Slack via Socket Mode

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/channels/slack

Starts listening for incoming messages using Slack Socket Mode. Requires a bot token and an app token for full functionality. If the slack-sdk is not installed or no app token is provided, it operates in send-only mode.

```python
def connect(self) -> None:
    """Start listening for incoming messages via Slack Socket Mode."""
    if not self._token:
        logger.warning("No Slack bot token configured")
        self._status = ChannelStatus.ERROR
        return

    self._stop_event.clear()
    self._status = ChannelStatus.CONNECTING

    try:
        from slack_sdk.socket_mode import SocketModeClient  # noqa: F401

        if not self._app_token:
            logger.info("No app token for Socket Mode; send-only mode")
            self._status = ChannelStatus.CONNECTED
            return

        self._listener_thread = threading.Thread(
            target=self._socket_mode_loop,
            daemon=True,
        )
        self._listener_thread.start()
        self._status = ChannelStatus.CONNECTED
        logger.info("Slack channel connected (Socket Mode)")
    except ImportError:
        logger.info("slack-sdk not installed; send-only mode")
        self._status = ChannelStatus.CONNECTED
```

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

### Initialize Hardware Configuration

Source: https://open-jarvis.github.io/OpenJarvis/user-guide/cli

Detects local hardware and generates a configuration file. Use --force to overwrite existing settings.

```bash
jarvis init           # Interactive — refuses to overwrite existing config
jarvis init --force   # Overwrite existing config without prompting
```

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

### Propose Initial Configuration

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/learning/optimize/llm_optimizer

Proposes a starting configuration from the search space. Requires the optimizer_backend to be initialized.

```python
propose_initial() -> TrialConfig
```

```python
def propose_initial(self) -> TrialConfig:
    """Propose a reasonable starting config from the search space."""
    if self.optimizer_backend is None:
        raise ValueError("optimizer_backend is required to propose configurations")

    prompt = self._build_initial_prompt()
    response = self.optimizer_backend.generate(
        prompt,
        model=self.optimizer_model,
        system="You are an expert AI systems optimizer.",
        temperature=0.7,
        max_tokens=2048,
    )
    return self._parse_config_response(response)
```

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

### Start TaskScheduler Polling

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/scheduler/scheduler

Starts the background thread that polls for due tasks. Ensures the thread is only started if not already running. Logs the scheduler start with the configured poll interval.

```python
def start(self) -> None:
    """Start the background polling daemon thread."""
    if self._thread is not None and self._thread.is_alive():
        return
    self._stop_event.clear()
    self._thread = threading.Thread(
        target=self._poll_loop, daemon=True, name="jarvis-scheduler"
    )
    self._thread.start()
    logger.info("Scheduler started (poll_interval=%ds)", self._poll_interval)
```

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

### Install Ollama and Pull Model

Source: https://open-jarvis.github.io/OpenJarvis/user-guide/chat-simple

Installs Ollama and downloads a specified language model. Ensure Ollama is installed before proceeding.

```bash
# Install Ollama: https://ollama.com
ollama pull qwen3.5:4b

```

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

### LLMOptimizer.propose_initial

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/learning/optimize/llm_optimizer

Proposes a reasonable starting configuration from the defined search space.

```APIDOC
## POST /llm_optimizer/propose_initial

### Description
Propose a reasonable starting config from the search space.

### Method
POST

### Endpoint
`/llm_optimizer/propose_initial`

### Parameters
#### Query Parameters
- **optimizer_backend** (Optional[InferenceBackend]) - Required - The backend for LLM inference. This is required to propose configurations.

### Response
#### Success Response (200)
- **TrialConfig** (object) - The proposed initial configuration.

### Response Example
```json
{
  "example": "TrialConfig object"
}
```
```

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

### OpenJarvis SDK Initialization and Usage

Source: https://open-jarvis.github.io/OpenJarvis/architecture/query-flow

Demonstrates how to initialize the Jarvis SDK and use its `ask` and `ask_full` methods for direct and agent modes. Includes examples of specifying models, engines, and tools.

```python
from openjarvis import Jarvis

j = Jarvis(model="qwen3:8b", engine_key="ollama")

# Direct mode
response = j.ask("Hello")

# Agent mode with tools
response = j.ask(
    "What is 2^10?",
    agent="orchestrator",
    tools=["calculator"],
)

# Full result with metadata
result = j.ask_full("Hello")
# {
#     "content": "Hello! How can I help you?",
#     "usage": {"prompt_tokens": 10, "completion_tokens": 15, "total_tokens": 25},
#     "model": "qwen3:8b",
#     "engine": "ollama",
# }

j.close()

```

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

### Install llama.cpp

Source: https://open-jarvis.github.io/OpenJarvis/getting-started/macos

Installs the local inference engine.

```bash
brew install llama.cpp
```

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

### Start GatewayDaemon

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/daemon/gateway

Starts the daemon process in the foreground.

```python
start() -> None
```

```python
def start(self) -> None:
    """Start the daemon (foreground)."""
    self._running = True
```

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

### Complete End-to-End Session

Source: https://open-jarvis.github.io/OpenJarvis/getting-started/quickstart

A comprehensive example demonstrating indexing, memory search, agent usage, and model listing.

```python
from openjarvis import Jarvis

# Initialize with defaults (auto-detect hardware and engine)
j = Jarvis()

# 1. Index some documentation
index_result = j.memory.index("./docs/", chunk_size=512)
print(f"Indexed {index_result['chunks']} chunks from {index_result['path']}")

# 2. Search memory
results = j.memory.search("how to configure engines")
for r in results:
    print(f"  [{r['score']:.3f}] {r['source']}")

# 3. Ask a question (memory context is injected automatically)
answer = j.ask("How do I configure the Ollama engine host?")
print(f"\nAnswer: {answer}")

# 4. Use an agent with tools
calc_result = j.ask_full(
    "Calculate the compound interest on $10,000 at 5% for 10 years",
    agent="orchestrator",
    tools=["calculator", "think"],
)
print(f"\nCalculation: {calc_result['content']}")
print(f"Tools used: {[t['tool_name'] for t in calc_result['tool_results']]}")
print(f"Agent turns: {calc_result['turns']}")

# 5. List available models
models = j.list_models()
print(f"\nAvailable models: {models}")

# 6. Clean up
j.close()
```

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

### Initialize and run SyncScheduler

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/connectors/scheduler

Demonstrates setting up the SyncScheduler with a SyncEngine and managing the lifecycle of background sync tasks.

```python
store = KnowledgeStore(db_path=":memory:")
pipeline = IngestionPipeline(store)
engine = SyncEngine(pipeline)

scheduler = SyncScheduler(engine, interval_seconds=3600)
scheduler.add(gmail_connector)
scheduler.add(slack_connector)
scheduler.start()       # background thread syncs every hour

# Later:
scheduler.stop()
```

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

### GET /memory/stats

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/server/api_routes

Get memory backend statistics.

```APIDOC
## GET /memory/stats

### Description
Get memory backend statistics.

### Method
GET

### Endpoint
/memory/stats

### Response
#### Success Response (200)
- The response contains statistics about the memory backend. The exact fields may vary depending on the backend implementation.

#### Response Example
```json
{
  "total_items": 1500,
  "storage_size_bytes": 1024000,
  "last_cleaned": "2023-10-26T12:00:00Z"
}
```
```

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

### Initialize KnowledgeStore

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/connectors/store

Constructor signature for the KnowledgeStore class.

```python
KnowledgeStore(db_path: Union[str, Path] = '')
```

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

### Set up Channel Backend

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/cli/serve

Initializes the SystemBuilder to set up the channel backend if it is enabled and a default channel is configured.

```python
from openjarvis.system import SystemBuilder

channel_bridge = None
if config.channel.enabled and config.channel.default_channel:
    try:
        # Reuse _resolve_channel logic from SystemBuilder
        sb = SystemBuilder(config)
```

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

### Install Node.js

Source: https://open-jarvis.github.io/OpenJarvis/getting-started/macos

Installs Node.js required for the browser frontend.

```bash
brew install node
```

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

### Initialize Knowledge Graph Tools

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/tools/knowledge_tools

Constructor methods for KGAddEntityTool, KGAddRelationTool, KGQueryTool, and KGNeighborsTool.

```python
KGAddEntityTool(backend: Optional[Any] = None)
```

```python
def __init__(self, backend: Optional[Any] = None) -> None:
    self._backend = backend
```

```python
KGAddRelationTool(backend: Optional[Any] = None)
```

```python
KGQueryTool(backend: Optional[Any] = None)
```

```python
KGNeighborsTool(backend: Optional[Any] = None)
```

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

### Install uv

Source: https://open-jarvis.github.io/OpenJarvis/getting-started/macos

Installs the uv package manager for Python.

```bash
brew install uv
```

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

### Install Homebrew

Source: https://open-jarvis.github.io/OpenJarvis/getting-started/macos

Installs the standard macOS package manager.

```bash
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
```

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

### Build Workflow with Agents and Connections

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/workflow/builder

Example demonstrating how to add agents and connect them sequentially to build a research pipeline workflow. Requires agents and tools to be defined.

```python
wf = (WorkflowBuilder("research_pipeline")
    .add_agent("researcher", agent="orchestrator", tools=["web_search"])
    .add_agent("summarizer", agent="simple")
    .connect("researcher", "summarizer")
    .build())
```

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

### start()

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/telemetry/session

Starts the background sampling thread for the telemetry session.

```APIDOC
## start()

### Description
Starts the background sampling thread if a monitor is configured and the thread is not already running.
```

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

### Troubleshoot Model Loading

Source: https://open-jarvis.github.io/OpenJarvis/getting-started/macos

Example of running the server with a specific model path.

```bash
llama-server -m ~/models/Qwen_Qwen3-4B-Q4_K_M.gguf
```

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

### GET /traces/{trace_id}

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/server/api_routes

Get a specific trace by ID.

```APIDOC
## GET /traces/{trace_id}

### Description
Get a specific trace by ID.

### Method
GET

### Endpoint
/traces/{trace_id}

### Parameters
#### Path Parameters
- **trace_id** (str) - Required - The ID of the trace to retrieve.

### Response
#### Success Response (200)
- The response contains the details of the specified trace.

#### Response Example
```json
{
  "id": "trace-123",
  "timestamp": "2023-10-27T10:30:00Z",
  "name": "User Query Processing",
  "steps": [
    {
      "action": "Search",
      "input": "What is the capital of France?",
      "output": "Paris"
    }
  ]
}
```
```

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

### Clone and Install OpenJarvis Development Dependencies

Source: https://open-jarvis.github.io/OpenJarvis/development/contributing

Clone the repository and install development dependencies using uv. This command installs the package in editable mode with essential development tools.

```bash
git clone https://github.com/open-jarvis/OpenJarvis.git
cd OpenJarvis
uv sync --extra dev
```

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

### KnowledgeStore Initialization

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/connectors/store

Initializes the KnowledgeStore with a specified database path, defaulting to the system configuration directory if none is provided.

```APIDOC
## KnowledgeStore(db_path: Union[str, Path] = '')

### Description
Initializes a source-aware SQLite/FTS5 knowledge store for Deep Research. It extends the MemoryBackend to store document chunks with provenance metadata.

### Parameters
#### Path Parameters
- **db_path** (Union[str, Path]) - Optional - The file system path to the SQLite database file. If empty, defaults to the system's default configuration directory.
```

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

### Example Tasks

Source: https://open-jarvis.github.io/OpenJarvis/user-guide/code-assistant

Common use cases for the OpenJarvis agent.

```bash
# Write a new script
jarvis ask "Write a Python script that converts YAML to JSON"

# Explain existing code
jarvis ask "Read src/openjarvis/core/events.py and explain the EventBus pattern"

# Debug a failing test
jarvis ask "Run pytest tests/test_memory.py -v and fix any failures"

# Refactor code
jarvis ask "Read utils.py and refactor the parse_config function to use dataclasses"

# Generate tests
jarvis ask "Read src/openjarvis/tools/calculator.py and write unit tests for it"

# Shell tasks
jarvis ask "Find all Python files larger than 100KB in this repo"
```

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

### Install Python Dependencies

Source: https://open-jarvis.github.io/OpenJarvis/getting-started/macos

Installs project dependencies including the server backend.

```bash
uv sync --extra dev --extra server
```

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

### Start iMessage Daemon

Source: https://open-jarvis.github.io/OpenJarvis/api-reference/openjarvis/server/agent_manager_routes

Starts the iMessage daemon if the channel type is 'imessage' and an identifier is provided. It checks if the daemon is already running and starts it in a new thread if not. Requires an engine and tools to be available.

```python
if req.channel_type == "imessage":
    identifier = (req.config or {}).get("identifier", "")
    if identifier:
        try:
            from openjarvis.channels.imessage_daemon import (
                is_running,
                run_daemon,
            )

            if not is_running():
                import threading

                engine = getattr(request.app.state, "engine", None)
                if engine:
                    from openjarvis.server.agent_manager_routes import (
                        _build_deep_research_tools,
                    )

                    tools = _build_deep_research_tools(engine=engine, model="")
                    if tools:
                        from openjarvis.agents.deep_research import (
                            DeepResearchAgent,
                        )

                        agent_inst = DeepResearchAgent(
                            engine=engine,
                            model=getattr(engine, "_model", ""),
                            tools=tools,
                        )

                        def handler(text: str) -> str:
                            result = agent_inst.run(text)
                            return result.content or "No results."

                        t = threading.Thread(
                            target=run_daemon,
                            kwargs={
                                "chat_identifier": identifier,
                                "handler": handler,
                            },
                            daemon=True,
                        )
                        t.start()
        except Exception as exc:
```

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

### Initialize Jarvis with Hardware Detection

Source: https://open-jarvis.github.io/OpenJarvis/architecture/design-principles

Run 'jarvis init --force' to automatically detect system hardware and configure the default inference engine in '~/.openjarvis/config.toml'. This ensures optimal performance by selecting the best engine for your hardware.

```bash
jarvis init --force
# Detects hardware, writes ~/.openjarvis/config.toml with:
# [engine]
# default = "vllm"  # (for A100)

```

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

### Install and Configure Rust

Source: https://open-jarvis.github.io/OpenJarvis/getting-started/macos

Installs Rust and configures the environment for compiling the OpenJarvis extension.

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
```

```bash
source "$HOME/.cargo/env"
```

```bash
rustc --version
```