| name | blackbox-desktop |
| description | 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.
|
| compatibility | Requires Blackbox Desktop Agent installed. Available for macOS, Windows, and Linux.
|
| metadata | {"author":"tradecraft","version":"1.0.0"} |
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:
| 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
- Install and launch the application
- Sign in with your Blackbox AI account
- Choose your control mode
- 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:
- Go to cloud.blackbox.ai
- Open profile settings
- Find "MCP Token" section
- Click generate
Connect MCP Server:
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
