Self-host Understudy
v0.3.0Local AI agent that drives your desktop, browser and shell
- Stars
- 465
- Port
- 23333 (Gateway background process (HTTP + WebSocket) that chat, dashboard, webchat and channels connect through)
- Requires
- Xcode Command Line Tools
What is Understudy?
Understudy is an open-source, local-first AI agent you install on your own computer that carries out tasks across the whole desktop: it sees the screen and drives native apps, automates browsers, runs shell commands, searches the web, and replies over eight built-in messaging channels such as Telegram, Slack, Discord and Signal. Beyond following one-off instructions, you can teach it a workflow by demonstrating it once — it extracts intent rather than coordinates and publishes a reusable skill that survives UI redesigns — and repeated daily use can crystallize successful paths into skills automatically. Larger automations compose as workspace artifacts: playbooks sequence deterministic workers and agentic skills, for example a six-stage pipeline that browses the App Store, installs an app on a real iPhone and publishes a narrated review video. It is bring-your-own-model, with Anthropic, OpenAI, Google/Gemini and MiniMax among the supported providers, configured with API keys or OAuth. Self-hosting is through npm (GitHub Packages also works): install the package, run the setup wizard, and start the gateway daemon that terminal, dashboard, webchat and messaging surfaces connect to. Full native GUI automation requires macOS with Accessibility and Screen Recording permissions granted to your terminal app; Linux and Windows backends are planned. Layers 1–2 of its five-layer design are implemented, layers 3–4 partially, and proactive autonomy remains the long-term goal.
Should you self-host Understudy?
Understudy scores 48/100 on selfhost.directory (how scoring works) and ranks #110 of 209 in AI Agents. It has 465 GitHub stars.
There was no stable release in the past 12 months, so check the repository's recent activity before you rely on it.
Setup is moderate: expect some configuration beyond a single command. It is MIT-licensed and written mostly in Typescript.
Its closest alternative on selfhost.directory is Orca (91/100, 108 739 stars). It scores higher overall, so compare the two before you pick. See Understudy vs Orca side by side.
Features
- Automatic skill crystallizationLayer 3 partially implemented; promotion policy and automatic route upgrading still early
- Bring your own model
- Browser Automation
- GUI automation (computer use)macOS only today; Linux and Windows planned
- Learn by demonstration
- Multi-channel messaging
- Persistent memory
- Playbook orchestration
- Reusable skills
- Shell command execution
- Subagents
- Task Scheduling
- Web Dashboard
- Web search and fetch
Understudy README
More in Automation
uniflowUniflow is a self-hosted, fair-code workflow automation tool using flow-based programming and WebAssembly. Create flows that run on browser, Node.js, and VS Code.
unmonitarrSelf-hosted tool that manages Sonarr and Radarr monitoring based on air and release dates to prevent fake pre-release downloads.
unpackerrSelf-hosted daemon that extracts archives for Starr apps or watches folders, with web UI on port 5656.
UseAgentUseAgent is a self-hosted, open-source control plane for running multiple AI coding agents in isolated sandboxes with a shared event log.
ValmisSelf-hosted AI agent platform with secure credential proxying and 100+ integrations for team automation.
Vanchor-NGSelf-hosted GPS autopilot turning a trolling motor into a virtual anchor with routing and fishing modes — runs offline on Raspberry Pi or in simulation.
vitoOpen-source, self-hosted server management panel: provision VPS clouds, deploy PHP/Laravel or Node.js apps, and manage databases, SSL, firewall, cron and monitoring.
VolteVolte is a free, open-source Discord bot in C# with moderation, utility, and server management features. Self-host on Linux, Windows, or Docker.
WA-AKGWA-AKG is a self-hosted, open-source WhatsApp gateway with dashboard for managing sessions, scheduling messages, auto-replies, and REST API integration.
WAHASelf-hosted, open-source WhatsApp REST API: pair a number with a QR scan, then send and receive messages, groups, channels and status via webhooks.
WakupatorWakupator is a self-hosted Linux daemon that wakes up LAN machines via Wake-on-LAN when detecting traffic to spoofed IPs, reducing energy waste for home servers.
WarrenWarren runs coding agents as isolated workloads on your infrastructure, managing workspace, lifecycle, spend limits, live events, and Git delivery.
0 comments