The operating system for autonomous AI agents. Scheduling, messaging, agent discovery, and a browser-based command center. One person can ship like a team.

Install

npm install -g dorkos

Quick Start

export ANTHROPIC_API_KEY=your-key-here
dorkos

Your browser opens. You're looking at every Claude Code session across all your projects: sessions you started from the CLI, from VS Code, from anywhere. One place. Every session. Already there.

What DorkOS Does

It's 7am. CI has been red since 2:47am. A dependency update cascaded across three repos. Your agent could have caught this overnight, fixed it, and sent you a Telegram message. Instead, the terminal was closed. The agent wasn't running.

DorkOS gives your agents what they're missing: scheduling, communication, and coordination. The intelligence comes from the agents. Everything else comes from DorkOS.

Tasks - Scheduling

Cron-based and on-demand agent execution, independent of your IDE or terminal. Your agents ship code, triage issues, and run audits on schedule. You wake up to completed pull requests.

• File-based task definitions alongside your code
• Overrun protection prevents duplicate runs
• Isolated sessions per run with full history
• Configurable concurrency limits

Relay - Communication

Built-in messaging between your agents and the channels you already use. Telegram, webhooks, browser. Agents reach you where you are. Agents can also message each other across project boundaries.

• Telegram and webhook adapters built in
• Add new channels with a plugin, no custom bots required
• Messages persist when terminals close
• Your research agent can notify your coding agent. No copy-paste required.

Mesh - Agent Discovery

Scans your projects and finds agent-capable directories. You approve which agents join the network. They coordinate through channels you define.

• Finds Claude Code, Cursor, and Codex projects automatically
• Each agent gets an identity: name, color, icon, purpose
• Agents know about each other: what they can do and how to reach them
• From solo agents to a coordinated team

Console - Browser UI

Your agents have names, colors, and status. Glance at your browser tabs and know which ones are working, which are done, and which need your attention.

Start a session from the browser. Check on it from your phone. Resume it from inside Obsidian. Every session, regardless of which client started it, visible in one place.

• Rich markdown rendering with full session history
• Approve or deny tool calls from any device
• Real-time sync across multiple clients
• Available in any browser or embedded in Obsidian

Extensions

Agents can build and install extensions that add new capabilities. Extensions define their own settings, secrets, and entry points — all managed through the UI.

MCP Server

DorkOS exposes an MCP server at /mcp (Streamable HTTP transport) so external AI agents — Claude Code, Cursor, Windsurf — can use DorkOS tools directly. Optional API key auth via MCP_API_KEY.

claude mcp add dorkos --transport http http://localhost:4242/mcp

CLI Reference

dorkos                        # Start the server
dorkos --port 8080            # Custom port
dorkos --dir ~/projects       # Custom working directory
dorkos --tunnel               # Enable remote access via ngrok
dorkos --tasks                # Enable Tasks scheduler
dorkos --no-open              # Don't open browser on startup
dorkos config                 # Show all settings
dorkos config set <key> <val> # Update a setting
dorkos init                   # Interactive setup wizard
dorkos init --yes             # Accept all defaults
dorkos cleanup                # Remove all DorkOS data

Flags

| Flag | Description | | ------------------------- | -------------------------------------------------------------- | | -p, --port <port> | Port to listen on (default: 4242) | | -d, --dir <path> | Working directory | | -b, --boundary <path> | Directory boundary (default: home directory) | | -t, --tunnel | Enable ngrok tunnel for remote access | | --tasks / --no-tasks | Enable or disable the Tasks scheduler | | --no-open | Don't open browser on startup | | -l, --log-level <level> | Log level (fatal, error, warn, info, debug, trace) | | --post-install-check | Verify installation and exit | | -h, --help | Show help message | | -v, --version | Show version number |

Config Subcommands

| Command | Description | | --------------------------------- | --------------------------- | | dorkos config | Show all effective settings | | dorkos config get <key> | Get a single value | | dorkos config set <key> <value> | Set a single value | | dorkos config list | Full JSON output | | dorkos config reset [key] | Reset to defaults | | dorkos config edit | Open in $EDITOR | | dorkos config path | Print config file location | | dorkos config validate | Check validity |

Environment Variables

Required

| Variable | Description | | ------------------- | ---------------------- | | ANTHROPIC_API_KEY | Your Anthropic API key |

Optional

| Variable | Default | Description | | ---------------------- | ----------------- | -------------------------------------- | | DORKOS_PORT | 4242 | Server port | | DORKOS_HOST | localhost | Server host (use 0.0.0.0 for Docker) | | DORKOS_DEFAULT_CWD | Current directory | Default working directory for sessions | | DORKOS_BOUNDARY | Home directory | Directory boundary root | | DORK_HOME | ~/.dork | Override data directory location | | LOG_LEVEL | info | Log verbosity | | DORKOS_TASKS_ENABLED | true | Enable or disable the Tasks scheduler | | DORKOS_OPEN | true | Open browser on startup | | DORKOS_RELAY_ENABLED | true | Enable the Relay message bus | | DORKOS_CORS_ORIGIN | localhost | CORS allowed origin(s) | | MCP_API_KEY | (none) | API key for MCP server authentication |

Remote Access

| Variable | Description | | ----------------- | ------------------------------------------- | | TUNNEL_ENABLED | Set to true to enable ngrok tunnel | | NGROK_AUTHTOKEN | Your ngrok authentication token | | TUNNEL_DOMAIN | Custom tunnel domain (optional) | | TUNNEL_AUTH | Basic auth in user:pass format (optional) |

Docker

docker build -f Dockerfile.run --build-arg INSTALL_MODE=npm -t dorkos .
docker run --rm -p 4242:4242 \
  -e ANTHROPIC_API_KEY=your-key-here \
  -e DORKOS_HOST=0.0.0.0 \
  dorkos

Updating

DorkOS checks for new versions on startup and displays an update notice when one is available. Check your current version:

dorkos --version

Update to the latest release:

npm install -g dorkos@latest
# or
pnpm add -g dorkos@latest

For Homebrew, Docker, and other update methods, see the full upgrade guide.

API Documentation

Interactive API docs at /api/docs (Scalar UI) and raw OpenAPI spec at /api/openapi.json.

Open Source

MIT-licensed. Open source. Runs on your machine. Your agents, your data, your rules.

Choose your permission mode, from approve-every-tool-call to fully autonomous. Every session is recorded locally. When your agent runs overnight, you'll see exactly what it did in the morning.

• Documentation
• Changelog
• GitHub
• Issues

License

MIT