# Your first machine

> Press Connect a machine, paste the one line it gives you into the box, and open it on your phone — with a picture of every screen you will meet.

Three steps, and one of them is a line you paste.

Have ready: a terminal on the machine — `ssh` to a Linux box, or Terminal on a
Mac you are sitting at — and a device you are already signed in to
[Tailscale](https://tailscale.com) on. Your phone is ideal.

**If the machine is a Mac**, Tailscale is an app you install yourself — the
one-liner will not put it on. Doing this first is fine; you can also paste
first, and the connect screen will send you to the App Store if the app is
missing.

1. Get [Tailscale from the App Store](https://apps.apple.com/app/tailscale/id1475387142)
   and open it — or, from Homebrew, `brew install --cask tailscale` then
   `open -a Tailscale`.
2. Sign in to the account that owns the network this machine should join —
   the same one your phone is on.
3. Click the Tailscale icon in the menu bar and **turn the switch on**, so
   the menu says Connected. An app that is installed but switched off is a
   machine that never gets an address.

## 1. Press *Connect a machine*

[Sign in](https://beafk.app/login?return_to=/machines/connect). The first screen is your
machines, and it is empty. Press [Connect a machine](https://beafk.app/machines/connect).

![the price before anything else: the seven-day trial, nothing to pay, and one button to a code](https://beafk.app/docs-shots/connect-cost.webp)

You see the figure before you are given anything to run. Your first machine is
the seven-day trial, so that figure is nothing and there is no card — the button
under it reads **Get a code · nothing to pay**. Later machines are quoted
exactly, and the number on that button is the number your card is charged. See [what it costs](https://beafk.app/docs/what-it-costs.md).

## 2. Paste the line into the machine

![a connect code, the countdown beside it, and the one line to run on the machine](https://beafk.app/docs-shots/connect-code.webp)

You now have a **connect code** with ten minutes on the clock, and under it,
headed **Run this on the machine**, one line.

**The line is what you copy** — press it, anywhere along it; the whole line is
the button and it goes to your clipboard. The code is already inside it, which
is why the code itself has nothing to press: it is there to be read while you
wait, and to be typed by hand on the rare machine your clipboard cannot reach.

Paste the line into the terminal on the machine. This screen watches for it.
If you close the tab, the machine's row in your list is the way back — it
reads as *installing* and opens the same screen.

That one line downloads beafk from this site, installs it, and uses the
code. The code is used as soon as the machine exists, before the long part
of the install, so the ten minutes cannot run out halfway through.

That one line is the whole of what the screen hands over. If the machine
already has beafk on it — you are reconnecting one, or moving it to another
workspace — `sudo beafk cloud connect <cabinet> --code <code>` uses the code
and does nothing else. The screen does not print that second line.

If the ten minutes run out, press **New code**. That is free, and it does not
buy a second seat.

On a Mac the pasted line keeps its `sudo`: it is accepted and handed straight
back to you, because the install belongs to the person logged in and not to
root.

Running it twice is safe. It never moves a machine that is already set up.

### What the screen shows while it installs

![the install as four named parts, current step Tailscale is on the machine, Open waiting on an address](https://beafk.app/docs-shots/connect-installing.webp)

The screen does not jump to Open the moment the code is used. It shows four
parts, all open:

- **beafk lands on it** — the binary, an account to run as, the service on
  loopback.
- **it becomes yours** — this workspace, then **Tailscale is on the machine**.
- **the agents go on** — the packages a machine needs, then each CLI you
  picked.
- **it says who it is** — its own row, and the fingerprint you will compare.

On Linux the walk's current row during that package step is **Tailscale is on
the machine**. That row is the package, not a login: apt from Tailscale's
signed repo, and the daemon. Login is a second screen, after the walk
succeeds.

A failed step stays coral under that row, with one sentence. A machine that
has gone quiet for two minutes says so on the step it stopped at, and offers
the same line again — every script skips what is already there.

The seat is already paid (or the trial has already started) from the moment
the machine took the code. Close the terminal and the rest keeps going.

**Open** waits until the machine has an address. Until then the slot says
*No address yet*, or *Waiting for certificate* while Tailscale issues the
first one — usually under a minute, nothing to run.

### It stops once, to let you into your own network

![Tailscale waiting for a yes — the same login the terminal printed, as a press on this screen](https://beafk.app/docs-shots/connect-login.webp)

After the walk succeeds, a second screen — not a row of the walk. The title
is **Tailscale is waiting for you to say yes**. The machine has already run
`tailscale up`, and Tailscale has answered with a link. Tap **Open the
Tailscale login**. On a phone the QR is behind **Signed in to Tailscale on
your phone? Scan it instead**; on a desk the square is already there. The
install waits while you do.

You are not asked for a key, and there is nothing to make beforehand. Whoever
opens that link is the network the machine joins, so open it yourself. Your
Tailscale password never reaches us. The link can appear on this screen so
you do not have to copy it from the terminal — it is held in memory for the
few minutes the login is open, never written down, and only somebody signed
in to your workspace is shown it.

If your tailnet has **device approval** turned on, the machine joins and then
waits for an admin. The terminal says so rather than sitting there.

On a Mac whose Tailscale app is installed but the switch is off, this is not a
login: the card says Tailscale is switched off. Turn the switch on in the
menu bar so it says Connected. beafk notices, and the cabinet updates at
once. Do not run `sudo` Tailscale on a Mac — root cannot see the app.

#### If the Mac does not have the app yet

![Get Tailscale on the App Store, Homebrew folded underneath](https://beafk.app/docs-shots/connect-mac.webp)

After the walk, if Tailscale.app is missing, the screen is a mint **Get
Tailscale on the App Store** — that opens
[the App Store listing](https://apps.apple.com/app/tailscale/id1475387142) —
with Homebrew under a fold labelled **or Homebrew, from the terminal you
just used**: `brew install --cask tailscale`, then `open -a Tailscale`. Sign
in, **turn the switch on**. The cabinet notices; there is nothing to
refresh.

#### If Linux never got Tailscale

![Tailscale is not installed — sudo beafk net tailscale, then the login](https://beafk.app/docs-shots/connect-blocked.webp)

If the package failed during the walk, the second screen is titled
**Tailscale is not installed**. It shows `sudo beafk net tailscale` first;
once that has put Tailscale on the box, the login and the QR follow. The
cabinet learns as soon as the machine has an address.

#### Switch off key expiry, or it goes quiet in 180 days

A machine you sign in this way belongs to your Tailscale account, and Tailscale
expires an account's machines on a schedule — 180 days by default. When that
happens the address simply stops answering: nothing is broken, nothing is
logged, and there is nothing on the machine to see.

Open its row at
[login.tailscale.com/admin/machines](https://login.tailscale.com/admin/machines)
and turn key expiry off for it. One press, once, and it is the difference
between a machine that sits there and answers and one that disappears in the
spring.

#### If you cannot finish the login on that device

Press **k** at the login screen and paste an auth key instead. It is the same
join by a different door, and it is there for one real case: a Tailscale
account behind a company sign-in you cannot complete from the machine in front
of you.

Make the key at
[login.tailscale.com/admin/settings/keys](https://login.tailscale.com/admin/settings/keys)
→ **Generate auth key**. The prompt prints the switches that matter and two of
them decide whether you keep the machine:

- **Ephemeral** — **off**. An ephemeral machine is removed from the tailnet the
  moment it goes offline, and your machine goes offline every time it reboots —
  taking its address, and your way in, with it.
- **Pre-approved** — on, if your tailnet has device approval turned on.
  Otherwise the machine joins and waits for an admin with no address, which
  both the terminal and the screen read as a machine that never came up.

The key is typed on the machine with the echo off, spent once, and kept
nowhere. It does not reach beafk, here or there.

Two more are switched on for the **whole tailnet** rather than on the key, and
no machine can turn them on for itself: **MagicDNS** and **HTTPS certificates**,
at [login.tailscale.com/admin/dns](https://login.tailscale.com/admin/dns). They
are what give the machine a name and a certificate. Without them it joins
perfectly well and has no https address — and a browser will not talk to a panel
over plain http, so step 3 waits on a certificate that never comes. Running
`sudo beafk net tailscale` on the machine (no `sudo` on a Mac) says which of
the two it is, and prints the address to turn it on.

Press ⏎ at the login to skip the whole thing if you would rather do Tailscale
yourself, and run `sudo beafk net tailscale` later. On a Mac, drop the `sudo`
— root there cannot see Tailscale's app.

## 3. Check the fingerprint, then open it

![the machine has answered: five green rows, its fingerprint, and a button that opens it](https://beafk.app/docs-shots/connect-open.webp)

When the machine has an address, the screen you left — or the row that
brought you back — shows five rows about the machine and a `SHA256:…`
fingerprint, the machine's one true name, calculated from a key it made for
itself and has never shown anybody. We check the signature on the code, so we
know that **this machine and no other** spent it, without you typing a
credential into a terminal.

**Your terminal printed the same line.** Compare them. If they differ, do not
open it. A machine belongs to exactly one workspace by fingerprint and not by
hostname: an address can be wrong, the fingerprint cannot.

Then press **Open**, which carries the machine's own name on it. On your phone,
install Tailscale first, sign in to the same network, and **turn it on** the
same way — the switch in the app, not merely an account. Then open beafk cloud
there, sign in, and press **Open** on that machine — or tap its card on the
fleet. What you land on is
[the home screen](https://beafk.app/docs/the-home-screen.md).

Your browser gets a short-lived certificate and opens the machine **directly**
— the chat, the files and the terminal never come through us. There is
nothing to pair; see
[how your phone reaches it](https://beafk.app/docs/reaching-your-machine.md).

## Then what

Sign an agent in — [signing an agent in](https://beafk.app/docs/signing-an-agent-in.md) — pick
a folder, and say something to it.

If a step did not go the way this page says,
[when something is wrong](https://beafk.app/docs/when-something-is-wrong.md) is the list of what
actually goes wrong and what to do about each one.

---

beafk documentation · Your first machine · https://beafk.app/docs/your-first-machine

In this section:
- Your first machine — https://beafk.app/docs/your-first-machine.md (this page)
- How your phone reaches it — https://beafk.app/docs/reaching-your-machine.md
- Signing an agent in — https://beafk.app/docs/signing-an-agent-in.md
- A chat — https://beafk.app/docs/a-chat.md

Every page, one line each: https://beafk.app/docs/llms.txt
All of it in one file: https://beafk.app/docs/llms-full.txt