# Blackbox Desktop

> Guides usage of the Blackbox AI Desktop Agent, including desktop automation, MCP client connections, control modes (Full Autonomy, Approval Required, Chat Only), and .blackboxignore file exclusion. Activates when configuring or troubleshooting the Desktop Agent.

- Skill: `webrenew/blackbox-desktop` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add webrenew/blackbox-desktop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/webrenew/blackbox-desktop/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: webrenew (https://skillmd.com/u/webrenew)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/webrenew/blackbox-desktop

---


# Blackbox AI Desktop Agent

The Blackbox AI Desktop Agent is a standalone application for Windows, macOS, and Linux that provides AI-powered coding assistance with full autonomy controls, MCP client integration, and cross-application automation.

## When to Use This Skill

- Installing the Blackbox Desktop Agent on any OS
- Configuring control modes (Full Autonomy, Approval Required, Chat Only)
- Setting up MCP (Model Context Protocol) client connections
- Creating `.blackboxignore` files for file exclusion
- Managing token usage and session settings
- Understanding security and encryption features
- Running cross-application automation workflows

## Quick Start

### Install

Download from [app.blackbox.ai](https://app.blackbox.ai/):

| Platform | Requirement |
|----------|-------------|
| **macOS** (Apple Silicon) | macOS 10.15+, DMG installer |
| **macOS** (Intel) | macOS 10.15+, DMG installer |
| **Windows** | Windows 10/11 64-bit, EXE installer |
| **Linux** | Ubuntu/Fedora/Debian, .deb/.rpm/AppImage |

### Setup

1. Install and launch the application
2. Sign in with your Blackbox AI account
3. Choose your control mode
4. Start coding with AI assistance

## Core Concepts

### Control Modes

| Mode | Description | Best For |
|------|-------------|----------|
| **Full Autonomy** | Agent works independently without intervention | Trusted tasks, automation |
| **Approval Required** | Review and approve each action | Learning, sensitive code |
| **Chat Only** | Conversational assistance, no automated actions | Q&A, brainstorming |

Switch modes from the agent settings panel.

### MCP Client Setup

The Desktop Agent acts as an MCP (Model Context Protocol) client, connecting to external tools and services.

**Generate MCP Token:**
1. Go to [cloud.blackbox.ai](https://cloud.blackbox.ai)
2. Open profile settings
3. Find "MCP Token" section
4. Click generate

**Connect MCP Server:**
```bash
blackbox mcp add remote-code https://cloud.blackbox.ai/api/mcp \
  -t http \
  -H "Authorization: Bearer <your-mcp-token>"
```

**Verify:** Look for "using 1:MCP server" in terminal output.

**Discover tools:** Press `Ctrl+t` or ask `"print all the remote-code tools"`

See `references/mcp-setup.md` for detailed MCP configuration.

### File Exclusion

Create a `.blackboxignore` file in your project root:

```
# .blackboxignore
node_modules/
dist/
build/
.env
.env.local
*.log
*.lock
coverage/
.next/
__pycache__/
```

Same syntax as `.gitignore`. Excludes files from:
- Context indexing
- Token consumption
- AI analysis

### Security Features

| Feature | Description |
|---------|-------------|
| **End-to-End Encryption** | Industry-standard encryption for all communications |
| **Local Encryption** | Data encrypted on device before transmission |
| **File Protection** | `.blackboxignore` for sensitive file exclusion |
| **Access Control** | Full control over what the agent can access and modify |
| **Zero-Knowledge** | Server cannot access your sensitive work |

## Common Patterns

### Full Autonomy Workflow

```
1. Set mode to "Full Autonomy"
2. Describe the task: "Refactor all API routes to use Zod validation"
3. Agent works through all files autonomously
4. Review changes in git diff when complete
```

### Approval-Based Development

```
1. Set mode to "Approval Required"
2. Ask: "Add error handling to the payment processing module"
3. Review each proposed change
4. Approve or reject individually
```

### MCP-Enhanced Workflow

```
1. Connect MCP servers for external tools
2. Agent can now access remote resources
3. "Use the database MCP to check the current schema, then add a migration"
```

## Troubleshooting

| Issue | Fix |
|-------|-----|
| Installation fails | Check OS requirements and permissions |
| MCP connection fails | Verify token and endpoint URL |
| High token usage | Add more entries to `.blackboxignore` |
| Agent unresponsive | Restart the application |
| Files not excluded | Check `.blackboxignore` syntax and location |

## References

- See `references/capabilities.md` for full capability list
- See `references/mcp-setup.md` for MCP server configuration