Skip to content

CharlesSS07/CabraCommando

BranchesTags

Repository files navigation

Cabra Commando

Your friendly, everyday, safety-first, open-source AI agent.

Cabra Commando is an agentic platform that runs entirely in containers. Clone it, point it at any LLM, and let it work for you -- on a schedule, via email, or through the admin console. The agent lives in a hardened environment: it can do anything inside its container world, but nothing touches your host OS.

What It Does

  • Runs in a sandbox. The agent dispatches tool execution to a locked-down, disposable Docker container (cap_drop=ALL, no direct internet). It can modify its own data, prompts, knowledge, and tools -- but it cannot modify its own loop. If the sandbox breaks, the agent is unaffected and the sandbox can be rebuilt.
  • Works with any LLM. Point it at vLLM, Ollama, or any OpenAI-compatible endpoint. LiteLLM handles the abstraction.
  • Follows a calendar. Schedule tasks in plain English on a visual calendar. The agent picks them up, works within the time window, and moves on. Recurring events supported via RFC 5545 RRULE.
  • Controls a real browser. The browser agent (browser-use + Gemini VLM + Brave) navigates sites, fills forms, handles JavaScript-heavy pages, and deals with logins. Watch it live via noVNC at :6080.
  • Talks to you via email. Send an email to your agent's inbox (via AgentMail) to assign tasks or ask questions. The agent replies via send_message. Other transports (Discord, SMS, WhatsApp) are designed in but not yet wired.
  • Has a web console. The admin dashboard includes a built-in chat console so you can talk to the agent directly without configuring anything extra.
  • Builds its own tools. The agent writes scripts and utilities into its home directory (~/Applications) and can reuse them in future tasks. Its entire home directory is persistent across sessions.
  • Remembers what you tell it. A knowledge base stores facts about you and your preferences. Edit it any time from the admin dashboard. The agent also maintains its own semantic memory: any .md or .txt file it writes anywhere under its home directory is automatically indexed and searchable by meaning via the recalling tool -- so it can find past work, notes, and context by concept rather than filename.
  • Your data stays yours. Everything lives in a local PostgreSQL database. No cloud sync, no external dependencies.

Architecture

 ┌──────────────────┐       ┌──────────────────────────┐       ┌──────────────────────┐
 │  Browser (:6080) │       │         Cabra             │       │   Sandbox Container  │
 │                  │       │        (:8888)            │       │   (disposable)       │
 │  Brave browser   │browser│                           │       │                      │
 │  browser-use     │ REST  │  FastAPI + agent loop     │docker │  Python, R, Node,    │
 │  Gemini VLM      │◄──────│  Calendar + scheduler     │ exec  │  Perl, micromamba,   │
 │  noVNC viewer    │       │  Gateway (email/AgentMail)│──────►│  tmux, git, etc.     │
 └──────────────────┘       │  Contacts                 │       │  own PostgreSQL db   │
                            │  Admin Dashboard (static) │       └──────────────────────┘
                            │                           │
 Email ◄───────────────────►│  (AgentMail polling)      │       ┌──────────────────────┐
                            │                           │       │   PostgreSQL (:5432)  │
 Browser (:8888) ──────────►│  Console, Calendar, Files │──────►│   cabra db           │
                            │  Prompts, Knowledge,      │       │   sandbox db         │
                            │  Tools, Settings,         │       │   (pgvector)         │
                            │  Contacts                 │       └──────────────────────┘
                            └──────────────────────────┘

Four containers via docker-compose:

  • postgres -- standalone pgvector/pgvector:pg16 instance. Three databases: cabra (internal), sandbox (agent's own), and shared by all services. Not embedded in cabra.
  • cabra -- the orchestrator, agent brain, and admin interface. The entire agent (loop, state, identity) lives here. Hosts the FastAPI API, calendar scheduler, email gateway, contacts management, and the SvelteKit admin dashboard. Communicates with the browser container via REST and injects commands into sandbox via docker exec. If the sandbox breaks, the agent is unaffected.
  • sandbox -- the agent's world. A disposable execution environment where the agent runs code, fetches data, and builds tools. Runs no server; cabra injects commands via docker exec. No direct internet (all traffic intended to proxy through cabra). Can be reset or rebuilt without losing agent state.
  • browser -- a real Brave browser controlled by browser-use with Gemini as the VLM. Accepts natural-language goals from cabra, handles navigation/clicking/typing, and returns results. The user can watch and interact via noVNC at :6080.

Stack

Component Technology
Agent runtime Python 3.12, LiteLLM
Orchestrator FastAPI, SQLAlchemy, Alembic
Database PostgreSQL 16 + pgvector (standalone container, 2 databases: cabra, sandbox)
Sandbox tooling Python, R, Node.js, Perl, micromamba, tmux -- every language ships with a PostgreSQL connector
Browser agent browser-use, Brave, Gemini VLM, noVNC (separate container)
Email gateway AgentMail (polling inbox), extensible to Discord/SMS/WhatsApp
Contacts Multi-channel contact book (email, discord, sms, whatsapp)
Admin dashboard SvelteKit + shadcn-svelte, FullCalendar (static build inside cabra)

Getting Started

Prerequisites

  • Docker and Docker Compose
  • An API key for the main agent's LLM (LLM_API_KEY)
  • A Google API key for the browser agent (GOOGLE_API_KEY) -- the browser agent currently uses Gemini as its VLM; if you're already using Gemini for the main agent, this is the same key value in two variables

Setup

git clone https://github.com/cabra-commando/CabraCommando.git
cd CabraCommando
./setup.sh

setup.sh will generate a .env with the required variables. Edit it with your keys:

# Main agent LLM
LLM_API_KEY=...
LLM_MODEL=...
LITELLM_MODEL=...

# Browser agent VLM (currently requires a Google API key)
GOOGLE_API_KEY=...
BROWSER_LLM_MODEL=...

# Email gateway (optional — get a free inbox at agentmail.to)
AGENTMAIL_API_KEY=...
[email protected]

Run

docker compose up -d

Then open:

  • http://localhost:8888 -- Admin dashboard (console, calendar, browser, knowledge, tools, settings)
  • http://localhost:6080 -- noVNC (watch the browser agent work in real time)

Development

docker compose up -d --build   # start all containers
docker compose logs -f cabra   # cabra logs
docker compose logs -f browser # browser agent logs

# Admin dashboard hot-reload (optional, separate terminal)
cd cabra/web && npm install && npm run dev

To run the convenience log script from CLAUDE.md:

./scripts/show_last_50_cabra_logs.sh

Project Structure

CabraCommando/
├── cabra/                  # Cabra container (agent loop + orchestrator + admin UI)
│   ├── Dockerfile
│   ├── src/                # Python orchestrator + agent loop
│   │   ├── agent/          # Agent loop, LLM client, tools, hooks, conversation logging
│   │   ├── calendar/       # Event scheduling, CRUD, RFC 5545 recurrence
│   │   ├── gateway/        # Messaging gateway (email/AgentMail; future: Discord, SMS)
│   │   ├── messaging/      # Conversation + message storage (hash-chain log)
│   │   ├── console/        # In-dashboard chat console API
│   │   ├── browser/        # Proxy/API for the browser container
│   │   ├── proxy.py        # mitmproxy addon (ready for sandbox network enforcement)
│   │   ├── db.py           # Async SQLAlchemy engine
│   │   ├── config.py       # pydantic-settings
│   │   └── main.py         # FastAPI app factory
│   ├── tools.d/            # Tool manifests (YAML): shell, web_fetch, send_message, browser_use, calendar
│   ├── web/                # SvelteKit admin dashboard (static build)
│   │   └── src/routes/     # dashboard, console, calendar, browser, files, prompts,
│   │                       # knowledge, tools, settings, contacts, health
│   └── alembic/            # Database migrations
├── sandbox/                # The agent's world (disposable execution, no server, no direct internet)
│   └── Dockerfile          # Python, R, Node, Perl, micromamba, tmux, git, etc.
├── browser/                # Browser agent container
│   ├── Dockerfile          # Brave + browser-use + noVNC + supervisord
│   └── src/                # FastAPI service + session manager + ghost cursor + config
├── postgres/               # PostgreSQL init scripts
│   └── init-db.sh          # Creates cabra + sandbox databases and roles
├── scripts/                # Dev helper scripts
├── docker-compose.yml      # Four services: postgres + cabra + sandbox + browser
├── setup.sh                # First-time .env generator
├── update.sh               # Pull + rebuild
└── .env.example

Key Concepts

Single User, Local-First

Each Cabra Commando instance belongs to one person. No users table, no multi-tenancy. PostgreSQL is the source of truth for everything. All data stays on your machine.

The Agent Lives in Cabra, Operates in the Sandbox

The entire agent -- loop, state, identity -- runs inside the cabra container. The sandbox is the agent's world: from the agent's perspective, it's the Linux box where it builds tools, runs code, fetches data, and does all its work. But the agent actually lives in cabra, and the sandbox is disposable:

  • If the sandbox breaks (corrupted filesystem, killed processes, bad installs), the agent is unaffected and cabra can rebuild the sandbox.
  • The agent can modify its own prompts, knowledge, tools, data, and sandbox environment -- but it cannot modify its own loop.
  • Cabra injects commands into the sandbox via docker exec -- the sandbox runs no server.

Calendar-Driven Scheduling

Tasks are calendar events with a start time, end time, and plain-English description. The agent treats each event's duration as its time budget. Recurring events (daily standup, weekly reports) are supported via RFC 5545 RRULE. Missed events are handled gracefully at agent startup.

Browser Agent

The browser container runs a real Brave browser controlled by browser-use + Gemini VLM. Cabra dispatches browser_use tool calls to it via REST. The browser handles navigation, clicking, typing, JavaScript-heavy pages, and can deal with CAPTCHAs or 2FA by prompting the user to intervene (visible via noVNC at :6080).

Communications Gateway

The gateway polls for inbound messages (currently email via AgentMail) and injects them into the agent's conversation as user turns. Contacts are stored with multi-channel addresses (email, Discord, SMS, etc.) under user-chosen nicknames. The agent replies by calling send_message(to="email/dad", content="...").

Tool System

Tools are defined by YAML manifests in cabra/tools.d/. Built-in tools:

  • shell -- execute commands in the sandbox via docker exec
  • web_fetch -- fetch a URL from within the sandbox (via the network proxy)
  • browser_use -- control the real Brave browser for complex web tasks
  • send_message -- send a reply via any registered channel (email, Discord, etc.)
  • calendar -- create, read, update, delete calendar events

The agent can also build tools in ~/Applications (on its PATH) and invoke them via the shell tool across sessions.

Admin Dashboard Pages

Page What it does
Dashboard Agent status, current task, recent activity
Console Chat with the agent directly in the browser
Calendar Visual schedule -- drag to create events, click to edit
Browser Live view + control of the browser agent session
Files Browse and manage /data
Prompts Edit system prompt, persona, task templates
Knowledge Manage what the agent knows about you
Tools Enable/disable tools, view their configs
Settings Model selection, gateway credentials, preferences
Contacts Manage contacts and their channel addresses
Health Container and service health status

Security

  • Sandbox container runs with cap_drop=ALL and no direct internet access
  • The sandbox runs no server -- cabra injects commands via docker exec
  • The entire agent lives in cabra, so if the sandbox breaks the agent is unaffected
  • Tool execution via docker exec with timeout enforcement
  • Database isolation: sandbox can only access its own database; cabra role has full access
  • proxy.py (mitmproxy addon) is implemented and ready -- sandbox network enforcement is the next security milestone
  • All data lives locally in PostgreSQL -- no cloud sync
  • LLM keys are configured by the user in .env and stay on their machine

Roadmap

See PLAN.md for the full implementation plan and current phase status.

  • Phase 1: Foundation -- containers, agent loop, tools, basic chat via console
  • Phase 2: Calendar + Browser + Gateway -- scheduling, browser agent, email via AgentMail, contacts
  • Phase 3: Admin Dashboard -- console, calendar, browser viewer, files, prompts, knowledge, tools, settings, contacts
  • Phase 4: Sandbox network enforcement -- activate mitmproxy, internal: true on sandbox-net
  • Phase 5: Additional transports -- Discord, SMS, WhatsApp gateway adapters
  • Phase 6: Cabra Cloud -- zero-config option with managed API keys and traffic mixing
  • Phase 7: Polish -- CalDAV export, pgvector RAG, Google Drive, agent observability

Future: Cabra Cloud

Cabra Cloud will be an optional zero-config service. Users sign up, opt into the LLM providers they want (OpenAI, Anthropic, etc.), and receive forwarded API keys -- no need to create accounts with each provider individually. Traffic is mixed with other users for privacy. The website will follow the software; it does not exist yet.

Contributing

Cabra Commando is open source under the MIT License. Contributions are welcome.

  1. Fork the repo
  2. Create a feature branch (git checkout -b feature/my-feature)
  3. Commit your changes
  4. Push to the branch and open a PR

License

MIT

About

Your friendly, everyday, safety-first, open-source AI agent.

Resources

Readme
MIT license
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages