dorkos

 

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