OpenJarvis

https://open-jarvis.github.io/OpenJarvis
Admin
OpenJarvis is a research framework for building composable, on-device personal AI systems that run...
Tokens:1,403,681
Snippets:9,488
Trust Score:9.7
Update:2 weeks ago
Show doc for...
Tokens:
Raw
### Quickstart script for browser app

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

One-command setup for the browser app. Clones the repository and runs the quickstart script, which checks for Python 3.10–3.13 and Node.js 18+, installs Ollama if needed, pulls a starter model, installs dependencies, starts the backend and frontend servers, and opens http://localhost:5173.

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

```

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

### quickstart command implementation

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

Full implementation of the quickstart command, a 5-step guided setup that detects hardware, writes config, checks engine health, verifies models, and runs a test query. Uses --force to redo steps even if config exists. Exits with SystemExit(1) if engine unreachable or no models found.

```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]'
    )
```

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

### Start Ollama and pull starter model

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

Manual setup step 2: start the Ollama server in the background and pull the qwen3:0.6b model. Requires Ollama to be installed first.

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

```

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

### start command with --install option

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

Implements the `start` subcommand. With `--install`, it generates and enables a systemd/launchd service; otherwise it prints a foreground start message.

```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.")
```

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

### Run OpenJarvis quickstart script

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

Quickstart script that clones the repository九 runs the quickstart.sh script. The script checks for Python 3.10+ and Node.js 18+, installs Ollama if missing, pulls a starter model, installs dependencies, starts the backend and frontend, and opens http://localhost:5173.

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

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

### Quickstart script to clone and start backend

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

Clones the OpenJarvis repository and runs the quickstart script, which starts the backend required by the desktop app. Run this before opening the desktop app.

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

```

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

### Clone and install dependencies for manual browser setup

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

Manual setup step 1: clone the repository, sync Python dependencies with the desktop extra, and install frontend dependencies.

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

```

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

### Start frontend dev server

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

Manual setup step 4: start the frontend development server. Then open http://localhost:5173.

```bash
cd frontend
npm run dev

```

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

### Install server extra with uv sync --extra server

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

Installs the server extra, which is required to start the API server.

```bash
uv sync --extra server

```

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

### Energy monitor setup and benchmark execution

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

Sets up an energy monitor if requested and available, then runs benchmarks and outputs results. Handles setup failures with a hint to install the appropriate extra.

```python
setup_script = (
    Path(__file__).resolve().parents[3] / "scripts" / "setup-energy-monitor.sh"
)
is_darwin_arm = platform.system() == "Darwin" and platform.machine() == "arm64"
extra_hint = (
    "openjarvis[energy-apple]"
    if is_darwin_arm
    else "openjarvis[gpu-metrics]"
    if platform.system() == "Linux"
    else "openjarvis[energy-all]"
)
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,
            allow_estimates=config.telemetry.allow_energy_estimates,
        )
        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)

# Banner + configuration
_print_banner(console)
_section(console, "Configuration")
bench_names = [b.name for b in benchmarks]
config_panel = Panel(
    f"[cyan]Engine:[/cyan]     {engine_name}\n"
    f"[cyan]Model:[/cyan]      {model_name}\n"
    f"[cyan]Benchmarks:[/cyan] {', '.join(bench_names)}\n"
    f"[cyan]Samples:[/cyan]    {num_samples}\n"
    f"[cyan]Warmup:[/cyan]     {warmup}",
    title="[bold]Run Configuration[/bold]",
    border_style="blue",
    expand=False,
)
console.print(config_panel)

# Run benchmarks
_section(console, "Execution")
with console.status(
    f"[bold cyan]Running {len(benchmarks)} benchmark(s)...[/bold cyan]",
):
    results = suite.run_all(
        engine,
        model_name,
        num_samples=num_samples,
        warmup_samples=warmup,
        energy_monitor=energy_monitor,
    )

# Output results
if output_path:
    jsonl = suite.to_jsonl(results)
    with open(output_path, "w") as fh:
        fh.write(jsonl + "\n")
    console.print(f"[green]Results written to {output_path}[/green]")

if output_json:
    summary = suite.summary(results)
    click.echo(json_mod.dumps(summary, indent=2))
elif not output_path:
    # Pretty-print results as Rich tables
    _section(console, "Results")
    for r in results:
        _render_stats_table(console, r)

# Cleanup energy monitor
if energy_monitor is not None:
    try:
        energy_monitor.close()
    except Exception as exc:
        logger.debug("Energy monitor cleanup failed: %s", exc)
```

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

### Set web search API keys and start quickstart

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

Exports optional web search API keys before starting quickstart to raise rate limits or use Tavily or Serply instead of the default You.com keyless tier. The script does not automatically source .env files; run source .env first if keys are stored there.

```bash
export YOUDOTCOM_API_KEY="..."   # free key: https://you.com/platform
export SERPLY_API_KEY="..."      # free tier: https://serply.io
./scripts/quickstart.sh
```

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

### Start backend API server

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

Manual setup step 3: start the backend API server on port 8000.

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

```

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

### Install CLI

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

Install the CLI by cloning the repository and syncing Python dependencies.

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

```

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

### start()

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

Starts the background sampling thread for telemetry monitoring.

```APIDOC
## start()

### Description
Starts the background sampling thread for telemetry monitoring.

### Method
start()

### Signature
```python
def start(self) -> None
```

### Parameters
None

### Returns
None

### Source Code
```python
def start(self) -> None:
    """Start background sampling thread."""
    if self._monitor is None:
        return
    if self._thread is not None and self._thread.is_alive():
        return
    self._stop_event.clear()
    self._thread = threading.Thread(target=self._sample_loop, daemon=True)
    self._thread.start()
```
```

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

### Install AFM backend with uv sync

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

Install the AFM backend. Requires a full Xcode installation because the SDK compiles Swift bindings at install time; Command Line Tools alone fail. The DEVELOPER_DIR environment variable points to the Xcode developer directory.

```bash
DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer \
    uv sync --extra afm

```

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

### EventRecorder usage example

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

Example usage of the EventRecorder: record events with metadata, then retrieve them. The example shows recording tool call start and end events and getting the events list.

```python
>>> recorder = EventRecorder()
>>> recorder.record('tool_call_start', tool='calculator')
>>> recorder.record('tool_call_end', tool='calculator')
>>> events = recorder.get_events()
>>> len(events)
2
```

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

### Start backend and frontend with quickstart.sh

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

Starts the backend server and the React frontend, opening http://localhost:5173 with a full chat interface, streaming responses, and an energy monitoring dashboard.

```bash
./scripts/quickstart.sh

```

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

### EnvironmentProvider.setup

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

Abstract method to start the environment and return connection info as a dictionary with environment-specific details.

```APIDOC
## setup()

### Description
Start the environment and return connection info.

### Method
setup (abstract method)

### Signature
```python
setup() -> Dict[str, Any]
```

### Parameters
None

### Returns
- **Dict[str, Any]** - Connection details (e.g., URLs, ports, credentials).

### Source Code
```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).
    """
```
```

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

### hint_no_config function

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

Returns a suggestion when no config file is found. Suggests running `jarvis init` to detect hardware and generate `~/.openjarvis/config.toml`, or `jarvis quickstart` for guided 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."
    )
```

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

### hint_no_engine function

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

Returns a suggestion when the inference engine is unreachable. Defaults to 'ollama' if no engine name is provided. Suggests running `jarvis doctor` to check all engines and `jarvis quickstart` for guided setup, and shows how to configure a remote engine host.

```python
def hint_no_engine(engine_name: Optional[str] = None) -> str:
    """Return a suggestion when the inference engine is unreachable."""
    name = engine_name or "ollama"
    return (
        f"[yellow]Hint:[/yellow] Engine '{name}' is not reachable.\n"
        f"  Make sure the {name} server is running.\n"
        "  Run [bold]jarvis doctor[/bold] to check all engines.\n"
        "  Run [bold]jarvis quickstart[/bold] for guided setup.\n"
        "\n"
        "  [dim]To use a remote engine:[/dim]\n"
        f"    [cyan]jarvis config set engine.{name}.host http://<remote-ip>:<port>[/cyan]\n"
        f"    [dim]or[/dim] [cyan]export OLLAMA_HOST=http://<remote-ip>:11434[/cyan]"
    )
```

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

### Run spec_search_quickstart.py

Source: https://open-jarvis.github.io/OpenJarvis/user-guide/llm-guided-spec-search

Runs the self-contained quickstart script. It requires no API key or Ollama and wires up a real orchestrator, multi-session loop, and composite-reward modules with stub teacher/student/judge so you can observe one full session and a stagnation loop terminate. Production swap-points are commented inline.

```bash
python examples/openjarvis/spec_search_quickstart.py
```

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

### Install WSL2 with wsl --install

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

Run this command in an admin PowerShell to install WSL2. After it completes, open the Ubuntu (or Debian) shell that gets installed.

```powershell
wsl --install

```

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

### Run privacy check and print getting started panel

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

Runs a quick privacy check unless skip_scan is set, then prints a 'Getting Started' panel with next steps using the selected engine and model.

```python
if not skip_scan:
    _quick_privacy_check(console)
console.print()
console.print(
    Panel(
        _next_steps_text(selected_engine, model),
        title="Getting Started",
        border_style="cyan",
    )
)
```

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

### Install and initialize the code assistant

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

Clones the OpenJarvis repository, installs dependencies with uv, and initializes the code assistant preset. The --force flag overwrites any existing configuration.

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

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

### Install Hermes Tweet skill from GitHub

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

Example: install the Hermes Tweet skill for Twitter/X workflows (search, read replies, monitor, export followers, gated post/reply/DM).

```bash
jarvis skill install github:Xquik-dev/hermes-tweet/skills/hermes-tweet --url https://github.com/Xquik-dev/hermes-tweet
```

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

### Start server with custom options

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

Starts the server with custom options: host, port, engine, model, and agent.

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

```

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

### ApprovalStore.__init__ implementation

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

Initializes the ApprovalStore, creating the parent directory if needed, connecting to the SQLite database with WAL mode, creating tables, and committing.

```python
def __init__(self, db_path: str = "") -> None:
    if not db_path:
        db_path = str(get_config_dir() / "approvals.db")
    self._db_path = db_path
    Path(db_path).parent.mkdir(parents=True, exist_ok=True)
    self._conn = sqlite3.connect(db_path, check_same_thread=False)
    self._conn.execute("PRAGMA journal_mode=WAL")
    self._create_tables()
    self._conn.commit()
```

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

### GET /skills

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

Lists all installed skills. Returns an array of skill names, or an empty array if an error occurs.

```APIDOC
## GET /skills

### Description
List installed skills.

### Method
GET

### Endpoint
/skills

### Response
#### Success Response (200)
- **skills** (array) - List of installed skills, each with a "name" field.

#### Error Response (200 with empty skills)
- **skills** (array) - Empty array if listing fails.

### Response Example
{
  "skills": [
    {
      "name": "example_skill"
    }
  ]
}
```

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

### KnowledgeStore.__init__

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

Initializes the KnowledgeStore with a database path, creating the database file if needed and setting up the connection.

```APIDOC
## KnowledgeStore.__init__

### Description
Initializes the KnowledgeStore with a database path, creating the database file if needed and setting up the connection.

### Method
Constructor

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

### Parameters
- **db_path** (Union[str, Path]) - Optional - Path to the SQLite database file. If empty, defaults to `DEFAULT_CONFIG_DIR/knowledge.db`.

### Example
```python
store = KnowledgeStore()
```
```

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

### setup_security implementation

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

Full implementation of setup_security. It applies security guardrails: sets up scanners (secret and PII), wraps the engine with GuardrailsEngine, initializes capability policy, rate limiter, and audit logger. Raises RuntimeError for capability policy or rate limiter failures in certain profiles.

```python
def setup_security(
    config: Any,
    engine: Any,
    bus: Optional[EventBus] = None,
) -> SecurityContext:
    """Apply security guardrails to an engine based on config.

    Returns a SecurityContext. No-ops if config.security.enabled is False.
    """
    if not config.security.enabled:
        return SecurityContext(engine=engine)

    from openjarvis.security._stubs import BaseScanner
    from openjarvis.security.audit import AuditLogger
    from openjarvis.security.guardrails import GuardrailsEngine
    from openjarvis.security.scanner import PIIScanner, SecretScanner
    from openjarvis.security.types import RedactionMode

    # Scanners + engine wrapping
    try:
        scanners: list[BaseScanner] = []
        if config.security.secret_scanner:
            scanners.append(SecretScanner())
        if config.security.pii_scanner:
            scanners.append(PIIScanner())

        if scanners:
            mode = RedactionMode(config.security.mode)
            engine = GuardrailsEngine(
                engine,
                scanners=scanners,
                mode=mode,
                scan_input=config.security.scan_input,
                scan_output=config.security.scan_output,
                bus=bus,
            )
    except Exception as exc:
        logger.debug("Failed to set up security scanners: %s", exc)

    # Capability policy
    cap_policy = None
    if config.security.capabilities.enabled:
        try:
            from openjarvis.security.capabilities import CapabilityPolicy

            cap_policy = CapabilityPolicy(
                policy_path=config.security.capabilities.policy_path or None,
                default_deny=config.security.capabilities.default_deny,
            )
            # No explicit policy file: grant a conservative baseline to the
            # "_default" wildcard agent so default-deny doesn't silently
            # break every managed agent (whose UUIDs aren't known ahead of
            # time). Read/fetch/memory only — writes, code execution, and
            # admin tools require an explicit per-agent grant.
            if (
                config.security.capabilities.default_deny
                and not config.security.capabilities.policy_path
            ):
                for cap in (
                    "file:read",
                    "network:fetch",
                    "memory:read",
                    "memory:write",
                ):
                    cap_policy.grant("_default", cap)
        except Exception as exc:
            # Explicitly enabled enforcement is a contract in every profile.
            # Missing native support or an invalid policy must not produce an
            # unrestricted executor merely because the profile is personal.
            raise RuntimeError("Capability policy initialization failed") from exc

    # Rate limiter — config.security.rate_limit_* were previously read by
    # nothing; this is the first thing in the codebase that actually turns
    # them into an enforced limiter.
    rate_limiter = None
    if config.security.rate_limit_enabled:
        try:
            from openjarvis.security.rate_limiter import RateLimitConfig, RateLimiter

            rate_limiter = RateLimiter(
                RateLimitConfig(
                    requests_per_minute=config.security.rate_limit_rpm,
                    burst_size=config.security.rate_limit_burst,
                    enabled=True,
                )
            )
        except Exception as exc:
            if config.security.profile in {"shared", "server"}:
                raise RuntimeError("Rate limiter initialization failed") from exc
            logger.warning("Failed to set up rate limiter: %s", exc)

    # Audit logger
    audit = None
    try:
        audit = AuditLogger(
            db_path=config.security.audit_log_path,
            bus=bus,
        )
    except Exception as exc:
        logger.debug("Failed to set up audit logger: %s", exc)

    return SecurityContext(
        engine=engine,
        capability_policy=cap_policy,
        audit_logger=audit,
        rate_limiter=rate_limiter,
    )
```

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

### get

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(chunk_id: str) -> Optional['torch.Tensor']

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

### Method
`get`

### Parameters
- **chunk_id** (str) - Required - The identifier of the chunk whose embedding is to be loaded.

### Returns
- **Optional[torch.Tensor]** - The embedding tensor for the chunk, or `None` if not found or `torch` is not installed.
```

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

### GmailChannel connect implementation

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

Connects to Gmail using OAuth2. Loads credentials from token file or runs local server flow if needed. Starts a polling thread. Requires Google API libraries; install with pip install openjarvis[channel-gmail].

```python
def connect(self) -> None:
    """Load OAuth2 credentials and build the Gmail API service."""
    if not self._credentials_path and not self._token_path:
        logger.warning("No Gmail credentials configured")
        self._status = ChannelStatus.ERROR
        return

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

    try:
        from google.oauth2.credentials import Credentials
        from google_auth_oauthlib.flow import InstalledAppFlow
        from googleapiclient.discovery import build

        SCOPES = ["https://www.googleapis.com/auth/gmail.modify"]

        creds: Any = None
        if self._token_path and os.path.exists(self._token_path):
            creds = Credentials.from_authorized_user_file(
                self._token_path,
                SCOPES,
            )

        if not creds or not creds.valid:
            if creds and creds.expired and creds.refresh_token:
                from google.auth.transport.requests import Request

                creds.refresh(Request())
            elif self._credentials_path and os.path.exists(
                self._credentials_path,
            ):
                flow = InstalledAppFlow.from_client_secrets_file(
                    self._credentials_path,
                    SCOPES,
                )
                creds = flow.run_local_server(port=0)
            else:
                logger.warning("Gmail credentials not found or invalid")
                self._status = ChannelStatus.ERROR
                return

            # Save token for future use
            if self._token_path and creds:
                with open(self._token_path, "w") as token_file:
                    token_file.write(creds.to_json())

        self._service = build("gmail", "v1", credentials=creds)
        self._status = ChannelStatus.CONNECTED
        logger.info("Gmail channel connected")

        # Start polling thread
        self._listener_thread = threading.Thread(
            target=self._poll_loop,
            daemon=True,
        )
        self._listener_thread.start()
    except ImportError:
        logger.warning(
            "Google API libraries not installed; "
            "install with: pip install openjarvis[channel-gmail]",
        )
        self._status = ChannelStatus.ERROR
    except Exception:
        logger.debug("Gmail connect failed", exc_info=True)
        self._status = ChannelStatus.ERROR
```

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

### Set up configuration file for OpenJarvis

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

Creates the configuration directory and copies config.toml to the expected location. The server reads ~/.openjarvis/config.toml on startup, where ~ resolves from the HOME environment variable.

```bash
sudo -u openjarvis mkdir -p /opt/openjarvis/.openjarvis
sudo -u openjarvis cp config.toml /opt/openjarvis/.openjarvis/config.toml

```

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

### Complete example of OpenJarvis SDK usage

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

Shows initialization with auto-detected engine, indexing documents, simple and detailed queries with agent and tools, memory search, listing models, 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()

```

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

### GET /identity

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

Returns the analytics identity for the current install. If analytics is disabled, returns a structurally valid response with enabled=False. No authentication required.

```APIDOC
## GET /identity

### Description
Returns the analytics identity for the current install. If analytics is disabled in config, still returns a structurally valid response with `enabled=False` so the frontend can decide what to do; never throws.

### Method
GET

### Endpoint
/identity

### Parameters
None

### Response
#### Success Response (200)
- **enabled** (boolean) - Whether analytics is enabled.
- **anon_id** (string) - The anonymous identity ID, empty if disabled.
- **host** (string) - The PostHog host.
- **key** (string) - The PostHog project key, empty if disabled.

#### Response Example
{
  "enabled": true,
  "anon_id": "generated-or-existing-id",
  "host": "https://posthog.example.com",
  "key": "public-project-key"
}
```

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

### Run OpenJarvis server

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

Starts the OpenJarvis server after installation. The server binds to 127.0.0.1 by default, so no API key is required. Verify by opening http://127.0.0.1:8000/health.

```powershell
cd "$env:LOCALAPPDATA\OpenJarvis\src"
uv run jarvis serve
```

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

### Install and initialize OpenJarvis with chat-simple preset

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

Clones the OpenJarvis repository, installs dependencies with uv, and initializes the chat-simple preset, overwriting any existing configuration.

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

```

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

### Combine optional extras

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

Combine multiple optional extras in a single `uv sync` command. This example installs the desktop, memory-faiss, and inference-cloud extras together.

```bash
uv sync --extra desktop --extra memory-faiss --extra inference-cloud
```

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

### Set default model with OPENJARVIS_MODEL

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

Sets the default model via the OPENJARVIS_MODEL environment variable before starting quickstart. Replace deepseek-r1:14b with your desired model name.

```bash
OPENJARVIS_MODEL=deepseek-r1:14b ./scripts/quickstart.sh
```

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

### Initialize Jarvis with Core SDK Pattern

Source: https://open-jarvis.github.io/OpenJarvis/tutorials/code-companion

Demonstrates the standard setup for the OpenJarvis SDK, including client initialization, agent selection, and tool configuration.

```python
from openjarvis import Jarvis

j = Jarvis(model="qwen3:8b", engine_key="ollama")  
try:
    response = j.ask(
        prompt,                      
        agent="native_react",        
        tools=["git_diff", "think"], 
    )
    print(response)
finally:
    j.close()
```

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

### get method implementation

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. Handles stale index entries by deleting them.

```python
def get(self, chunk_id: str) -> Optional["torch.Tensor"]:
    """Load a chunk's embedding from disk.

    Returns ``None`` if the chunk has no stored embedding or if
    ``torch`` is not installed.
    """
    try:
        import torch as _torch  # noqa: F401
    except ImportError:
        return None

    row = self._conn.execute(
        "SELECT filename FROM embedding_index WHERE chunk_id = ?",
        (chunk_id,),
    ).fetchone()

    if row is None:
        return None

    tensor_path = self._tensor_dir / row[0]
    if not tensor_path.exists():
        # Stale index entry --- clean it up
        self._conn.execute(
            "DELETE FROM embedding_index WHERE chunk_id = ?", (chunk_id,)
        )
        self._conn.commit()
        return None

    try:
        return _torch.load(str(tensor_path), weights_only=True)
    except Exception as exc:
        logger.warning(
            "EmbeddingStore.get: failed to load tensor for %s (%s)", chunk_id, exc
        )
        return None
```

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

### propose_initial implementation

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

Implementation of propose_initial. Raises ValueError if optimizer_backend is None, builds an initial prompt, calls the backend's generate method with the specified model, system prompt, temperature 0.7, and max_tokens 2048, then parses the response into a 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)
```

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

### Output of jarvis init

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

Example output from running `jarvis init`, showing detected hardware details and confirmation that the config was written.

```text
Detecting hardware...
  Platform : linux
  CPU      : AMD EPYC 7763 (128 cores)
  RAM      : 512.0 GB
  GPU      : NVIDIA A100 (80.0 GB VRAM, x8)

Config written successfully.

```

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

### telemetry_stats - Get aggregated telemetry statistics

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

Async route handler for GET /stats on telemetry_router. Uses TelemetryAggregator to summarize telemetry data since session start, returning zeros if the database file does not exist. Removes per_model and per_engine fields, renames total_calls to total_requests, and returns an error dict on exception.

```python
@telemetry_router.get("/stats")
async def telemetry_stats(request: Request):
    """Get aggregated telemetry statistics."""
    try:
        from dataclasses import asdict

        from openjarvis.telemetry.aggregator import TelemetryAggregator

        db_path = _telemetry_db_path(request)
        if not db_path.exists():
            return {"total_requests": 0, "total_tokens": 0}

        session_start = getattr(request.app.state, "session_start", None)
        agg = TelemetryAggregator(db_path)
        try:
            stats = agg.summary(since=session_start)
            d = asdict(stats)
            d.pop("per_model", None)
            d.pop("per_engine", None)
            d["total_requests"] = d.pop("total_calls", 0)
            return d
        finally:
            agg.close()
    except Exception as exc:
        return {"error": str(exc)}
```

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

### jarvis gui

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

Starts the browser-based graphical mode in the default browser. This command is intended for source checkouts; for installed desktop applications, launch OpenJarvis from the operating system menu instead.

```APIDOC
## jarvis gui

### Description
Starts the browser-based graphical mode in the default browser. This command is intended for source checkouts; for installed desktop applications, launch OpenJarvis from the operating system menu instead.

### Method
CLI

### Endpoint
`jarvis gui`

### Parameters
#### Options
- `--frontend-port` (int) - Optional - Port for the frontend server. Default: 5173. Range: 1-65535.
- `--api-port` (int) - Optional - Port for the API server. Default: 8000. Range: 1-65535.
- `--no-server` (flag) - Optional - Do not start the API server.
- `--no-browser` (flag) - Optional - Only start the frontend.

### Request Example
```
jarvis gui --frontend-port 5173 --api-port 8000
```

### Response
#### Success Response
- The graphical mode is ready and the URL is printed: `http://127.0.0.1:<frontend_port>`
- The default browser is opened unless `--no-browser` is specified.

#### Response Example
```
OpenJarvis graphical mode is ready: http://127.0.0.1:5173
```

### Error Handling
- If the graphical frontend is not available, an error is raised: "The graphical frontend is not available in this installation."
- If Node.js/npm is not installed, an error is raised: "Node.js/npm is required for graphical mode."
- If `uv` is not installed and `--no-server` is not used, an error is raised: "uv is required to start the API with desktop dependencies."
- If the API server fails to start, an error is raised: "Could not start the OpenJarvis API server."
- If the frontend does not start on the requested port, an error is raised: "The graphical frontend did not start on the requested port."
```

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

### Hardware detection and engine recommendation via jarvis init

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

Runs jarvis init --force to detect hardware and write the recommended engine to ~/.openjarvis/config.toml, as shown in the comment.

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

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

### Install Xcode Command Line Tools

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

Pre-installs the Xcode Command Line Tools, which macOS prompts for the first time you run git or curl. Accept the prompt to get both tools.

```bash
xcode-select --install
```

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

### TraceStore.__init__ implementation

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

Initializes the SQLite connection with WAL mode, creates necessary tables, and migrates existing databases by adding a messages column if missing. Uses check_same_thread=False and a lock to support multi-threaded writes.

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

        secure_create(Path(self._db_path))
    # 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.
    # check_same_thread=False permits that use, but WAL does not serialize
    # operations on one connection, so use a lock too.
    self._db_lock = threading.RLock()
    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()
```

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

### Quick Start: Initialize and Run Pearl Miner

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

Quick start sequence for Pearl mining with vLLM. Sets up the environment, initializes the mining config, starts the miner, and checks status. Requires a Pearl node and wallet address.

```bash
uv sync --extra mining-pearl-vllm
export PEARLD_RPC_PASSWORD=<your-pearld-password>
export HF_TOKEN=<your-huggingface-token>

uv run jarvis mine init
uv run jarvis mine start
uv run jarvis mine status

```
Tokens:
Raw