> ## Documentation Index > Fetch the complete documentation index at: https://docs.drkm.dev/llms.txt > Use this file to discover all available pages before exploring further. # Installation > Install the drkm command, start a local outpost or sign in to one you already have, and get the Python SDK where your code runs. ## Install the CLI One command installs `drkm` on Apple silicon macOS and on x86-64 or ARM64 Linux. Run it as your own user, not as root, with `curl` on the PATH. It prints a sign-in link and an eight-character confirmation code; open the link on any device, sign in with the Microsoft account Darkmatter granted installer access to, and confirm the code. The code expires after five minutes. The installer then downloads the release, verifies its checksum, prints the exact command to use in the current terminal and saves PATH for new ones. * The release carries its own Python runtime, locked dependencies, terminal and console, so nothing else needs to be on your PATH. Nothing is compiled or fetched from package indexes. * On Linux, the tools a local outpost needs are installed if missing: Docker Engine and Buildx, k3d, Helm, kubectl and Nebula. Preparing the machine can prompt for your password. * On macOS the installer prepares nothing else. The first `drkm start` that runs the outpost in its dedicated `drkm-kvm` Linux VM, the default on a Mac, installs the VM and its tools, and can prompt for your password. * Installer access is separate from console accounts and mesh membership. It authorizes downloads and nothing else; contact Darkmatter if sign-in is refused. ```bash Terminal theme={null} curl -fsSL https://drkm.dev/install | sh ~/.local/bin/drkm --help ~/.local/bin/drkm --version ``` > [!NOTE] > > Over SSH the link still works: open it in a browser on any machine and enter the code. The sign-in requests no refresh token and nothing is written to the shell history. ## Where things live * **`~/.local/share/drkm`**: The installation: each release under `releases/`, a `current` link, and install logs under `logs/`. * **`~/.local/bin/drkm`**: The command, linked into the current release. * **`~/.drkm`**: Your outpost: its data directory, its settings and credentials under `outposts/`, and console profiles. Reinstalls and updates never touch it. Read and change the outpost's settings with `drkm config list`, `get`, `set` and `unset`. Running the installer again over an existing installation asks whether to remove it and install fresh or upgrade in place with your settings carried forward. To skip the prompt, set `DRKM_INSTALL_REPLACE=yes` or `no` in the environment of the `sh` process. ```bash Run the installer again without a prompt theme={null} # Upgrade in place, settings carried forward curl -fsSL https://drkm.dev/install | DRKM_INSTALL_REPLACE=no sh # Remove the installation and install fresh; ~/.drkm is kept curl -fsSL https://drkm.dev/install | DRKM_INSTALL_REPLACE=yes sh ``` ## Start a local outpost `drkm start` provisions the outpost on this machine, prints its address and attaches the terminal workspace. The first start loads the release's prebuilt application image (or builds it when the release has none), creates the local cluster and pulls its service images, so it takes longer than later starts. The console is served at `https://drkm.localhost:3756` by default, and every start also prints a name for your local network, `https://.local`. The first start asks three things: * **Identity.** Create the first administrator with a password, or point the outpost at an OIDC provider you already run. `drkm setup` completes this step on its own, and `drkm setup --file` reads it from a private JSON file for unattended installs. * **Name.** A callsign for the fleet, such as `harbor-mac`. `--tag` sets it without a prompt; leave it blank for a generated one. * **Inference.** Connect a provider with an API key, run a local model sized for this device’s GPU, or set up later. The server keeps running without a model. Resume at any time with `drkm models setup`; see [models and inference](https://docs.drkm.dev/models.md). A fresh installation belongs to no mesh. The console and the local outpost work on their own until you [create or join a mesh](https://docs.drkm.dev/mesh.md). ```bash Terminal theme={null} # Provision, print the console address, attach the terminal drkm start # Name the outpost for the fleet, or choose its ports drkm start --tag harbor-mac drkm start --https-port 3756 --http-port 8081 # Start without attaching the terminal drkm start console # Finish identity or inference setup later drkm setup drkm models setup drkm stop ``` > [!NOTE] > > On a Mac the outpost runs in the drkm-kvm VM by default. drkm start --native runs it without the VM on Apple silicon; the first native start asks for macOS administrator approval once to install the mesh helper. drkm start --vm switches back. Stop the outpost before switching. ## Sign in to an existing outpost You do not need a local outpost to work. Sign this terminal in to any outpost you can reach, then use the same `drkm console` commands against it. After `drkm start` the terminal already knows your local outpost, so `drkm console login` with no address signs in there. * `--device` prints a code to confirm in a browser through the outpost’s identity provider. Use it on a machine without a browser. * `--password` prompts for email and password, where the outpost allows password sign-in. * `--token` accepts an ID token minted by the provider out of band. Keep saved credentials in the OS keyring. For automation, inject an API key or ID token from your secret manager into `DRKM_TOKEN` at runtime; do not save it in a script or file. A saved sign-in is bound to the address it used. For an outpost on a private mesh with its own certificate authority, pass `--tls-ca` with the CA bundle. ```bash Terminal theme={null} drkm console login https://outpost.example --device drkm console whoami # A private-mesh outpost with its own certificate authority drkm console --tls-ca /path/to/ca.pem login https://outpost.example --device # Target an outpost from the environment instead DRKM_URL=https://outpost.example DRKM_TOKEN="$ID_TOKEN" drkm console jobs drkm console logout ``` ## Get the Python SDK The SDK is the `drkm` package: Python 3.12 or later, standard library only. Where you use it decides how you get it. * **Inside an agent sandbox** it is already installed. Code the agent runs can `import drkm` at once. * **In the installed release**, the `drkm` command’s own Python environment carries it. * **In your own environment**, install it from the release on that machine: `pip install ~/.local/share/drkm/current/sdk`. From a source checkout, `pip install ./sdk` builds the same package. The `drkm` name on the public package index is a pointer, not the SDK: `import drkm` succeeds and any use raises `SDKNotIncluded` with instructions for getting the real package. Keep the SDK aligned with the release of the outpost you connect to. ```bash Terminal theme={null} python3 -m venv .venv source .venv/bin/activate python -m pip install ~/.local/share/drkm/current/sdk python -c "import drkm; help(drkm.connect)" ``` > [!NOTE] > > To reuse a sign-in stored in the OS keyring, install the keyring package beside the SDK with python -m pip install keyring. For automation without a keyring, inject an API key from your secret manager into DRKM\_TOKEN at runtime. ## Update and check versions `drkm update` fetches the latest published release, verifies its checksum, upgrades the installation in place and redeploys a running outpost, restoring the previous release if the new one never becomes healthy. Settings and outpost data already stored in the active home (`$DRKM_HOME`, or `~/.drkm` by default) survive the release change. Older installations with a custom data directory need the migration below. A stopped outpost comes up on the new release at its next `drkm start`. Installation registers a per-machine update key with the same approval as the download, so later updates need no browser. Outposts also update themselves once a day unless an administrator turns **Automatic updates** off in **Settings → Updates**, where **Check for updates** and **Update now** live as well. An update restarts the outpost. ```bash Terminal theme={null} drkm update drkm --version # the installed product version drkm version # compares it with the running outpost drkm version --diagnostics # build identity # Re-approve this machine after a refused update grant drkm update --authorize ``` ### Before updating a legacy custom data directory If you set `DRKM_HOME` and an older installation still uses `drkm-local:dataDir` in its Pulumi stack, migrate that data before updating. An explicit home disables automatic legacy-data migration. The update removes `dataDir` from the carried primary stack; the new release reads `$DRKM_HOME/data` instead. It leaves the old directory in place, but does not find its data automatically. 1. Turn off **Automatic updates** in **Settings → Updates**. Record the old `dataDir` path from the current release's stack file; resolve a relative path against that release's `infrastructure/local` directory. 2. Stop the old outpost with its existing release and home setting. Back up the complete old data directory and the active home before copying anything; do not copy a running database. 3. If `$DRKM_HOME/data` already exists, stop here: do not overwrite it or merge two outposts' data. Otherwise copy the entire old data directory to `$DRKM_HOME/data`, including hidden files, preserving ownership and permissions. Keep the original and backup. 4. Use the same `DRKM_HOME` for `drkm update` and the next `drkm start`. Confirm the outpost's identity and existing data in the console before re-enabling automatic updates or retiring the old copy. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.