Getting started

This walks you from nothing to a running machine you can reach on the open web: install the CLI, sign in so apply can provision on your behalf, declare a machine in a Dorkyfile, and apply it.

Install the CLI

The dorky CLI is a single-file binary built from the repository. Clone the repo and build it once:

git clone https://github.com/awhitty/dorky.git
cd dorky
bun run install:cli

install:cli compiles the binary and links dorky into a directory on your PATH (defaulting to ~/.bun/bin). If that directory is not on your PATH, the installer prints the exact line to add.

Check the install with:

dorky version

The binary is a point-in-time snapshot, so after you pull new changes, re-run bun run install:cli to refresh it. dorky version prints the binary's own build date, so staleness is easy to spot.

Sign in

dorky login stores a provision grant so that dorky apply can provision machines through the hosted provisioner, with no substrate credentials of your own on this computer.

Mint a grant from your account home at key.dorky.host, then hand it to the CLI:

dorky login https://<provisioner-url>

On a terminal you are prompted to paste the grant (the input stays hidden). The grant is a bearer secret, so it never rides the command line. The CLI decodes it to show the non-secret facts (the account it names, the substrate it permits, its expiry), refuses anything that is not a provision grant, and writes it to your config at 0600. The value itself is never echoed back.

Piping works too, which is handy for scripts and agents:

pbpaste | dorky login https://<provisioner-url>

The hosted provisioner is coming online

The dorky login verb and the credential-less dorky apply path are built. The public key.dorky.host account home that mints grants is being brought up as a live surface. Until it is live, you can still declare and preview machines with dorky apply --plan (shown below), which needs no account and nothing configured.

Declare and apply your first machine

A machine is described by a Dorkyfile named <name>.dorky.toml. The fastest way to start is dorky new, which scaffolds the smallest Dorkyfile that provisions and applies it:

dorky new hello

That writes hello.dorky.toml (a name and a substrate) and provisions the machine named hello.

You can also write the file yourself and apply it. Preview first with --plan — a pure local read that works in an empty directory with nothing set up — then apply for real:

dorky apply hello.dorky.toml --plan   # preview the ship manifest, change nothing
dorky apply hello.dorky.toml          # provision on first run, reconcile after

dorky apply is the one verb you keep using. Edit the Dorkyfile and apply it again, and the machine converges to the new description. A change to services, routes, or upstreams applies live; only an [image] line reboots the machine.

To see what a machine runs and whether the last apply landed:

dorky status hello

Reach it

The machine answers at its own subdomain, hello.dorky.host. Its name is its address.

A few verbs cover the rest of the loop:

dorky ls              # list your machines
dorky chat hello      # open a browser chat with the machine's agent (--open)
dorky diff hello      # compare the running machine to its Dorkyfile
dorky rm hello        # destroy the machine (the Dorkyfile stays)

dorky rm removes the machine, never the file. The Dorkyfile is the durable declaration; a later dorky apply recreates the machine from it.