Install & access

How to install rk, keep it up to date, check your runtime, set up a development environment, and reach the dashboard over HTTPS.

Install

run-kit ships as a Homebrew formula:

brew install sahil87/tap/rk

This puts the rk binary on your PATH. From there, a clean install to a working dashboard with one agent running is:

rk serve -d                     # start the dashboard daemon on :3000
open http://localhost:3000      # open the dashboard in your browser

# in any tmux session:
rk riff --skill /fab-discuss    # spawn an agent workspace

Upgrade

rk update

rk update pulls the latest version via Homebrew and restarts the daemon so the new binary takes effect immediately.

Prerequisites

rk riff requires:

A running tmux session ($TMUX set).
wt on your PATH — install via brew install sahil87/tap/wt, or via the toolkit meta-formula brew install sahil87/tap/all.
The launcher (default claude --dangerously-skip-permissions) available.

When something breaks, run:

rk doctor

rk doctor checks tmux, wt, the launcher binary, port availability, and prints per-dependency status. Run this first when something isn’t working.

Development

Run just doctor to check development prerequisites (Node 20+, pnpm, tmux, just, Go 1.22+, air, direnv), then:

just setup
just dev       # watch mode (Go backend + Vite dev server)
just prod      # run from built binary

Tailscale HTTPS

run-kit binds to 127.0.0.1 by default. Some browser features (e.g., copy to clipboard) require HTTPS, and accessing run-kit from other machines on your tailnet does too. Tailscale Serve handles both with zero TLS config.

Prerequisites

Enable HTTPS on your tailnet in the Tailscale admin console under DNS > HTTPS Certificates.

Quickstart

tailscale serve --bg http://localhost:3000

run-kit is now available at:

https://<machine>.<tailnet>.ts.net

To check status or stop:

tailscale serve status
tailscale serve off

Advanced: Custom hostname

Serve run-kit under a stable hostname like runner1.<tailnet>.ts.net instead of the machine name — the URL survives moving rk to another host.

Services need a tagged node. Do these in order:

Define the tag:server tag. In Access controls, Visual editor → Tags → add a tag named server. Owners can be left empty.
Re-register the node with the tag (--operator lets you manage Tailscale without sudo afterward):
```
sudo tailscale up --advertise-tags=tag:server --operator=$USER
```
Add the HTTPS endpoint. In the machines console, open the svc:runner1 service and add tcp:443. Skip this and you’ll get “required ports are missing” even while the service advertises.

Serve:

tailscale serve --bg --service=svc:runner1 http://localhost:3000

Approve the service. Open the Services page, find the pending svc:runner1 advertisement under Service hosts, and click Approve. The service is inactive until you do.

run-kit is now at https://runner1.<tailnet>.ts.net.

Note: Tagging a node drops its user-identity association — user-based ACL grants stop applying. Make sure your ACLs grant the tag what it needs.

Tip: If you advertise services often, you can skip the manual approval in step 5. In the Access controls JSON editor, add an autoApprovers block as a top-level key (there’s no Visual editor control for service approval), then save — leave the existing grants block untouched:
"autoApprovers": {
  "services": {
    "svc:runner1": ["tag:server"]
  }
},

Advanced: Public access (Funnel)

To expose run-kit to the public internet (not just your tailnet):

tailscale funnel --bg http://localhost:3000

Warning: Funnel makes your terminal relay publicly accessible. Only use this if you understand the security implications.