SuperAgent is a super app for building and running personal agents. You can create custom agents, let them develop the skills they need to do task for you, and have them run automatocally in the background for you.
Features:
- Containerized Agents - SuperAgents spins up a containerized sandbox per agent - keeping your computer secure.
- Connected Accounts - easily connect 100s of accounts your agent can use.
- Secure Integrations - API calls are proxied outside your agent and the agent never sees Auth Tokens, keeping your account secure and giving you an audit trail of agent actions.
- Recurring and Scheduled Tasks - agents can schedule recurring tasks and future work so they can serve you autonomously in the background.
- Browser Access - agents can spin up and use a web browser to accomplish tasks where no API / MCP is available.
- Agent Dashboards & Artifacts - agents can create dashboard for you to more easily access information.
- Create Shared Skillsets - as agents create skills for your work - creaate skillsets to share them with your team!
Run as:
- Web App - you can run super agent in server mode and access it via the web. Great if you have a computer that can run it 24/7
- Desktop App - you can download and run superagent locally in your machine as a desktop app.
Pre-Reqs
To get strated with Superagent, you need:
- A container runtime -> this is where SuperAgent will run it’s agent containers. Our recommendations:
- Docker Desktop
- OrbStack
- Podman
- An Anthropic API Key -> we currently only support Anthropic models, more coming soon. Get your API key from the Anthropic Console.
- [Optional] A Composio API key -> SuperAgent uses Composio to generate OAuth Tokens for you for different acocunts. You can get one on Composio.
Getting Started
Desktop App
Download the latest release from the links above, or visit the releases page.
Running with Docker
You can run Superagent in a Docker container using Docker-outside-of-Docker (DooD) to spawn agent containers.
Using the published image
# Set your API key
export ANTHROPIC_API_KEY=your-api-key-here
# Pull and run
docker compose up
# Access at http://localhost:47891
Building locally
# Build and run from source
docker compose up --build
How it works
The Docker setup:
- Mounts the Docker socket for spawning sibling agent containers
- Persists data in
~/.superagent (same path on host and container)
- Mounts
./agent-container for building agent images on-demand
The image is published to ghcr.io/iddogino/superagent on every push to main and on version tags.
Running from Source
-
Install dependencies:
npm install
-
Build the agent container:
npm run build:container
-
Set up environment variables (see below)
-
Create the local data directory:
mkdir -p ~/.superagent
-
Run database migrations:
npm run db:migrate
-
Start the development server:
npm run dev
Environment Variables
| Variable | Description | Default |
|---|
ANTHROPIC_API_KEY | Your Anthropic API key (required) | - |
SUMMARIZER_MODEL | Model used for generating session names | claude-haiku-4-5 |
CONTAINER_STATUS_SYNC_INTERVAL_SECONDS | How often to sync container status with Docker (seconds) | 300 |
RUNNER_AVAILABILITY_CACHE_TTL_SECONDS | How long to cache Docker/Podman availability checks (seconds) | 60 |
Auth Mode (Multi-User)
Superagent can run in auth mode for multi-user deployments with role-based access control. When enabled, users sign up and sign in with email/password, and agents are isolated per user via ACLs.
How it works
- The first user to sign up is automatically promoted to admin.
- Subsequent users sign up as regular users.
- On a Platform-managed deployment, members join through Platform instead, and each member's first sign-in gives them their Platform role (owners and admins become admin, members become user) rather than promoting whoever arrives first. It is set at that sign-in only, so a role changed later in Settings > Users stays.
- Admins can manage users and access global settings (LLM keys, runtime config).
- Each agent has an owner (the creator) who can invite other users as user (can chat) or viewer (read-only).
- Auth mode is web-only — the Electron desktop app always runs in single-user mode.
Enabling auth mode
AUTH_MODE is a compile-time setting for the frontend (Vite injects it as __AUTH_MODE__), so it must be set at build time.
Using the published Docker image:
Pre-built auth images are published with the -auth suffix:
SUPERAGENT_IMAGE=ghcr.io/skillfulagents/superagent:main-auth \
ANTHROPIC_API_KEY=your-api-key \
docker compose up
From source:
AUTH_MODE=true npm run dev
Building Docker locally:
AUTH_MODE=true docker compose up --build
Docker image tags
Both regular and auth-enabled images are published on every push to main and on version tags:
| Tag | Description |
|---|
main | Latest from main branch (single-user) |
main-auth | Latest from main branch (multi-user auth) |
X.Y.Z | Version release (single-user) |
X.Y.Z-auth | Version release (multi-user auth) |
X.Y | Major.minor release (single-user) |
X.Y-auth | Major.minor release (multi-user auth) |
Auth environment variables
| Variable | Description | Default |
|---|
BETTER_AUTH_SECRET | Secret key for signing session cookies (min 32 chars). If not set, a secret is auto-generated and persisted to $SUPERAGENT_DATA_DIR/.auth-secret. | Auto-generated |
TRUSTED_ORIGINS | Comma-separated list of allowed origins for CORS and CSRF protection. The first origin is also used as the app's base URL for OAuth callbacks. Example: https://superagent.example.com | None (permissive CORS) |
HOST | Server hostname, used to construct the auth base URL when TRUSTED_ORIGINS is not set. | localhost |
PORT | Server port, used to construct the auth base URL when TRUSTED_ORIGINS is not set. | 47891 |
USE_HTTPS | Use https protocol in the auth base URL when TRUSTED_ORIGINS is not set. | false |
HOST_PUBLIC_URL | The public https address of the app, for links and pages handed to outside services (OAuth callbacks, the meeting bot's camera page). Features that need the internet to reach the app, such as meetings, are offered only when this is set to a non-private https URL. | First TRUSTED_ORIGINS entry (links only) |
RECALL_API_KEY / RECALL_REGION | Self-hosted alternative to the platform proxy for meeting bots: a Recall.ai key and its region (us-west-2 default). Not needed when the platform is connected. | None |
Example: production deployment
SUPERAGENT_IMAGE=ghcr.io/iddogino/superagent:main-auth \
ANTHROPIC_API_KEY=your-api-key \
TRUSTED_ORIGINS=https://superagent.example.com \
BETTER_AUTH_SECRET=your-secret-key-at-least-32-characters-long \
docker compose up
The runtime variables (TRUSTED_ORIGINS, BETTER_AUTH_SECRET, etc.) are passed through automatically by the compose file.
Optional: Composio OAuth setup
If you connect accounts through Composio (Slack/Gmail/GitHub, etc.), make sure token masking is disabled in your Composio project settings, otherwise SuperAgent cannot read usable access tokens and proxy calls may fail.
In the Composio dashboard, go to:
Project SettingsProject Configuration- Disable
Mask Connected Account Secrets
After changing this setting, reconnect the account in SuperAgent.
Create a .env.local file in the project root:
ANTHROPIC_API_KEY=your-api-key-here
# Optional overrides
# SUMMARIZER_MODEL=claude-haiku-4-5
# CONTAINER_STATUS_SYNC_INTERVAL_SECONDS=300
# RUNNER_AVAILABILITY_CACHE_TTL_SECONDS=60
[[Finish this section -- get to a running server]]
Development
Scripts
Development
| Script | Description |
|---|
npm run dev | Start web app + API server in parallel |
npm run dev:api | Start API server only (port 3001) |
npm run dev:web | Start Vite dev server only (port 3000) |
npm run dev:electron | Start Electron app in development |
Build
| Script | Description |
|---|
npm run build | Build web app + API for production |
npm run build:web | Build web frontend only |
npm run build:api | Build API server only |
npm run build:electron | Build Electron app |
npm run build:container | Build the agent Docker container |
Distribution
| Script | Description |
|---|
npm run dist:mac | Package Electron app for macOS. Building the built-in runtime's VM image needs Docker running (scripts/build-lima-image.sh); without it the app ships Alpine's stock image, whose first boot downloads sudo and reboots once |
npm run dist:win | Package Electron app for Windows |
npm run preview | Build and run production server locally |
Quality
| Script | Description |
|---|
npm run typecheck | Run TypeScript type checking |
npm run lint | Run ESLint |
npm test | Run tests in watch mode |
npm run test:run | Run tests once |
npm run test:coverage | Run tests with coverage |
Database
| Script | Description |
|---|
npm run db:migrate | Run database migrations |
npm run db:generate | Generate new migration |
npm run db:studio | Open Drizzle Studio |
npm run db:reset | Reset database |
On-demand PR desktop builds
To build signed macOS and Windows installers for a PR, open Actions → PR Build →
Run workflow, leave the workflow branch as main, and enter the PR number.
You can also trigger it from this checkout with GitHub CLI:
gh workflow run pr-build.yml --ref main -f pr_number=1477
Replace 1477 with the PR to build. The workflow resolves its current head commit
once and uses it for both platforms. It posts the commit and artifact download
links in a PR comment; artifacts are retained for 14 days. Signed builds require
a PR branch in this repository, because they use repository signing secrets.
For the Mac App Store package as well, tick Also build the Mac App Store
package (or add -f mas=true). App Store Connect validates it, and it is
never uploaded. It needs the Store's signing secrets (see
.github/workflows/build-mas.yml); without them the comment says it was skipped.
The manual trigger becomes available once this workflow change is merged into
main. PR pushes run tests without automatically packaging desktop apps; builds
on main pushes and version-tag releases still run automatically. The Mac App
Store package is built only by releases, and on demand for a PR. A release
uploads it to App Store Connect and adds it to the TestFlight groups: Team at
once, and Beta after Beta App Review. Every release of a version shares one
TestFlight version (0.6.0-rc.1, rc.2 and 0.6.0 are all 0.6.0), so only its
first build needs a full review. A full release also leaves the macOS App Store
version ready to submit: the version being prepared takes its number and build,
or a new version is made, with the last one's listing, once the last is out.
Submitting it for review is a click in App Store Connect.
Architecture
The application uses a dual-target architecture supporting both web and Electron desktop deployment:
Web Mode
- Frontend: Vite dev server (port 3000) proxies API requests to the backend
- Backend: Hono server (port 3001) handles API routes and serves static files in production
Electron Mode
- Main Process: Starts embedded Hono API server and creates browser window
- Renderer Process: Same React app as web, communicates with API via localhost
- Preload Script: Exposes safe IPC methods to renderer
The desktop app can also drive a remote auth-mode deployment ("cloud
workspace") instead of its own embedded API. Because the same React app runs in
three configurations — Electron on the local API, Electron on a cloud workspace,
and a plain browser — a feature is gated by what it touches, not by what the
window is:
| The feature acts on… | Predicate |
|---|
| this computer, on the agents' behalf | canUseHostFeatures() |
| the machine running the API | !targetIsRemote() |
| the window itself (traffic lights, tray, updates) | isElectron() |
!targetIsRemote() is true in browsers and isElectron() is not, so these are
not one scale of strictness — choosing the wrong one silently withdraws a
feature from every web deployment. See
docs/cloud-workspace.md § Capability gating
for the truth table and the full inventory of gated sites.
Agent Containers
Each agent runs in its own Docker/Podman container with Claude Code in headless mode:
- Containers communicate via HTTP/WebSocket APIs
- SSE streaming for real-time message updates
- File-based persistence for agents, sessions, and messages
- SQLite database for OAuth connected accounts
