Skip to main content

​
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. 
npx junis
Zero Configuration: Run the command, click login, and your device is connected. AI agents can immediately start working on your machine.

​
Why Use Junis Desktop Agent?

Complete Device Control

AI agents can read/write files, execute commands, automate browsers, and interact with your OS — all through your Junis agents.

One-Line Setup

No complex configuration. Run npx junis, authenticate once, and you’re connected.

Secure Connection

OAuth-based authentication with encrypted WebSocket relay. Your device connects outbound — no open ports required.

Two Operating Modes

Use Cloud Mode for remote AI access or Local Mode for direct integration with Claude Desktop.

​
Getting Started

​
Prerequisites

  • Node.js 18+ installed on your machine
  • A Junis account (sign up at junis.ai)

​
Quick Start

1

Run the CLI

Open your terminal and run:
npx junis
2

Authenticate

A browser window opens automatically. If you’re already logged in to Junis, simply click “Approve” to authorize the device.
3

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...

​
Available Tools

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

​
File & Shell Tools

ToolDescription
execute_commandRun terminal commands on the device
read_fileRead files (supports multiple formats)
write_fileCreate or overwrite files
list_directoryBrowse directory contents
search_codeSearch through codebases
list_processes / kill_processProcess management

​
Browser Automation Tools

ToolDescription
browser_navigateNavigate to any URL
browser_clickClick elements on web pages
browser_typeType text into form fields
browser_screenshotCapture screenshots
browser_snapshotGet page accessibility tree
browser_evaluateExecute JavaScript in the browser

​
Operating Modes

​
Cloud Relay Mode

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 pipelinesFeatures:
  • Persistent connection with auto-reconnect
  • 30-second heartbeat for reliability
  • Exponential backoff on disconnection
  • Device appears in your Junis dashboard

​
CLI Commands

CommandDescription
npx junisStart in cloud mode (default)
npx junis --localStart in local-only mode
npx junis --port 3000Specify a custom port
npx junis --resetReset authentication
npx junis statusCheck connection status
npx junis logoutLog out and clear credentials
npx junis --helpDisplay help

​
Linking Devices to Agents

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

Open Agent Settings

Go to Admin > Agents and edit the agent you want to give device access.
2

Link Device

In the Devices section, select your connected device from the list.
3

Test

Chat with the agent and ask it to perform a device action, like listing files in your home directory.
You can also link devices programmatically via Junis Magic MCP tools: list_devices and link_agent_device.

​
Cross-Platform Support

PlatformStatus
macOSFully supported
WindowsFully supported
LinuxFully supported

​
Security

  • OAuth Device Flow: Industry-standard authentication
  • Tokens stored locally in ~/.junis/config.json
  • Tokens can be revoked anytime via npx junis logout
  • 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
  • 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

​
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

Junis Magic

Manage devices via MCP tools

Agent System

Learn about agent types

MCP Integration

Connect external services

Tools Overview

All available tools
Need Help? Contact us at contact@junis.ai for assistance with device setup and configuration.