# Deployment
Source: https://dorkos.ai/docs/self-hosting/deployment

Run your own DorkOS server, from a one-line quick start to a production setup with systemd



# Deployment [#deployment]

DorkOS deploys as a standalone server via the `dorkos` npm package. One process serves both the API and the web cockpit, so nothing but your calls to Anthropic ever leaves the machine it's running on. Run it on your laptop, a spare desktop, or a cloud box, it's the same install either way.

This page covers the Claude Code runtime (the default). If you're running Codex or OpenCode instead, check their setup docs for the credentials they expect.

## Docker or a direct install? [#docker-or-a-direct-install]

For most servers, Docker is the easier default. It keeps DorkOS isolated from the rest of the machine, checks its own health automatically, and upgrades in a couple of commands, all while running as a regular, unprivileged user instead of root. Start with the [Docker guide](/docs/self-hosting/docker).

A direct install, like the one below, fits better when your agents need broad access to code already on the machine. A container only sees the folders you mount into it, while a direct install (paired with systemd, covered further down) can reach anything your OS user can.

## Quick Deploy [#quick-deploy]

```bash
npm install -g dorkos
export ANTHROPIC_API_KEY=your-key-here
dorkos --port 4242
```

Open `http://localhost:4242` in your browser. That's your cockpit, already running. (Don't have a key yet? The [Installation guide](/docs/getting-started/installation) shows you where to get one.)

Everything past this point is optional: production hardening for when you're running DorkOS somewhere other than your own machine.

## Reference: production configuration [#reference-production-configuration]

Most people never touch what follows, it's here for when you're putting DorkOS on a shared server, a systemd unit, or anywhere else that isn't a quick local run.

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

    ```bash
    npm install -g dorkos
    ```
  </Step>

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

    <Tabs items="[&#x22;Environment Variables&#x22;, &#x22;Interactive Setup&#x22;]">
      <Tab value="Environment Variables">
        ````bash export ANTHROPIC_API_KEY=your-key-here export DORKOS_PORT=4242 export
        DORKOS_DEFAULT_CWD=/path/to/projects export DORKOS_BOUNDARY=/path/to/boundary ```
        </Tab>

        <Tab value="Interactive Setup">
        ```bash
        dorkos init
        ````

        The setup wizard asks for the port, UI theme (system, light, or dark), whether to enable a tunnel, and a default working directory. Configuration is saved to `~/.dork/config.json`.
      </Tab>
    </Tabs>
  </Step>

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

    ```bash
    dorkos
    ```

    <Callout type="info">
      Config precedence: CLI flags > environment variables > `~/.dork/config.json` > built-in defaults.
    </Callout>
  </Step>
</Steps>

### Environment variables [#environment-variables]

Here's the full list, in case you're scripting a deployment or writing a systemd unit:

<TypeTable
  type="{
  ANTHROPIC_API_KEY: { type: 'string', description: 'Claude API key (required)' },
  DORKOS_PORT: { type: 'number', description: 'Server port', default: &#x22;'4242'&#x22; },
  DORKOS_HOST: {
    type: 'string',
    description:
      'Which network address the server listens on. Set to 0.0.0.0 to let other devices on your network (or a Docker host) reach it',
    default: &#x22;'localhost'&#x22;,
  },
  DORKOS_DEFAULT_CWD: {
    type: 'string',
    description: 'Default working directory',
    default: 'Repo root',
  },
  DORKOS_BOUNDARY: {
    type: 'string',
    description: 'The folder DorkOS is allowed to touch (see Directory Boundary below)',
    default: 'Home directory',
  },
  DORKOS_AUTH_SIGNIN_RATE_LIMIT: {
    type: 'number',
    description:
      'Max sign-in attempts allowed from one IP address in a 15-minute window before it is briefly blocked. Raise it if a shared network locks you out.',
    default: &#x22;'10'&#x22;,
  },
  DORKOS_ACTIVITY_RETENTION_DAYS: {
    type: 'number',
    description: 'How many days of activity history to keep before old events are pruned.',
    default: &#x22;'30'&#x22;,
  },
  NODE_ENV: {
    type: 'string',
    description:
      &#x22;You do not set this. The dorkos CLI pins it to 'production' on every start. The 'development' default only applies when you run the server from source with pnpm dev.&#x22;,
    default: &#x22;'production'&#x22;,
  },
}"
/>

### Directory Boundary [#directory-boundary]

`DORKOS_BOUNDARY` is the folder DorkOS is allowed to touch. Every `cwd`, `path`, and `dir` parameter a request sends is checked against it; anything outside returns a `403` and gets rejected.

<Callout type="warn">
  The default boundary is your whole home directory. For anything public-facing, fence it in tighter
  than that: point `DORKOS_BOUNDARY` at just the folder your projects live in.
</Callout>

### systemd Service [#systemd-service]

For long-running deployments on Linux, running DorkOS as a systemd service means it restarts automatically after a crash or reboot:

```ini title="/etc/systemd/system/dorkos.service"
[Unit]
Description=DorkOS - Autonomous Agent Operating System
After=network.target

[Service]
Type=simple
User=dorkos
Environment=ANTHROPIC_API_KEY=your-key-here
Environment=DORKOS_PORT=4242
Environment=DORKOS_HOST=0.0.0.0
Environment=DORKOS_DEFAULT_CWD=/home/dorkos/projects
Environment=DORKOS_BOUNDARY=/home/dorkos/projects
ExecStart=/usr/local/bin/dorkos
Restart=on-failure
RestartSec=5

[Install]
WantedBy=multi-user.target
```

Enable and start:

```bash
sudo systemctl enable dorkos
sudo systemctl start dorkos
```

### Docker Deployment [#docker-deployment]

For Docker-based deployments, including `docker run`, Docker Compose, persistent volumes, and reverse proxy setup, see the dedicated [Docker guide](/docs/self-hosting/docker).

### Health Check [#health-check]

Point a load balancer or monitoring tool at this endpoint to confirm the server is alive:

```bash
curl http://localhost:4242/api/health
# { "status": "ok", "version": "x.y.z", "uptime": 12345 }
```

When a tunnel (a secure link that exposes your local server to the internet without opening firewall ports) is active, the response includes a `tunnel` field with its status.

<Callout type="info">
  The health endpoint is unauthenticated on purpose, so monitoring tools can reach it without a key.
</Callout>

## Next Steps [#next-steps]

<Cards>
  <Card title="Reverse Proxy" href="/docs/self-hosting/reverse-proxy">
    Configure nginx or Caddy for HTTPS, domain routing, and SSE (the live-update stream the cockpit
    uses) compatibility.
  </Card>

  <Card title="Tunnel Setup" href="/docs/self-hosting/tunnel-setup">
    Expose your instance remotely via ngrok without a reverse proxy.
  </Card>

  <Card title="Configuration" href="/docs/getting-started/configuration">
    Full configuration reference for ports, directories, and persistent settings.
  </Card>
</Cards>