Skip to main content

​
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.
Terminal
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.
Run the installer again without a prompt

​
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://<callsign>.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.
A fresh installation belongs to no mesh. The console and the local outpost work on their own until you create or join a mesh.
Terminal
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.
Terminal

​
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.
Terminal
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.
Terminal

​
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.