# Installation
Source: https://dorkos.ai/docs/getting-started/installation

Install DorkOS and open the cockpit where you run, schedule, and check on your coding agents



# Installation [#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 [#before-you-start]

<Callout type="info">
  Every install method needs a Claude API key (a key from
  [Anthropic](https://console.anthropic.com/) 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](https://nodejs.org/) 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.)
</Callout>

## Try it without installing [#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:

```bash
npx dorkos@latest
```

The 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:

```bash
export ANTHROPIC_API_KEY="your-key-here"
npx dorkos@latest
```

Like 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 [#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.

<Tabs items="['One-liner (Recommended)', 'npm', 'Desktop App', 'Docker', 'Obsidian Plugin', 'Self-Hosted']">
  <Tab value="One-liner (Recommended)">
    One command, no yak-shaving: it checks your Node.js version, installs DorkOS, and can walk you through setup.

    <Steps>
      <Step>
        ### Install DorkOS [#install-dorkos]

        ```bash
        curl -fsSL https://dorkos.ai/install | bash
        ```

        This 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.
      </Step>

      <Step>
        ### Set your API key [#set-your-api-key]

        ```bash
        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.
      </Step>

      <Step>
        ### Start DorkOS [#start-dorkos]

        ```bash
        dorkos
        ```

        DorkOS starts on port 4242 (the address your browser uses to reach it) and opens your browser automatically to the DorkOS cockpit.
      </Step>
    </Steps>

    <Callout type="info">
      **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`
    </Callout>
  </Tab>

  <Tab value="npm">
    If you already have a package manager on hand, skip the one-liner and install DorkOS the way you install everything else.

    <Steps>
      <Step>
        ### Install the package [#install-the-package]

        <CodeBlockTabs defaultValue="npm">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="yarn">
              yarn
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="bun">
              bun
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="npm">
            ```bash
            npm install -g dorkos
            ```
          </CodeBlockTab>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm add -g dorkos
            ```
          </CodeBlockTab>

          <CodeBlockTab value="yarn">
            ```bash
            yarn global add dorkos
            ```
          </CodeBlockTab>

          <CodeBlockTab value="bun">
            ```bash
            bun add -g dorkos
            ```
          </CodeBlockTab>
        </CodeBlockTabs>
      </Step>

      <Step>
        ### Set your API key [#set-your-api-key-1]

        ```bash
        export ANTHROPIC_API_KEY="your-key-here"
        ```

        Add this to your shell profile (`~/.bashrc`, `~/.zshrc`, or similar) to persist it across sessions.
      </Step>

      <Step>
        ### Verify the installation [#verify-the-installation]

        ```bash
        dorkos --version
        ```
      </Step>

      <Step>
        ### Start DorkOS [#start-dorkos-1]

        ```bash
        dorkos
        ```

        DorkOS starts on port 4242 and opens your browser to the cockpit.
      </Step>
    </Steps>

    <Callout type="info">
      Pass flags to customize startup: `dorkos --port 8080 --dir ~/projects/my-app`. Run `dorkos --help`
      for all options.
    </Callout>
  </Tab>

  <Tab value="Desktop App">
    <Callout type="warn">
      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.
    </Callout>

    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.

    <Steps>
      <Step>
        ### Download and install [#download-and-install]

        Download the app from [dorkos.ai/download/mac](https://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**.
      </Step>

      <Step>
        ### Connect your agent [#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.
      </Step>
    </Steps>

    ### On Windows (early alpha) [#on-windows-early-alpha]

    There is now a Windows version too, and it is brand new. Download it from [dorkos.ai/download/windows](https://dorkos.ai/download/windows) and run the installer.

    <Callout type="warn">
      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.
    </Callout>

    <Callout type="info">
      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.
    </Callout>

    See the [Desktop App guide](/docs/getting-started/desktop-app) for the full menu, deep link, and
    auto-update details, plus what it doesn't do that the web cockpit does.
  </Tab>

  <Tab value="Docker">
    Run DorkOS in a container. No Node.js installation required on the host, only [Docker](https://docs.docker.com/get-docker/).

    <Steps>
      <Step>
        ### Pull and run [#pull-and-run]

        ```bash
        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:latest
        ```

        The `-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.
      </Step>

      <Step>
        ### Open the interface [#open-the-interface]

        Navigate to [http://localhost:4242](http://localhost:4242) in your browser. You'll land on the DorkOS cockpit.
      </Step>
    </Steps>

    <Callout type="info">
      For persistent data, custom ports, Docker Compose, and production hardening, see the [Docker
      deployment guide](/docs/self-hosting/docker). Pin a specific version for reproducible deployments:
      `ghcr.io/dork-labs/dorkos:0.12.0`.
    </Callout>
  </Tab>

  <Tab value="Obsidian Plugin">
    <Callout type="warn">
      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.
    </Callout>

    DorkOS Copilot embeds a chat sidebar for your agents directly inside [Obsidian](https://obsidian.md/), 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:

    <Steps>
      <Step>
        ### Build the plugin [#build-the-plugin]

        Follow the Self-Hosted tab below to clone and install DorkOS, then build the plugin package from `apps/obsidian-plugin`.
      </Step>

      <Step>
        ### Copy it into your vault [#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/`.
      </Step>

      <Step>
        ### Enable it [#enable-it]

        In Obsidian, go to **Settings** → **Community Plugins**, make sure community plugins are enabled, then find and toggle on **DorkOS Copilot**.
      </Step>

      <Step>
        ### Configure your API key [#configure-your-api-key]

        Open the DorkOS Copilot settings and enter your Anthropic API key.
      </Step>
    </Steps>

    <Callout type="info">
      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.
    </Callout>
  </Tab>

  <Tab value="Self-Hosted">
    For contributors and anyone customizing DorkOS: clone the repository and run the full development stack.

    <Steps>
      <Step>
        ### Clone the repository [#clone-the-repository]

        ```bash
        git clone https://github.com/dork-labs/dorkos.git
        cd dorkos
        ```
      </Step>

      <Step>
        ### Install dependencies [#install-dependencies]

        <CodeBlockTabs defaultValue="pnpm">
          <CodeBlockTabsList>
            <CodeBlockTabsTrigger value="pnpm">
              pnpm
            </CodeBlockTabsTrigger>

            <CodeBlockTabsTrigger value="npm">
              npm
            </CodeBlockTabsTrigger>
          </CodeBlockTabsList>

          <CodeBlockTab value="pnpm">
            ```bash
            pnpm install
            ```
          </CodeBlockTab>

          <CodeBlockTab value="npm">
            ```bash
            npm install
            ```
          </CodeBlockTab>
        </CodeBlockTabs>
      </Step>

      <Step>
        ### Configure environment [#configure-environment]

        Create a `.env` file in the repository root:

        ```bash
        ANTHROPIC_API_KEY=your-key-here
        ```
      </Step>

      <Step>
        ### Start the development server [#start-the-development-server]

        ```bash
        pnpm dev
        ```

        This starts the Express API server and Vite dev server together, with hot reload as you edit. The cockpit is available at [http://localhost:6241](http://localhost:6241).
      </Step>
    </Steps>

    <Callout type="info">
      For production builds, run `pnpm build` then `pnpm start` to serve the compiled app on port 4242.
    </Callout>
  </Tab>
</Tabs>

<Callout type="info">
  **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.
</Callout>

## Updating [#updating]

DorkOS checks for a newer version every time it starts. Here's how to update on each install method.

<Tabs items="['One-liner / npm', 'Desktop App', 'Docker', 'Obsidian Plugin', 'Self-Hosted']">
  <Tab value="One-liner / npm">
    Re-run the one-liner or update with your package manager:

    <CodeBlockTabs defaultValue="One-liner">
      <CodeBlockTabsList>
        <CodeBlockTabsTrigger value="One-liner">
          One-liner
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="npm">
          npm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="pnpm">
          pnpm
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="yarn">
          yarn
        </CodeBlockTabsTrigger>

        <CodeBlockTabsTrigger value="bun">
          bun
        </CodeBlockTabsTrigger>
      </CodeBlockTabsList>

      <CodeBlockTab value="One-liner">
        ```bash
        curl -fsSL https://dorkos.ai/install | bash
        ```
      </CodeBlockTab>

      <CodeBlockTab value="npm">
        ```bash
        npm install -g dorkos@latest
        ```
      </CodeBlockTab>

      <CodeBlockTab value="pnpm">
        ```bash
        pnpm add -g dorkos@latest
        ```
      </CodeBlockTab>

      <CodeBlockTab value="yarn">
        ```bash
        yarn global add dorkos@latest
        ```
      </CodeBlockTab>

      <CodeBlockTab value="bun">
        ```bash
        bun add -g dorkos@latest
        ```
      </CodeBlockTab>
    </CodeBlockTabs>

    Check your current version at any time:

    ```bash
    dorkos --version
    ```
  </Tab>

  <Tab value="Desktop App">
    Nothing 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.)
  </Tab>

  <Tab value="Docker">
    Pull the latest image and recreate the container:

    ```bash
    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:latest
    ```

    Data in the `dorkos-data` volume persists across updates.

    <Callout type="warn">
      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](/docs/self-hosting/docker#upgrading-from-an-older-image) in the Docker guide.
    </Callout>
  </Tab>

  <Tab value="Obsidian Plugin">
    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.
  </Tab>

  <Tab value="Self-Hosted">
    ```bash
    git pull origin main
    pnpm install
    pnpm build
    ```

    Restart the running server after rebuilding. Database migrations run automatically on startup. Check the [changelog](/docs/changelog) for breaking changes before upgrading; major releases may require configuration updates.
  </Tab>
</Tabs>

## Reference [#reference]

Deeper detail for when things go sideways or you need an exact version.

### Rollback and version pinning [#rollback-and-version-pinning]

Something broke after an update? Roll back to the version that worked.

<Callout type="info">
  <CodeBlockTabs defaultValue="npm">
    <CodeBlockTabsList>
      <CodeBlockTabsTrigger value="npm">
        npm
      </CodeBlockTabsTrigger>

      <CodeBlockTabsTrigger value="Docker">
        Docker
      </CodeBlockTabsTrigger>
    </CodeBlockTabsList>

    <CodeBlockTab value="npm">
      ```bash
      npm install -g dorkos@0.11.0
      ```
    </CodeBlockTab>

    <CodeBlockTab value="Docker">
      ```bash
      docker pull ghcr.io/dork-labs/dorkos:0.11.0
      ```
    </CodeBlockTab>
  </CodeBlockTabs>

  Replace `0.11.0` with the version you want. Available versions are listed on [npm](https://www.npmjs.com/package/dorkos?activeTab=versions) and [GitHub Releases](https://github.com/dork-labs/dorkos/releases).
</Callout>

## Next steps [#next-steps]

Head to the [Quickstart](/docs/getting-started/quickstart) to open your first session, or [Configuration](/docs/getting-started/configuration) to customize your setup.