Installation

DorkOS runs in three modes: as a standalone npm CLI, as an Obsidian plugin, or as a self-hosted development server. Pick the one that fits your workflow.

Prerequisites

All installation methods require Node.js 18 or later and a Claude API key from the Anthropic Console.

Choose Your Install Method

The fastest way to get started. Install the dorkos package globally and run it from any directory.

Install the package

npm install -g dorkos

Set your API key

DorkOS needs your Anthropic API key to communicate with Claude:

export ANTHROPIC_API_KEY=your-key-here

To persist this, add it to your shell profile (~/.bashrc, ~/.zshrc, etc.).

Verify the installation

dorkos --version

Start DorkOS

dorkos

The server starts on port 4242 and opens your browser automatically. Visit http://localhost:4242 to see the interface.

You can pass flags to customize startup: dorkos --port 8080 --dir ~/projects/my-app. Run dorkos --help for all options.

Run DorkOS directly inside Obsidian as a sidebar panel, with full access to your vault files.

Open Obsidian settings

Go to Settings then Community Plugins and make sure community plugins are enabled.

Search for DorkOS

Click Browse and search for DorkOS in the community plugin directory.

Install and enable

Click Install, then toggle the plugin on. DorkOS appears as a sidebar view.

Configure your API key

Open the DorkOS plugin settings and enter your Anthropic API key.

The Obsidian plugin requires Node.js 18+ installed on your system. It uses the same Claude Agent SDK as the CLI but runs in-process via the DirectTransport adapter.

Clone the repository and run the full development stack. Useful for contributing or customizing DorkOS.

Clone the repository

git clone https://github.com/dork-labs/dorkos.git
cd dorkos

Install dependencies

npm install

Configure environment

Create a .env file in the repository root:

ANTHROPIC_API_KEY=your-key-here

Start the development server

npm run dev

This starts both the Express API server and Vite dev server. The interface is available at http://localhost:3000 with hot module replacement.

For production builds, run npm run build then npm start to serve the compiled app on port 4242.

Updating

Update to the latest version using the same package manager you installed with:

npm install -g dorkos@latest

DorkOS checks for new versions on startup and shows a notification when an update is available. You can check your current version at any time:

dorkos --version

Obsidian handles plugin updates automatically. To check manually, go to Settings then Community Plugins, find DorkOS in your installed plugins, and click Update if available.

Pull the latest changes and rebuild:

git pull origin main
npm install
npm run build

Next Steps

You are ready to start using DorkOS. Head to the Quickstart guide to walk through your first conversation, or check out Configuration to customize your setup.

Installation

On this page