Installation

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 terminal and a pinned runtime, so nothing else needs to be on your PATH. Its Python tooling is installed if missing.
• Deployment tools are installed if missing: Pulumi, k3d, Nebula, Docker Engine and Buildx. Preparing the machine can prompt for your password.
• On macOS the installer prepares a dedicated drkm-kvm Linux VM, the default home of a Mac’s outpost.
• Installer access is separate from console accounts and mesh membership. It authorizes downloads and nothing else; contact Darkmatter if sign-in is refused.

curl -fsSL https://drkm.ai/install | sh

~/.local/bin/drkm --help
drkm --version

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, generated secrets and console profiles. Reinstalls and updates never touch it.

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.

# Upgrade in place, settings carried forward
curl -fsSL https://drkm.ai/install | DRKM_INSTALL_REPLACE=no sh

# Remove the installation and install fresh; ~/.drkm is kept
curl -fsSL https://drkm.ai/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 builds the application container, 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.

# 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

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.

Credentials stay in the OS keyring, or in a private file you name with --credential-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.

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_OUTPOST=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.

python3 -m venv .venv
source .venv/bin/activate
python -m pip install ~/.local/share/drkm/current/sdk

python -c "import drkm; help(drkm.connect)"

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, custom directories and outpost data are preserved. 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.

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