Installation
Install DorkOS and open the cockpit where you run, schedule, and check on your coding agents
Installation
DorkOS gives you a browser tab where you run, schedule, and check on your coding agents. Install it once, and it starts in seconds whenever you need it.
Before you start
Every install method needs a Claude API key (a key from Anthropic that lets DorkOS talk to Claude on your behalf). If you don't have one yet, create it there first. Everything except Docker and the desktop app also needs Node.js 22 or later, the JavaScript runtime DorkOS runs on. (The desktop app and Docker bring their own, so you don't have to install anything else.)
Try it without installing
Curious before you commit to anything? If you have Node.js 22 or newer, you can run DorkOS straight from npm with npx, no install step first:
npx dorkos@latestThe first run takes a minute or two: npx downloads DorkOS and compiles a couple of native pieces it depends on. After that, your browser opens to the same cockpit a permanent install gives you.
Already signed in to Claude Code? You're set. Otherwise, set your API key first:
export ANTHROPIC_API_KEY="your-key-here"
npx dorkos@latestLike what you see? Install DorkOS for good with one of the methods below, and skip that first-run wait every time you start it.
Pick your install method
Most people should use the one-liner: it's one command and it checks your setup for you. Already comfortable with npm? Use the npm tab. On a Mac and want a real app in your dock, no terminal at all? Use the Desktop App (there is a new Windows version too, still in early testing). Running on a server, or don't want Node.js on your machine? Use Docker. Contributing to DorkOS itself? Use Self-Hosted.
One command, no yak-shaving: it checks your Node.js version, installs DorkOS, and can walk you through setup.
Install DorkOS
curl -fsSL https://dorkos.ai/install | bashThis checks for Node.js 22+, installs DorkOS, and asks if you'd like to run the setup wizard. Say yes and it'll ask for your preferred port, a UI theme, and which folder you want DorkOS to work in by default. You can change any of these later.
Set your API key
export ANTHROPIC_API_KEY="your-key-here"An environment variable is a value your shell hands to programs when they start, in this case your API key. Add this line to your shell profile (~/.bashrc, ~/.zshrc, or similar) so you don't have to retype it every time you open a terminal.
Start DorkOS
dorkosDorkOS starts on port 4242 (the address your browser uses to reach it) and opens your browser automatically to the DorkOS cockpit.
CI/Automation: Skip interactive prompts with --no-prompt: bash curl -fsSL https://dorkos.ai/install | bash -s -- --no-prompt Pin a specific version: curl -fsSL https://dorkos.ai/install | bash -s 1.2.3
If you already have a package manager on hand, skip the one-liner and install DorkOS the way you install everything else.
Install the package
npm install -g dorkosSet your API key
export ANTHROPIC_API_KEY="your-key-here"Add this to your shell profile (~/.bashrc, ~/.zshrc, or similar) to persist it across sessions.
Verify the installation
dorkos --versionPass flags to customize startup: dorkos --port 8080 --dir ~/projects/my-app. Run dorkos --help
for all options.
The desktop app is new. It runs on Macs with Apple Silicon (the M1 chip or later) and is under active development, so expect a rough edge here and there. If you hit trouble, the web cockpit from the tabs above is the most battle-tested way to run DorkOS today.
A real Mac app: it's the same DorkOS cockpit, in its own window and dock icon, with nothing to install in a terminal. It bundles everything it needs, including Claude Code, so you don't need Node.js.
Download and install
Download the app from dorkos.ai/download/mac, open the .dmg, and drag DorkOS to your Applications folder. The first time you open it, macOS asks you to confirm you want to run it; click Open.
Connect your agent
On first launch, DorkOS walks you through connecting Claude: sign in to your Claude account, or paste your Anthropic API key. That's it, no environment variables to set.
On Windows (early alpha)
There is now a Windows version too, and it is brand new. Download it from dorkos.ai/download/windows and run the installer.
Windows may show a blue "Windows protected your PC" message, because the app is not signed yet. Click More info, then Run anyway to continue. We have not finished testing the Windows app on a real machine, so treat it as an early preview. If something does not work, the web cockpit from the tabs above is the most reliable way to run DorkOS today.
The desktop app updates itself (on Windows this rides the same mechanism as the unverified alpha build, so treat it as unverified too). When a new version is out, it downloads in the background and installs the next time you quit and reopen the app, so you're always current without lifting a finger.
See the Desktop App guide for the full menu, deep link, and auto-update details, plus what it doesn't do that the web cockpit does.
Run DorkOS in a container. No Node.js installation required on the host, only Docker.
Pull and run
docker run -d --name dorkos \
-p 4242:4242 \
-e ANTHROPIC_API_KEY=your-key-here \
-v dorkos-data:/home/node/.dork \
ghcr.io/dork-labs/dorkos:latestThe -v dorkos-data:/home/node/.dork part creates a Docker volume, a small chunk of storage that survives even if you remove the container, so your sessions and settings stick around.
Open the interface
Navigate to http://localhost:4242 in your browser. You'll land on the DorkOS cockpit.
For persistent data, custom ports, Docker Compose, and production hardening, see the Docker
deployment guide. Pin a specific version for reproducible deployments:
ghcr.io/dork-labs/dorkos:0.12.0.
The Obsidian plugin (built as DorkOS Copilot) is early. It's not yet listed in Obsidian's community plugin directory, and it's under active development, so expect rough edges. If you want a dependable daily driver today, use the web cockpit above; come back here once it's further along.
DorkOS Copilot embeds a chat sidebar for your agents directly inside Obsidian, so you can talk to them without leaving your notes. Because it isn't published yet, the only way to try it is to build it from source, alongside the DorkOS repo:
Build the plugin
Follow the Self-Hosted tab below to clone and install DorkOS, then build the plugin package from apps/obsidian-plugin.
Copy it into your vault
Copy the built manifest.json, main.js, and styles.css into a new folder at <your-vault>/.obsidian/plugins/dorkos-copilot/.
Enable it
In Obsidian, go to Settings → Community Plugins, make sure community plugins are enabled, then find and toggle on DorkOS Copilot.
Configure your API key
Open the DorkOS Copilot settings and enter your Anthropic API key.
For the curious: the plugin runs the same agent engine as the CLI, but in-process inside Obsidian instead of talking to a separate server. In practice that means it's fast and nothing leaves your machine, though it also means the plugin needs Node.js 22+ installed on your system.
For contributors and anyone customizing DorkOS: clone the repository and run the full development stack.
Clone the repository
git clone https://github.com/dork-labs/dorkos.git
cd dorkosInstall dependencies
pnpm installStart the development server
pnpm devThis starts the Express API server and Vite dev server together, with hot reload as you edit. The cockpit is available at http://localhost:6241.
For production builds, run pnpm build then pnpm start to serve the compiled app on port 4242.
Port already taken? If DorkOS won't start because something else is using the port, run
dorkos --port 8081 (or any free port) to start on a different one.
Updating
DorkOS checks for a newer version every time it starts. Here's how to update on each install method.
Re-run the one-liner or update with your package manager:
curl -fsSL https://dorkos.ai/install | bashCheck your current version at any time:
dorkos --versionNothing to do: the desktop app updates itself. It downloads new versions in the background and installs them the next time you quit and reopen the app. (On Windows, updates ride the same unverified alpha mechanism.)
Pull the latest image and recreate the container:
docker pull ghcr.io/dork-labs/dorkos:latest
docker stop dorkos && docker rm dorkos
docker run -d --name dorkos \
-p 4242:4242 \
-e ANTHROPIC_API_KEY=your-key-here \
-v dorkos-data:/home/node/.dork \
ghcr.io/dork-labs/dorkos:latestData in the dorkos-data volume persists across updates.
Upgrading from version 0.48.0 or earlier? The data path changed from /root/.dork to
/home/node/.dork, and existing files need an ownership fix first. See Upgrading from an older
image in the Docker guide.
Rebuild the plugin from an updated copy of the repository, then copy the new files over the ones in <your-vault>/.obsidian/plugins/dorkos-copilot/ and reload Obsidian.
git pull origin main
pnpm install
pnpm buildRestart the running server after rebuilding. Database migrations run automatically on startup. Check the changelog for breaking changes before upgrading; major releases may require configuration updates.
Reference
Deeper detail for when things go sideways or you need an exact version.
Rollback and version pinning
Something broke after an update? Roll back to the version that worked.
npm install -g dorkos@0.11.0Replace 0.11.0 with the version you want. Available versions are listed on npm and GitHub Releases.
Next steps
Head to the Quickstart to open your first session, or Configuration to customize your setup.