Self-hosted AI agent orchestrator with a real browser, a cron scheduler, and a web dashboard.
launch.mp4 |
demo.mp4 |
Schedule AI agents to run on a cron, browse the web with a real Chromium browser you can watch live through VNC, and manage everything from a web dashboard or the CLI. Chat with the agent directly from the web UI, or connect Slack for conversational threads and slash commands. BrowserBird is the orchestration layer; the agent CLI (Claude Code) handles reasoning, memory, tools, and sub-agents.
Built by Owloops, building browser automation tools since 2020.
Set up an automation (scheduled task) and it runs on a cron, browses the web, and posts results to your Slack channel. The browser keeps logins and cookies across runs, so it works with sites that require authentication.
| Use Case | What the automation does |
|---|---|
| Competitor monitoring | Visits competitor pages on a schedule, screenshots pricing or feature changes, and flags differences in your channel. |
| News and mention digest | Browses Hacker News, Reddit, or Twitter for mentions of your product or keywords, and posts a morning summary. |
| Status page watchdog | Checks a status page every few minutes and alerts your incidents channel when something is degraded. |
| Dashboard screenshots | Logs into your analytics or billing dashboard, takes screenshots of key metrics, and posts them weekly. |
| Job and listing tracker | Browses job boards, real estate sites, or marketplaces for new listings matching your criteria. |
| Internal database analytics | Deployed in your private network with read-only database access, lets non-technical teams ask questions in Slack and get structured answers with tables and trends. |
These are starting points. Every automation has a full AI agent behind it that can browse the web, run shell commands, write and analyze code, call APIs, use MCP servers, and work with any CLI tool installed in the environment.
On first run, open the web UI and complete the onboarding wizard. It walks through agent config, API keys, and optional integrations (Slack, browser).
curl -fsSL https://raw.githubusercontent.com/Owloops/browserbird/main/compose.yml -o compose.yml
docker compose up -dEverything is included: agent CLI, Chromium browser, VNC, and Playwright MCP. Open http://<host>:18800 to begin onboarding.
The browser runs in persistent mode by default: logins and cookies are saved across sessions, one agent at a time. Set BROWSER_MODE=isolated in .env for parallel sessions with fresh contexts (requires container restart).
Two services are deployed: browserbird-app (web dashboard, API, Slack) and browserbird-vm (Chromium browser, VNC). Open the app service URL for the dashboard; the VM service has no web UI.
Important
Region: Deploy both services in the region closest to you. A distant region causes high VNC latency and makes interactive browser tasks nearly impossible. Both services must be in the same region.
Tip
Enable automatic deployments in Railway service settings so new versions apply without manual intervention. The app service volume at /app/.browserbird persists your database and config across redeployments.
Deploys both containers as a sidecar pair on ECS Fargate with an ALB and EFS for persistent storage. Select your VPC and subnets from the dropdown menus, deploy the stack, then open the dashboard URL to complete onboarding (API keys, Slack, agent config).
Optional integrations (fill in at stack creation time):
- HTTPS - provide an ACM certificate ARN to enable TLS on the ALB.
- Database access - provide an RDS security group ID and the template adds an ingress rule so BrowserBird can reach your database. Store database credentials in BrowserBird's vault keys after deployment.
After the stack is created, add a DNS record (CNAME or alias) pointing to the ALB DNS name from the stack outputs. This is required when using HTTPS so the domain matches your certificate.
Note
The stack requires the CAPABILITY_NAMED_IAM capability (it creates an ECS task execution role and task role). CloudFormation will prompt you to acknowledge this before creating the stack.
The manifest pre-configures all scopes, events, and slash commands. After creating the app, install it to your workspace and grab two tokens: the Bot User OAuth Token (xoxb-...) from OAuth & Permissions, and an app-level token (xapp-...) with connections:write scope from Basic Information.
Once the app is installed, /automation is available in any channel:
/automation list Show all configured automations
/automation run <name> [args] Trigger an automation (replaces $ARGUMENTS in the prompt)
/automation stop <name> Stop a running automation
/automation logs <name> Show recent runs
/automation enable <name> Enable an automation
/automation disable <name> Disable an automation
/automation create Create a new automation (opens modal form)
/automation status Show daemon status
To stop an active response in a thread, send stop as a message (or @BrowserBird stop in channels). The agent process is killed and a reaction is added to confirm.
Tip
If /automation fails or routes to the wrong app, you may have another Slack app in the workspace with the same slash command. Remove or rename the duplicate from api.slack.com/apps.
The onboarding wizard handles initial setup. For manual configuration, copy the example config:
cp browserbird.example.json browserbird.jsonSee browserbird.example.json for the full config with defaults.
Any string value can reference an environment variable with "env:VAR_NAME" syntax (e.g. "env:SLACK_BOT_TOKEN").
The top-level timezone field (IANA format, default "UTC") is used for cron scheduling and quiet hours.
slack - Slack connection and behavior
"slack": {
"botToken": "env:SLACK_BOT_TOKEN",
"appToken": "env:SLACK_APP_TOKEN",
"requireMention": true,
"coalesce": { "debounceMs": 3000, "bypassDms": true },
"channels": ["*"],
"quietHours": { "enabled": false, "start": "23:00", "end": "08:00", "timezone": "UTC" }
}botToken,appToken: Optional. Bot user OAuth token and app-level token for Socket Mode. Required only for Slack integrationrequireMention: Only respond in channels when@mentioned; DMs always respondcoalesce.debounceMs: Wait N ms after last message before dispatching (groups rapid messages)coalesce.bypassDms: Skip debouncing for DMschannels: Channel names or IDs to listen in, or"*"for allquietHours: Silence the bot during specified hours. Start/end in HH:MM format, can wrap midnight
agents - Agent routing and model config
"agents": [
{
"id": "default",
"name": "BrowserBird",
"model": "sonnet",
"fallbackModel": "haiku",
"maxBudgetUsd": 5,
"maxTurns": 50,
"systemPrompt": "You are responding in a Slack workspace. Be concise, helpful, and natural.",
"channels": ["*"]
}
]Each agent is scoped to specific channels. Multiple agents are matched in order, first match wins.
id,name: Required. Unique identifier and display namemodel: Short names (sonnet,haiku) or full model IDsfallbackModel: Fallback when primary model is unavailablemaxBudgetUsd: Cap API spend per invocation in USD (agent exits when reached)maxTurns: Max conversation turns per sessionsystemPrompt: Instructions prepended to every sessionchannels: Channel names or IDs this agent handles, or"*"for allprocessTimeoutMs: Per-agent subprocess timeout override (inherits fromsessionsif not set)
sessions - Session lifecycle
"sessions": {
"ttlHours": 72,
"maxConcurrent": 5,
"processTimeoutMs": 300000
}ttlHours: Hours of inactivity before a session expires. The timer resets on each message. When a session expires, the agent starts fresh with no memory of the previous conversation. Messages are still stored in BrowserBird's database, but the agent itself begins a new context. Default is 72 (3 days)maxConcurrent: Max simultaneous agent processesprocessTimeoutMs: Per-request timeout in milliseconds
browser - Playwright MCP and VNC
"browser": {
"enabled": false,
"mcpConfigPath": null,
"vncPort": 5900,
"novncPort": 6080,
"novncHost": "localhost"
}enabled: Enable Playwright MCP for the agentmcpConfigPath: Path to your MCP config (relative or absolute)vncPort: VNC server portnovncPort: Upstream noVNC WebSocket portnovncHost: Upstream noVNC host (e.g."vm"in Docker)
Browser mode (persistent or isolated) is controlled by the BROWSER_MODE environment variable, not the config file.
automations - Scheduled task settings
"automations": {
"maxAttempts": 3
}maxAttempts: Max job attempts before an automation stops retrying
Each automation supports per-automation active hours set via CLI --active-hours 09:00-17:00 or the API. Wrap-around windows (e.g. 22:00-06:00) are supported.
database - Retention policy
"database": {
"retentionDays": 30
}retentionDays: How long to keep messages, run logs, jobs, and logs
web - Dashboard and API server
"web": {
"enabled": true,
"host": "127.0.0.1",
"port": 18800,
"corsOrigin": ""
}enabled: Enable the web dashboard and APIhost: Bind address (0.0.0.0for Docker/remote)port: Web UI and REST API portcorsOrigin: Allowed origin for CORS headers (for cross-origin SPA hosting)
Authentication is handled via the web UI. On first visit, you create an account. All subsequent visits require login.
| Variable | Description |
|---|---|
SLACK_BOT_TOKEN |
Bot user OAuth token (optional, for Slack integration) |
SLACK_APP_TOKEN |
App-level token for Socket Mode (optional, for Slack integration) |
ANTHROPIC_API_KEY |
Anthropic API key (pay-per-token) |
CLAUDE_CODE_OAUTH_TOKEN |
OAuth token (uses your Claude Pro/Max subscription) |
BROWSER_MODE |
persistent (default) or isolated. Requires container restart |
BROWSERBIRD_CONFIG |
Path to browserbird.json. Overridden by --config flag |
BROWSERBIRD_DB |
Path to SQLite database file. Overridden by --db flag |
BROWSERBIRD_VAULT_KEY |
Vault encryption key (auto-generated on first start, stored in .env) |
BROWSERBIRD_VERBOSE |
Set to 1 to enable debug logging. Same as --verbose flag |
BROWSERBIRD_AUTOMATION_DATA |
Persistent data directory for the current automation. Set automatically per automation run |
BROWSERBIRD_TOKEN |
CLI auth token. Takes priority over saved credentials files |
BROWSERBIRD_CREDENTIALS |
Path to a credentials JSON file. Used when BROWSERBIRD_TOKEN is unset |
BROWSERBIRD_API_URL |
Daemon URL the CLI talks to (default http://127.0.0.1:18800). Overridden by --url flag |
NO_COLOR |
Disable colored output |
Note
Agent authentication: ANTHROPIC_API_KEY (pay-per-token) is required for shared or commercial deployments per Anthropic's Consumer ToS. CLAUDE_CODE_OAUTH_TOKEN is fine for personal self-hosted use. When both are set, OAuth takes priority. This is also why BrowserBird uses the CLI rather than the Agent SDK; the SDK requires API key auth per Anthropic's usage policy.
Store markdown documents in .browserbird/docs/ that get injected into the agent's system prompt at spawn time. Use them for tone guides, project context, channel-specific instructions, or any reusable prompt content.
- File-backed. Each skill is a
.mdfile you can edit with any text editor. Drop a file in the directory and it gets auto-discovered. - Scoped with bindings. Bind a skill to specific channels via the web UI or CLI. Use
*as the channel to apply everywhere. Unbound skills are not injected (same semantics as vault keys). - Managed from the web UI or CLI. Create, edit, and manage bindings from the Skills page, or use
browserbird skillsfrom the terminal.
Store API keys and secrets in the web UI (Resources, Keys tab) and bind them to specific channels. At spawn time, bound keys are injected as environment variables into the agent subprocess.
- Encrypted at rest with AES-256-GCM. The encryption key is auto-generated on first start and stored in
.envasBROWSERBIRD_VAULT_KEY. - Redacted from output. If the agent prints a vault key value, it appears as
[redacted]in Slack and logs. - Bound to channels. A key bound to channel
*applies to all channels; a key bound to a specific channel applies only there.
Example: GitHub integration. Store a GitHub personal access token as GITHUB_TOKEN in the vault and bind it to a channel (or * for all channels). The agent can then create issues, open PRs, push code, review changes, and manage repositories using the GitHub API or CLI.
Example: authenticated browsing. For automations that need to browse logged-in sites (X, LinkedIn, etc.), export cookies from your local browser using Cookie-Editor, store the JSON as a vault key (e.g. X_COOKIES), and bind it to the channel where the automation runs. In the automation's prompt, instruct it to read the cookies from the env var and inject them via addCookies before browsing. Pre-injecting cookies ensures the agent starts in a logged-in state, making scheduled tasks more reliable.
Available on npm: npx @owloops/browserbird
$ browserbird --help
.__.
( ^>
/ )\
<_/_/
" "
usage: browserbird [command] [options]
commands:
sessions manage sessions and chat
automations manage scheduled automations
skills manage skills (agent instructions)
keys manage vault keys
config view configuration
logs show recent log entries
jobs inspect and manage the job queue
backups manage database backups
doctor check system dependencies
login authenticate to the daemon
logout clear saved daemon credentials
whoami show the authenticated user
reset-password reset a password locally (run on the host)
options:
-h, --help show this help
-v, --version show version
--verbose enable debug logging
--config config file path (env: BROWSERBIRD_CONFIG)
--db database file path (env: BROWSERBIRD_DB)
run 'browserbird <command> --help' for command-specific options.
BrowserBird works without Slack. Authenticate once, create an automation, trigger it, and check results from the terminal:
browserbird login
browserbird automations add --name "hn-digest" --schedule "0 9 * * *" --prompt "Check Hacker News for AI news and summarize"
browserbird automations run <name>
browserbird automations runs <name>The CLI talks to the daemon over HTTP and authenticates with a JWT. browserbird login prompts for your dashboard email and password and saves the token to ~/.config/browserbird/credentials.json (use --system to write to <DATA_DIR>/.credentials.json instead, for container deployments). To skip the file entirely, set BROWSERBIRD_TOKEN. Point at a remote daemon with --url or BROWSERBIRD_API_URL. browserbird logout clears the saved token; browserbird whoami shows the current principal.
Locked out of the dashboard? Reset from the host where BrowserBird runs (ssh in, or docker exec / kubectl exec / ecs execute-command into the container):
browserbird reset-password # sole user, prints a new password
browserbird reset-password --email you@x.com # when more than one user existsIt is the only CLI command that writes to the database directly rather than through the daemon, so it works even when the daemon is down and is authorized by host access rather than a credential (there is no HTTP endpoint, by design). It prints a new generated password and signs out the user's existing sessions. Pass --db (or set BROWSERBIRD_DB) for a non-default database path.
Runs at http://localhost:18800 by default.
| Page | Description |
|---|---|
| Mission Control | System overview, failing automations, upcoming runs, active sessions |
| Projects | Channels with the agent, keys, skills, and automations bound to each |
| Resources | Tabbed: Agents, Skills (markdown instructions with channel bindings), Keys (vault secrets), and Automations (scheduled tasks with run history) |
| Sessions | Chat with the agent directly, view message history, token usage, and session detail |
| Settings | Tabbed: Config editor, Browser (live noVNC viewer, Docker only), Database (retention, system automations, job queue, log viewer), and Backups |
git clone https://github.com/Owloops/browserbird.git
cd browserbird
npm cicd web && npm ci && npm run build && cd ..
./bin/browserbirdcp .env.example .env
docker compose -f oci/compose.yml up -d --buildnpm run typecheck # tsc --noEmit
npm run lint # eslint
npm run format:check # prettier
npm test # node --testWeb UI (from web/):
npm run check # svelte-check
npm run format:check # prettierThe Launch Stack button in the README points to s3://browserbird-releases/cloudformation/latest.yaml. After making changes to aws/cloudformation.yaml, upload the new version:
aws s3 cp aws/cloudformation.yaml \
s3://browserbird-releases/cloudformation/latest.yaml \
--content-type "application/x-yaml" \
--region us-east-1Validate before uploading:
cfn-lint aws/cloudformation.yaml
aws cloudformation validate-template \
--template-body file://aws/cloudformation.yamlThe bucket (browserbird-releases, account 267013046707, us-east-1) has a public read policy scoped to the cloudformation/ prefix so CloudFormation can fetch the template during stack creation.
FSL-1.1-MIT, source available, converts to MIT after two years.
Note
This project was built with assistance from LLMs. Human review and guidance provided throughout.