Flezi AgentBox

CLI Local Setup

Install the agentbox CLI for one-click local deployment with automatic IDE integration

CLI Local Setup

The agentbox CLI provides a one-click experience for running Flezi AgentBox locally. It handles Docker orchestration, pre-flight checks, LLM key management, and automatic MCP IDE configuration — all from a single binary.

Installation

macOS / Linux

bash
curl -fsSL https://raw.githubusercontent.com/agentbox/cli/main/install.sh | bash

Windows

Download the latest release from the GitHub Releases page. Extract and add to your PATH.

Homebrew (macOS)

bash
brew install agentbox/tap/agentbox

The CLI binary is ~7 MB with zero runtime dependencies beyond Docker. It supports linux/darwin/windows on both amd64 and arm64.

Quick Start

bash
# 1. Check your environment
agentbox doctor
 
# 2. Initialize (interactive wizard)
agentbox init
 
# 3. Start services
agentbox start
 
# 4. Check status
agentbox status

That's it. The init command runs pre-flight checks, pulls Docker images, generates config, stores your LLM key securely, and auto-connects your IDE.

Pre-Flight Checks

Before setup, agentbox doctor validates your environment:

| Check | Requirement | |-------|-------------| | Docker Engine | v20.10+ installed and running | | Docker Compose | v2 plugin available | | Ports | 3000, 3001, 54321 available | | Disk Space | 2 GB+ free | | Socket | Docker socket accessible (Unix) |

bash
agentbox doctor
Flezi AgentBox Pre-Flight Checks
========================
  Docker Engine     v27.1.2    OK
  Docker Daemon     running    OK
  Docker Compose    v2.29.1    OK
  Port 3000         available  OK
  Port 3001         available  OK
  Port 54321        available  OK
  Disk Space        48 GB      OK
  Docker Socket     ok         OK

All checks passed.

The Init Wizard

The init command runs an interactive setup wizard:

bash
agentbox init

Select your project directory

The CLI auto-detects the git root. Press Enter to accept or type a different path.

Enter your LLM API key

Paste your API key from OpenAI, Anthropic, or Google. The provider is auto-detected from the key prefix:

| Prefix | Provider | |--------|----------| | sk-ant- | Anthropic | | sk- | OpenAI | | AIza | Google |

Your key is stored in the OS keychain (macOS Keychain, Linux libsecret, Windows Credential Manager) with AES-256-GCM encrypted file fallback.

Automatic setup

The CLI then:

  1. Generates docker-compose.yml from embedded templates
  2. Pulls orchestrator and frontend images from GHCR
  3. Starts all services (orchestrator, frontend, Supabase)
  4. Waits for health checks to pass
  5. Generates an API key for MCP authentication
  6. Auto-detects your IDE and injects MCP configuration

Non-Interactive Mode

For CI/CD or scripted setups:

bash
agentbox init --non-interactive --project /path/to/project --llm-key sk-ant-xxx

IDE Auto-Connect

After init, the CLI automatically configures MCP for detected IDEs:

| IDE | Config File | Action | |-----|------------|--------| | VS Code | .vscode/settings.json | Merges mcp.servers.agentbox | | Cursor | ~/.cursor/mcp.json | Merges mcpServers.agentbox | | Claude Code | .mcp.json | Merges mcpServers.agentbox |

The CLI never overwrites existing config — it merges the agentbox entry alongside your other MCP servers. A .bak backup is created before any modification.

If auto-detection fails, run agentbox init again or manually add the config shown in the MCP Integration Guide.

Commands Reference

| Command | Description | |---------|-------------| | agentbox init | Run setup wizard (preflight + config + start) | | agentbox start | Start all Docker services | | agentbox stop | Stop all Docker services | | agentbox status | Show service status and ports | | agentbox doctor | Run pre-flight environment checks | | agentbox logs | View orchestrator logs | | agentbox logs --follow | Stream orchestrator logs | | agentbox config get <key> | Read a config value | | agentbox config set <key> <value> | Write a config value | | agentbox version | Show CLI version | | agentbox version --json | Show version as JSON |

Service Ports

| Service | Default Port | Config Key | |---------|-------------|------------| | Frontend (Dashboard) | 3000 | ports.frontend | | Orchestrator (API/MCP) | 3001 | ports.orchestrator | | Supabase | 54321 | ports.supabase |

All services bind to 127.0.0.1 only — no LAN exposure.

Configuration

Config is stored at ~/.agentbox/config.yaml:

yaml
project_dir: /home/user/my-project
ports:
  orchestrator: 3001
  frontend: 3000
  supabase: 54321
images:
  orchestrator: ghcr.io/agentbox/orchestrator:latest
  frontend: ghcr.io/agentbox/frontend:latest

Override any value:

bash
agentbox config set ports.orchestrator 4001

Security

  • LLM keys: Stored in OS keychain with AES-256-GCM encrypted file fallback
  • API keys: SHA-256 hashed in the database, raw key shown once during init
  • Network: All services bind to 127.0.0.1 (localhost only)
  • Project files: Mounted read-only into containers (/app/project:ro)
  • Docker images: Signed with Sigstore cosign, verified on pull

Troubleshooting

| Issue | Fix | |-------|-----| | docker: command not found | Install Docker Desktop or Docker Engine | | Port already in use | Stop the conflicting service or change ports via agentbox config set | | Health check timeout | Run agentbox logs to check orchestrator output | | IDE not detected | Manually configure MCP — see MCP Integration | | Permission denied (socket) | Add your user to the docker group: sudo usermod -aG docker $USER |

Updating

bash
# Reinstall the CLI
curl -fsSL https://raw.githubusercontent.com/agentbox/cli/main/install.sh | bash
 
# Pull latest Docker images
agentbox stop && agentbox start

Next Steps