DigitalOcean Gradient AI Hackathon submission.

Executive Butler is a hybrid agent:

• You chat from web/phone
• A cloud backend plans actions
• Your Mac receives action requests over WebSocket
• Every action requires local approval
• Screenshot artifacts upload to DigitalOcean Spaces and return as presigned links

This project uses DigitalOcean full-stack AI components in one flow:

• Gradient-compatible inference endpoint for natural language planning
• DigitalOcean Spaces for cloud artifact storage
• App Platform-ready backend (FastAPI)
• Agentic architecture with human-in-the-loop approval

It targets judging criteria directly:

• Technological Implementation: cloud + local bridge, safety gate, artifact pipeline
• Design: mobile-first chat UI with recommendations and visual artifacts
• Potential Impact: secure remote control of personal workstation from anywhere
• Quality of Idea: “Executive Butler” persona for high-trust productivity automation

• Natural language chat planning (LLM + heuristic fallback)
• Mandatory macOS approval prompt before execution
• Action execution on local machine (list, read, open, screenshot, run, etc.)
• Screenshot upload to DigitalOcean Spaces
• 1-hour presigned screenshot URL returned to chat
• Executive Butler brief (active app / visible apps / front window context)
• Tunnel support for phone testing

1. Phone/browser sends chat prompt to backend (/ws/chat).
2. Planner converts prompt to structured action.
3. Backend forwards action to local agent (/ws/agent/{device_id}).
4. Local agent shows approval popup.
5. On approve, action runs locally.
6. Screenshot actions upload image to Spaces and generate presigned URL.
7. Backend streams result to chat (including image URL/preview).

• backend/app/main.py: WebSocket bridge + API endpoints
• backend/app/planner.py: LLM + heuristic planner
• backend/app/action_parser.py: direct command parser
• backend/app/templates/index.html: mobile-first UI
• local_agent/client.py: local executor + approval + Spaces upload
• scripts/setup.sh: bootstrap dependencies
• scripts/start_backend.sh: run backend
• scripts/start_local_agent.sh: run local agent
• scripts/start_tunnel.sh: open public tunnel
• scripts/gradient_agent_init.sh: run gradient agent init
• scripts/gradient_agent_deploy.sh: run gradient agent deploy with env checks

cd /Users/edidiong/Desktop/hackerthon/gradient-hybrid-agent
./scripts/setup.sh
cp .env.example .env

Fill .env values (no secrets in repo; use .env.example template).

Run:

./scripts/start_backend.sh

./scripts/start_local_agent.sh

Open:

• http://127.0.0.1:8000

See .env.example for full list.

Key groups:

• Agent security:
  • BRIDGE_SHARED_SECRET
  • DEVICE_ID
• Planner/LLM:
  • PLANNER_MODE
  • LLM_API_BASE
  • LLM_API_KEY
  • LLM_MODEL
• Spaces upload:
  • DO_SPACES_ACCESS_KEY_ID
  • DO_SPACES_SECRET_ACCESS_KEY
  • DO_SPACES_ORIGIN_ENDPOINT
  • DO_SPACES_BUCKET
  • DO_SPACES_REGION

Start a tunnel:

./scripts/start_tunnel.sh 8000

Then open the public URL on phone and send prompts like:

• Executive Butler, give me my desktop briefing
• Take a screenshot and upload it to cloud
• What windows are currently open?

Use this when you want the planning "brain" hosted by DigitalOcean Gradient ADK.

1. Initialize ADK project metadata:

cd /Users/edidiong/Desktop/hackerthon/gradient-hybrid-agent
./scripts/gradient_agent_init.sh

This runs:

gradient agent init

and creates agents.yml.

2. Set required environment variables (in .env):

DIGITALOCEAN_API_TOKEN=...
GRADIENT_MODEL_ACCESS_KEY=...

3. Deploy:

cd /Users/edidiong/Desktop/hackerthon/gradient-hybrid-agent
./scripts/gradient_agent_deploy.sh

This runs:

gradient agent deploy

After ~1–5 minutes, you receive a deployment URL like:

https://agents.do-ai.run/v1/.../run

Use that hosted endpoint as your cloud planning brain, while your local agent remains the secure action executor on your Mac.

1. Push this repository to GitHub.
2. Create an App Platform app from this repo.
3. Configure build/run command:
   • Run: uvicorn backend.app.main:app --host 0.0.0.0 --port 8080
4. Add backend env vars in App Platform:
   • BRIDGE_SHARED_SECRET
   • PLANNER_MODE, LLM_*
   • DIGITALOCEAN_API_TOKEN, GRADIENT_MODEL_ACCESS_KEY (if using ADK-hosted brain flow)
   • AGENT_PERSONA*
5. Keep local agent running on your Mac with BACKEND_URL set to your deployed app URL.

• Every action requires local approval by default (APPROVAL_MODE=prompt).
• Local shell tool is restricted to readonly commands.
• Do not commit .env.
• Rotate keys before publishing demos.

1. Intro architecture (15s): phone -> cloud -> Mac approval.
2. Show live prompt from phone (45s): ask for status.
3. Show approval popup on Mac (20s).
4. Run screenshot flow (45s): capture -> Spaces upload -> image preview in chat.
5. Show Executive Butler summary (30s).
6. Explain DigitalOcean stack usage + impact (25s).

• Public GitHub repo URL
• Open source license file (included)
• Setup instructions (this README)
• 3-minute public demo video link
• Optional live demo URL
• Detailed project description (can reuse sections above)

MIT. See LICENSE.