> ## Documentation Index
> Fetch the complete documentation index at: https://docs.junis.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Junis Desktop Agent

> Give your AI agents full control over your device with a single command

## What is Junis Desktop Agent?

**Junis Desktop Agent** (`npx junis`) is a CLI tool that connects your local device to the Junis platform, enabling AI agents to control your computer. File management, terminal commands, browser automation, and more — all accessible to your AI agents through a secure connection.

> One command. One login click. Full device control for your AI agents.

```bash theme={null}
npx junis
```

<Info>
  **Zero Configuration**: Run the command, click login, and your device is connected. AI agents can immediately start working on your machine.
</Info>

***

## Why Use Junis Desktop Agent?

<CardGroup cols={2}>
  <Card title="Complete Device Control" icon="desktop">
    AI agents can read/write files, execute commands, automate browsers, and interact with your OS — all through your Junis agents.
  </Card>

  <Card title="One-Line Setup" icon="terminal">
    No complex configuration. Run `npx junis`, authenticate once, and you're connected.
  </Card>

  <Card title="Secure Connection" icon="shield-check">
    OAuth-based authentication with encrypted WebSocket relay. Your device connects outbound — no open ports required.
  </Card>

  <Card title="Two Operating Modes" icon="toggle-on">
    Use **Cloud Mode** for remote AI access or **Local Mode** for direct integration with Claude Desktop.
  </Card>
</CardGroup>

***

## Getting Started

### Prerequisites

* **Node.js 18+** installed on your machine
* A **Junis account** (sign up at [junis.ai](https://junis.ai))

### Quick Start

<Steps>
  <Step title="Run the CLI">
    Open your terminal and run:

    ```bash theme={null}
    npx junis
    ```
  </Step>

  <Step title="Authenticate">
    A browser window opens automatically. If you're already logged in to Junis, simply click **"Approve"** to authorize the device.
  </Step>

  <Step title="You're Connected">
    The CLI confirms the connection. Your device is now accessible to your Junis agents.

    ```
    Connected: My MacBook Pro
    WebSocket relay active
    Listening for agent commands...
    ```
  </Step>
</Steps>

***

## Available Tools

Once connected, your AI agents gain access to powerful device tools:

### File & Shell Tools

| Tool                              | Description                            |
| --------------------------------- | -------------------------------------- |
| `execute_command`                 | Run terminal commands on the device    |
| `read_file`                       | Read files (supports multiple formats) |
| `write_file`                      | Create or overwrite files              |
| `list_directory`                  | Browse directory contents              |
| `search_code`                     | Search through codebases               |
| `list_processes` / `kill_process` | Process management                     |

### Browser Automation Tools

| Tool                 | Description                       |
| -------------------- | --------------------------------- |
| `browser_navigate`   | Navigate to any URL               |
| `browser_click`      | Click elements on web pages       |
| `browser_type`       | Type text into form fields        |
| `browser_screenshot` | Capture screenshots               |
| `browser_snapshot`   | Get page accessibility tree       |
| `browser_evaluate`   | Execute JavaScript in the browser |

***

## Operating Modes

<Tabs>
  <Tab title="Cloud Mode (Default)">
    ### Cloud Relay Mode

    ```bash theme={null}
    npx junis
    ```

    Your device connects to the Junis cloud via WebSocket. AI agents on the Junis platform can send commands to your device remotely.

    **Best for**: Remote AI agent workflows, team collaboration, automated pipelines

    **Features**:

    * Persistent connection with auto-reconnect
    * 30-second heartbeat for reliability
    * Exponential backoff on disconnection
    * Device appears in your Junis dashboard
  </Tab>

  <Tab title="Local Mode">
    ### Local-Only Mode

    <Warning>
      **Coming Soon**: Local Mode is currently in development. Cloud Mode is fully available today.
    </Warning>

    ```bash theme={null}
    npx junis --local
    ```

    Runs a local MCP server without cloud connectivity. Perfect for direct integration with Claude Desktop or other local MCP clients.

    **Best for**: Privacy-focused use, offline work, direct Claude Desktop integration

    **Features**:

    * No cloud connection required
    * No Junis account needed
    * Local MCP server on your machine
    * Full tool access without relay
  </Tab>
</Tabs>

***

## CLI Commands

| Command                 | Description                   |
| ----------------------- | ----------------------------- |
| `npx junis`             | Start in cloud mode (default) |
| `npx junis --local`     | Start in local-only mode      |
| `npx junis --port 3000` | Specify a custom port         |
| `npx junis --reset`     | Reset authentication          |
| `npx junis status`      | Check connection status       |
| `npx junis logout`      | Log out and clear credentials |
| `npx junis --help`      | Display help                  |

***

## Linking Devices to Agents

After your device is connected, link it to specific agents:

<Steps>
  <Step title="Open Agent Settings">
    Go to **Admin > Agents** and edit the agent you want to give device access.
  </Step>

  <Step title="Link Device">
    In the **Devices** section, select your connected device from the list.
  </Step>

  <Step title="Test">
    Chat with the agent and ask it to perform a device action, like listing files in your home directory.
  </Step>
</Steps>

<Note>
  You can also link devices programmatically via [Junis Magic](/guides/junis-magic) MCP tools: `list_devices` and `link_agent_device`.
</Note>

***

## Cross-Platform Support

| Platform    | Status          |
| ----------- | --------------- |
| **macOS**   | Fully supported |
| **Windows** | Fully supported |
| **Linux**   | Fully supported |

***

## Security

<AccordionGroup>
  <Accordion title="Authentication" icon="lock">
    * **OAuth Device Flow**: Industry-standard authentication
    * Tokens stored locally in `~/.junis/config.json`
    * Tokens can be revoked anytime via `npx junis logout`
  </Accordion>

  <Accordion title="Connection Security" icon="shield-check">
    * **Outbound-only connection**: Your device connects out — no incoming ports needed
    * **Encrypted WebSocket**: All communication is encrypted via WSS
    * **Per-request authorization**: Each agent command is verified against your permissions
  </Accordion>

  <Accordion title="Device Permissions" icon="user-shield">
    * Only agents explicitly linked to your device can send commands
    * You control which agents have access via the dashboard
    * Disconnect anytime by stopping the CLI
  </Accordion>
</AccordionGroup>

***

## Use Cases

### Development Automation

```
You: "Run the test suite and fix any failing tests."

Agent (via your device):
1. Executes `npm test` on your machine
2. Reads test output and identifies failures
3. Opens and reads relevant source files
4. Applies fixes and reruns tests
```

### Browser-Based Research

```
You: "Go to competitor.com, take screenshots of their pricing page,
and compile a comparison report."

Agent (via your device):
1. Opens browser and navigates to the URL
2. Captures screenshots
3. Extracts pricing information
4. Generates a comparison document
```

### File Organization

```
You: "Organize the downloads folder — sort files by type into subfolders."

Agent (via your device):
1. Lists all files in ~/Downloads
2. Categorizes by file type
3. Creates organized subdirectories
4. Moves files into appropriate folders
```

***

## Related Guides

<CardGroup cols={2}>
  <Card title="Junis Magic" icon="wand-magic-sparkles" href="/guides/junis-magic">
    Manage devices via MCP tools
  </Card>

  <Card title="Agent System" icon="robot" href="/getting-started/agent-system">
    Learn about agent types
  </Card>

  <Card title="MCP Integration" icon="plug" href="/guides/mcp/overview">
    Connect external services
  </Card>

  <Card title="Tools Overview" icon="wrench" href="/guides/tools/overview">
    All available tools
  </Card>
</CardGroup>

***

<Note>
  **Need Help?** Contact us at [contact@junis.ai](mailto:contact@junis.ai) for assistance with device setup and configuration.
</Note>