webrenew 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
.blackboxignorefiles 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.mdfor full capability list - See
references/mcp-setup.mdfor MCP server configuration