Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Add a Linux one-line installer and a paste-back path for headless beacon login

Claudeda390d88e4b6
diff --git a/CLAUDE.md b/CLAUDE.md
index 484bfc25..1aa48779 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -347,7 +347,7 @@ docker run --rm --platform linux/amd64 homebrew/brew sh -c \
```
The release should include the five GoReleaser CLI archives (four `.tar.gz` plus
-`beacon_<version>_windows_amd64.zip`), `checksums.txt`, `threat-rules.tar.gz`,
+`beacon_<version>_windows_amd64.zip`), `checksums.txt`, `threat-rules.tar.gz`, `install.sh` (the Linux one-line installer from `packaging/linux/install.sh`),
`BeaconEndpointAgent-<version>-arm64.pkg`, its `.sha256`, `update-manifest.json`,
and `BeaconEndpointAgent-<version>-x64.msi` with its `.sha256`.
diff --git a/README.md b/README.md
index 33c451af..4fa9a008 100644
--- a/README.md
+++ b/README.md
@@ -69,17 +69,13 @@ beacon endpoint install
<details>
<summary><strong>Linux</strong></summary>
-Download the `.deb` or `.rpm` from the [latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest).
+Install the latest `.deb` or `.rpm` for your distribution and architecture (Debian, Ubuntu, Fedora, RHEL, Rocky, Alma):
```bash
-sudo apt install ./beacon_<version>_linux_amd64.deb
+curl -fsSL https://github.com/asymptote-labs/agent-beacon/releases/latest/download/install.sh | bash
```
-or:
-
-```bash
-sudo dnf install ./beacon_<version>_linux_amd64.rpm
-```
+The [installer](packaging/linux/install.sh) verifies the package against the release checksums. To install by hand, download the package from the [latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest) into a directory APT can read (not your home directory, or APT ends with a harmless `Permission denied` notice) and run `sudo apt install ./beacon_<version>_linux_amd64.deb` or `sudo dnf install ./beacon_<version>_linux_amd64.rpm`.
</details>
diff --git a/cli/beacon/.goreleaser.yaml b/cli/beacon/.goreleaser.yaml
index 7a3275f6..4135c0fc 100644
--- a/cli/beacon/.goreleaser.yaml
+++ b/cli/beacon/.goreleaser.yaml
@@ -292,6 +292,8 @@ release:
# The threat-rule pack ships as a separate asset, not embedded in the binary,
# so the rule corpus can grow without enlarging `beacon`.
- glob: ./release-rules/threat-rules.tar.gz
+ # The Linux one-line installer, served from releases/latest/download/install.sh.
+ - glob: ../../packaging/linux/install.sh
footer: |
## Installation
@@ -301,6 +303,11 @@ release:
brew install beacon
```
+ ### Linux (Debian, Ubuntu, Fedora, RHEL)
+ ```bash
+ curl -fsSL https://github.com/asymptote-labs/agent-beacon/releases/download/v{{.Version}}/install.sh | BEACON_VERSION={{.Version}} bash
+ ```
+
### Manual Download
Download the appropriate archive for your platform from the assets below, extract it, and add the binary to your PATH.
diff --git a/cli/beacon/cmd/account.go b/cli/beacon/cmd/account.go
index 4872d2d3..2238f8d1 100644
--- a/cli/beacon/cmd/account.go
+++ b/cli/beacon/cmd/account.go
@@ -5,7 +5,9 @@ import (
"encoding/json"
"errors"
"fmt"
+ "io"
"net/http"
+ "os"
"strings"
"time"
@@ -29,6 +31,14 @@ var (
accountInspect = account.Inspect
accountRevoke = account.Revoke
accountNow = time.Now
+ // accountPasteInput is where `beacon login` reads a pasted callback address.
+ // Only a terminal qualifies: piped stdin is not a person who can paste.
+ accountPasteInput = func(cmd *cobra.Command) io.Reader {
+ if !isTerminal(os.Stdin) {
+ return nil
+ }
+ return cmd.InOrStdin()
+ }
)
var loginCmd = &cobra.Command{
@@ -54,7 +64,8 @@ var whoamiCmd = &cobra.Command{
func init() {
loginCmd.Flags().StringVar(&accountOpts.baseURL, "auth-url", "", "Beacon authentication URL (defaults to "+account.DefaultBaseURL+", or "+account.BaseURLEnv+")")
- loginCmd.Flags().BoolVar(&accountOpts.noBrowser, "no-browser", false, "Print the sign-in URL instead of opening a browser")
+ loginCmd.Flags().BoolVar(&accountOpts.noBrowser, "no-browser", false, "Print the sign-in URL instead of opening a browser; on a remote machine, finish by pasting the address the browser was sent to")
+ loginCmd.Flags().BoolVar(&accountOpts.noBrowser, "headless", false, "Alias for --no-browser, for signing in on a remote or headless machine")
for _, command := range []*cobra.Command{loginCmd, logoutCmd, whoamiCmd} {
command.Flags().BoolVar(&accountOpts.json, "json", false, "Print machine-readable JSON")
rootCmd.AddCommand(command)
@@ -67,11 +78,12 @@ func runLogin(cmd *cobra.Command, args []string) error {
flowOut = cmd.ErrOrStderr()
}
session, err := accountLogin(commandContext(cmd), account.LoginOptions{
- BaseURL: accountOpts.baseURL,
- Version: version.GetVersion(),
- NoBrowser: accountOpts.noBrowser,
- Out: flowOut,
- Now: accountNow,
+ BaseURL: accountOpts.baseURL,
+ Version: version.GetVersion(),
+ NoBrowser: accountOpts.noBrowser,
+ Out: flowOut,
+ Now: accountNow,
+ PasteInput: accountPasteInput(cmd),
})
if err != nil {
return err
diff --git a/cli/beacon/internal/account/login.go b/cli/beacon/internal/account/login.go
index b4975f06..77df7104 100644
--- a/cli/beacon/internal/account/login.go
+++ b/cli/beacon/internal/account/login.go
@@ -1,6 +1,7 @@
package account
import (
+ "bufio"
"bytes"
"context"
"encoding/json"
@@ -50,6 +51,11 @@ type LoginOptions struct {
// When it is set, Login writes nothing to Out: a caller rendering its own UI
// owns the screen, and stray writes would corrupt an alternate-screen frame.
OnPrompt func(LoginPrompt)
+ // PasteInput, when set, lets the user finish signing in from another computer
+ // by pasting the callback address the remote browser could not load. It is read
+ // only when Login prints the URL (NoBrowser, or the browser could not open) and
+ // OnPrompt is unset, so it never competes with a caller that owns the terminal.
+ PasteInput io.Reader
}
// LoginPrompt is everything a user needs in order to finish signing in.
@@ -188,8 +194,13 @@ func Login(ctx context.Context, opts LoginOptions) (*Session, error) {
report = func(LoginPrompt) {}
}
report(LoginPrompt{URL: loginURL, WillOpen: !opts.NoBrowser, Timeout: timeout, Port: port})
+ paste := opts.PasteInput
+ if opts.OnPrompt != nil {
+ paste = nil
+ }
+ urlShown := true
if opts.NoBrowser {
- printLoginURL(out, loginURL, port)
+ printLoginURL(out, loginURL, port, paste != nil)
} else if err := openBrowser(loginURL); err != nil {
report(LoginPrompt{URL: loginURL, BrowserErr: err, Timeout: timeout, Port: port})
if errors.Is(err, auth.ErrNoDisplay) {
@@ -201,13 +212,19 @@ func Login(ctx context.Context, opts LoginOptions) (*Session, error) {
} else {
fmt.Fprintln(out, "Could not open a browser automatically.")
}
- printLoginURL(out, loginURL, port)
+ printLoginURL(out, loginURL, port, paste != nil)
} else {
+ urlShown = false
fmt.Fprintf(out, "Opening %s in your browser...\n", baseURL)
}
fmt.Fprintln(out, "Waiting for Beacon sign-in...")
- result, err := callback.WaitContext(ctx, timeout)
+ waitCtx, stopWaiting := context.WithCancel(ctx)
+ defer stopWaiting()
+ if paste != nil && urlShown {
+ go readPastedCallback(waitCtx, paste, out, callback)
+ }
+ result, err := callback.WaitContext(waitCtx, timeout)
if err != nil {
return nil, err
}
@@ -281,11 +298,54 @@ func ResolveBaseURL(flagValue string) string {
}
// printLoginURL shows the sign-in URL and how to use it from another computer.
-func printLoginURL(out io.Writer, loginURL string, port int) {
+func printLoginURL(out io.Writer, loginURL string, port int, acceptsPaste bool) {
fmt.Fprintf(out, "Open this URL to sign in to Beacon:\n%s\n", loginURL)
+ if acceptsPaste {
+ fmt.Fprintln(out, "Signing in from another computer? After you approve, that browser cannot reach this")
+ fmt.Fprintln(out, "machine and shows a connection error. Copy the full address from its address bar")
+ fmt.Fprintln(out, "(it starts with http://127.0.0.1) and paste it here, then press Enter.")
+ fmt.Fprintf(out, "Or forward the port over SSH before opening the URL: %s\n", SSHForwardCommand(port))
+ return
+ }
fmt.Fprintf(out, "From another computer over SSH, forward the port first: %s\n", SSHForwardCommand(port))
}
+// readPastedCallback feeds lines from in to the callback server until one
+// completes the sign-in or ctx ends. A line that is not this sign-in's callback
+// is reported and the user can paste again.
+//
+// A read from a terminal cannot be interrupted, so after Login returns this
+// goroutine may stay parked on the next line until the process exits; ctx keeps
+// it from writing or acting on anything it reads after that.
+func readPastedCallback(ctx context.Context, in io.Reader, out io.Writer, callback *auth.CallbackServer) {
+ scanner := bufio.NewScanner(in)
+ scanner.Buffer(make([]byte, 0, 4096), 64*1024)
+ for scanner.Scan() {
+ if ctx.Err() != nil {
+ return
+ }
+ line := strings.TrimSpace(scanner.Text())
+ if line == "" {
+ continue
+ }
+ err := callback.CompletePasted(ctx, line)
+ if err == nil || !errors.Is(err, auth.ErrInvalidPastedCallback) {
+ return
+ }
+ if ctx.Err() != nil {
+ return
+ }
+ fmt.Fprintf(out, "%s. Paste the address again, or press Ctrl+C to cancel.\n", capitalize(err.Error()))
+ }
+}
+
+func capitalize(msg string) string {
+ if msg == "" {
+ return msg
+ }
+ return strings.ToUpper(msg[:1]) + msg[1:]
+}
+
// SSHForwardCommand is the port forward that lets a browser on the SSH client finish a sign-in
// that redirects to port on this machine.
func SSHForwardCommand(port int) string {
diff --git a/cli/beacon/internal/account/login_test.go b/cli/beacon/internal/account/login_test.go
index 94b0eb67..57e86320 100644
--- a/cli/beacon/internal/account/login_test.go
+++ b/cli/beacon/internal/account/login_test.go
@@ -181,3 +181,89 @@ func TestResolveBaseURLPrecedence(t *testing.T) {
t.Fatalf("env URL = %q", got)
}
}
+
+// Signing in to a remote machine from a local browser: the redirect to 127.0.0.1 cannot reach the
+// CLI, so the person pastes the address the browser was sent to. A wrong paste is reported and
+// the next line still completes the sign-in.
+func TestLoginNoBrowserCompletesFromAPastedAddress(t *testing.T) {
+ service := newFakeAuthService(t)
+ pasteReader, pasteWriter := io.Pipe()
+ defer pasteWriter.Close()
+
+ var out syncBuffer
+ done := make(chan error, 1)
+ go func() {
+ _, err := Login(context.Background(), LoginOptions{
+ BaseURL: service.server.URL,
+ NoBrowser: true,
+ OpenBrowser: func(string) error {
+ t.Error("browser must not open with NoBrowser")
+ return nil
+ },
+ HTTPClient: service.server.Client(),
+ Out: &out,
+ Timeout: 5 * time.Second,
+ PasteInput: pasteReader,
+ })
+ done <- err
+ }()
+
+ var loginURL string
+ deadline := time.Now().Add(3 * time.Second)
+ for loginURL == "" && time.Now().Before(deadline) {
+ for _, line := range strings.Split(out.String(), "\n") {
+ if strings.HasPrefix(line, service.server.URL+LoginPagePath) {
+ loginURL = line
+ }
+ }
+ time.Sleep(10 * time.Millisecond)
+ }
+ if loginURL == "" {
+ t.Fatalf("login never printed its URL:\n%s", out.String())
+ }
+ parsed, err := url.Parse(loginURL)
+ if err != nil {
+ t.Fatal(err)
+ }
+ state, port := parsed.Query().Get("state"), parsed.Query().Get("port")
+
+ fmt.Fprintf(pasteWriter, "http://127.0.0.1:%s/callback?state=wrong&exchange_code=nope\n", port)
+ fmt.Fprintf(pasteWriter, "http://127.0.0.1:%s/callback?state=%s&exchange_code=code-123\n", port, state)
+
+ select {
+ case err := <-done:
+ if err != nil {
+ t.Fatalf("Login: %v\n%s", err, out.String())
+ }
+ case <-time.After(5 * time.Second):
+ t.Fatalf("Login did not finish from the pasted address:\n%s", out.String())
+ }
+ text := out.String()
+ for _, want := range []string{"paste it here", "different sign-in", "ssh -L "} {
+ if !strings.Contains(text, want) {
+ t.Fatalf("login output is missing %q:\n%s", want, text)
+ }
+ }
+ service.mu.Lock()
+ defer service.mu.Unlock()
+ if service.exchange["exchange_code"] != "code-123" || service.exchange["code_verifier"] == "" {
+ t.Fatalf("exchange payload = %#v", service.exchange)
+ }
+}
+
+type syncBuffer struct {
+ mu sync.Mutex
+ buf strings.Builder
+}
+
+func (b *syncBuffer) Write(p []byte) (int, error) {
+ b.mu.Lock()
+ defer b.mu.Unlock()
+ return b.buf.Write(p)
+}
+
+func (b *syncBuffer) String() string {
+ b.mu.Lock()
+ defer b.mu.Unlock()
+ return b.buf.String()
+}
diff --git a/cli/beacon/internal/auth/auth_test.go b/cli/beacon/internal/auth/auth_test.go
index 48f9f17c..c5bafdcf 100644
--- a/cli/beacon/internal/auth/auth_test.go
+++ b/cli/beacon/internal/auth/auth_test.go
@@ -250,3 +250,72 @@ func TestSuccessPageIsStyledAndPointsAtTheTerminal(t *testing.T) {
t.Fatalf("the page must not fetch anything:\n%s", page)
}
}
+
+// On a remote machine the browser runs elsewhere and cannot load the 127.0.0.1 redirect, so the
+// person pastes that address back into the terminal. Anything that is not this sign-in's callback
+// must leave the flow open for another try; the real address completes it exactly once.
+func TestCallbackServerCompletesFromAPastedAddress(t *testing.T) {
+ var gotCode, gotState, gotVerifier string
+ calls := 0
+ exchange := func(_ context.Context, code, state, verifier string) error {
+ calls++
+ gotCode, gotState, gotVerifier = code, state, verifier
+ return nil
+ }
+ cs, err := NewCallbackServer("state-abc", "verifier-xyz", exchange, time.Second)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer cs.Shutdown()
+
+ for _, bad := range []string{
+ "",
+ "http://127.0.0.1:43121/callback?state=other&exchange_code=c",
+ "http://127.0.0.1:43121/callback?state=state-abc",
+ "some words that are not a code",
+ } {
+ if err := cs.CompletePasted(context.Background(), bad); !errors.Is(err, ErrInvalidPastedCallback) {
+ t.Fatalf("CompletePasted(%q) = %v, want ErrInvalidPastedCallback", bad, err)
+ }
+ }
+ if calls != 0 {
+ t.Fatalf("invalid input ran the exchange %d times", calls)
+ }
+
+ pasted := fmt.Sprintf(" 'http://127.0.0.1:%d/callback?state=state-abc&exchange_code=code-123'\n", cs.Port())
+ if err := cs.CompletePasted(context.Background(), pasted); err != nil {
+ t.Fatalf("CompletePasted: %v", err)
+ }
+ if gotCode != "code-123" || gotState != "state-abc" || gotVerifier != "verifier-xyz" {
+ t.Fatalf("exchange got code=%q state=%q verifier=%q", gotCode, gotState, gotVerifier)
+ }
+ result, err := cs.Wait(time.Second)
+ if err != nil || result.Error != "" || result.State != "state-abc" {
+ t.Fatalf("Wait = %#v, %v", result, err)
+ }
+ if err := cs.CompletePasted(context.Background(), pasted); err == nil || errors.Is(err, ErrInvalidPastedCallback) {
+ t.Fatalf("second paste = %v, want an already-finished error", err)
+ }
+ if calls != 1 {
+ t.Fatalf("exchange ran %d times, want 1", calls)
+ }
+}
+
+// A page that shows the exchange code on its own, rather than redirecting, can be pasted as is.
+func TestCallbackServerAcceptsABarePastedCode(t *testing.T) {
+ var gotCode, gotState string
+ cs, err := NewCallbackServer("state-abc", "verifier", func(_ context.Context, code, state, _ string) error {
+ gotCode, gotState = code, state
+ return nil
+ }, time.Second)
+ if err != nil {
+ t.Fatal(err)
+ }
+ defer cs.Shutdown()
+ if err := cs.CompletePasted(context.Background(), "code-456"); err != nil {
+ t.Fatalf("CompletePasted: %v", err)
+ }
+ if gotCode != "code-456" || gotState != "state-abc" {
+ t.Fatalf("exchange got code=%q state=%q", gotCode, gotState)
+ }
+}
diff --git a/cli/beacon/internal/auth/server.go b/cli/beacon/internal/auth/server.go
index 55548758..ae7403d8 100644
--- a/cli/beacon/internal/auth/server.go
+++ b/cli/beacon/internal/auth/server.go
@@ -2,10 +2,12 @@ package auth
import (
"context"
+ "errors"
"fmt"
"html"
"net"
"net/http"
+ "net/url"
"strings"
"sync"
"time"
@@ -172,6 +174,61 @@ func (cs *CallbackServer) handleCallback(w http.ResponseWriter, r *http.Request)
cs.sendResponse(w, true, "")
}
+// ErrInvalidPastedCallback reports pasted text that is not a callback for this
+// sign-in. Nothing was consumed, so the caller can ask again.
+var ErrInvalidPastedCallback = errors.New("that is not the sign-in address for this terminal")
+
+// CompletePasted finishes the flow from text the user pasted instead of from a
+// browser request: the full callback address the browser failed to load
+// (http://127.0.0.1:<port>/callback?state=...&exchange_code=...), or the bare
+// exchange code.
+//
+// It exists for signing in on a remote or headless machine, where the browser
+// runs on another computer whose 127.0.0.1 is not this one. That is safe to
+// accept by hand because the exchange code is useless without the PKCE verifier,
+// which never leaves this process.
+//
+// Input that is not a callback for this sign-in returns an error wrapping
+// ErrInvalidPastedCallback and leaves the flow open. Any other error means the
+// flow ended, and Wait returns it too.
+func (cs *CallbackServer) CompletePasted(ctx context.Context, input string) error {
+ input = strings.Trim(strings.TrimSpace(input), `"'<>`)
+ if input == "" {
+ return fmt.Errorf("%w: nothing was pasted", ErrInvalidPastedCallback)
+ }
+ state, exchangeCode, errMsg := cs.state, input, ""
+ if strings.Contains(input, "://") || strings.ContainsAny(input, "?&=") {
+ parsed, err := url.Parse(input)
+ if err != nil {
+ return fmt.Errorf("%w: %v", ErrInvalidPastedCallback, err)
+ }
+ query := parsed.Query()
+ state, exchangeCode, errMsg = query.Get("state"), query.Get("exchange_code"), query.Get("error")
+ if state != cs.state {
+ return fmt.Errorf("%w: it belongs to a different sign-in", ErrInvalidPastedCallback)
+ }
+ if exchangeCode == "" && errMsg == "" {
+ return fmt.Errorf("%w: it has no exchange code", ErrInvalidPastedCallback)
+ }
+ } else if strings.ContainsAny(input, " \t/") {
+ return fmt.Errorf("%w: paste the whole address from the browser's address bar", ErrInvalidPastedCallback)
+ }
+ if !cs.reserveCompletion() {
+ return errors.New("sign-in already finished")
+ }
+ if errMsg != "" {
+ cs.resultCh <- &CallbackResult{Error: errMsg}
+ return errors.New(errMsg)
+ }
+ if err := cs.exchange(ctx, exchangeCode, state, cs.codeVerifier); err != nil {
+ message := fmt.Sprintf("failed to exchange code: %v", err)
+ cs.resultCh <- &CallbackResult{Error: message}
+ return errors.New(message)
+ }
+ cs.resultCh <- &CallbackResult{State: state}
+ return nil
+}
+
func (cs *CallbackServer) finishCallback(w http.ResponseWriter, result *CallbackResult, success bool, errorMsg string) {
if !cs.reserveCompletion() {
cs.sendResponse(w, false, "Callback already handled")
diff --git a/docs/cli/account-auth.mdx b/docs/cli/account-auth.mdx
index 92962d2b..f3a3d65a 100644
--- a/docs/cli/account-auth.mdx
+++ b/docs/cli/account-auth.mdx
@@ -23,33 +23,49 @@ beacon logout
beacon login
```
-For a terminal that cannot open a browser automatically:
+For a terminal that cannot open a browser automatically, or a remote or headless
+machine (`--headless` is the same flag):
```bash
beacon login --no-browser
```
-This is still a loopback-callback PKCE flow, not a device-code flow. Open the URL
-in a browser that can reach the same machine's callback listener. For a remote SSH
-session, use a browser on the remote host or forward the callback port shown in
-the printed URL; opening it on an unrelated workstation without port forwarding
-redirects to that workstation's localhost and cannot complete the remote login.
+This is still a loopback-callback PKCE flow, not a device-code flow: after you
+approve, beacon.sh sends the browser to `http://127.0.0.1:<port>/callback` on the
+machine running the CLI.
On Linux, `beacon login` does not try to open a browser when there is no display
(`DISPLAY` and `WAYLAND_DISPLAY` unset) or in an SSH session. It says so, prints the
-URL and the port forward to run, and waits:
+URL, and waits:
```text
No browser can be opened on this machine: this is an SSH session.
Sign-in finishes when beacon.sh redirects a browser back to this machine.
Open this URL to sign in to Beacon:
https://beacon.sh/cli/auth?port=43121&state=...
-From another computer over SSH, forward the port first: ssh -L 43121:127.0.0.1:43121 <this machine>
+Signing in from another computer? After you approve, that browser cannot reach this
+machine and shows a connection error. Copy the full address from its address bar
+(it starts with http://127.0.0.1) and paste it here, then press Enter.
+Or forward the port over SSH before opening the URL: ssh -L 43121:127.0.0.1:43121 <this machine>
Waiting for Beacon sign-in...
```
-Run the `ssh -L` command in a second terminal on your own computer, then open the URL
-there. The port changes on every attempt.
+### Signing in to a remote machine
+
+Open the URL in the browser on your own computer and approve. That browser then
+tries to load `http://127.0.0.1:<port>/callback?...`, which is your computer rather
+than the remote one, so the page fails to load. Copy the whole address from the
+address bar, paste it into the waiting terminal, and press Enter. The CLI checks that
+the address belongs to this sign-in, redeems the one-time exchange code, and
+finishes. An address from another attempt is rejected and you can paste again.
+
+Pasting the address is safe for the same reason the loopback redirect is: the
+exchange code is single use and is worthless without the PKCE verifier, which only
+the waiting CLI holds.
+
+Alternatively, run the printed `ssh -L` command in a second terminal on your own
+computer before opening the URL, and the redirect reaches the remote CLI directly.
+The port changes on every attempt.
The session is stored at `~/.beacon/auth/session.json` in a `0700` directory with file mode `0600`. Human and JSON command output never includes the access token. Tokens expire rather than refreshing indefinitely; run `beacon login` again after expiry.
diff --git a/docs/get-started/quickstart.mdx b/docs/get-started/quickstart.mdx
index ef71d5ad..9fc4ce5e 100644
--- a/docs/get-started/quickstart.mdx
+++ b/docs/get-started/quickstart.mdx
@@ -22,19 +22,13 @@ description: "Install Beacon, choose where your data lives, and capture your fir
See the [Windows install guide](/platforms/windows) for more options.
</Tab>
<Tab title="Linux">
- Install Beacon using the package for your environment:
+ Install the latest `.deb` or `.rpm` for your distribution and architecture:
- <CodeGroup>
- ```bash title="Debian, Ubuntu"
- sudo apt install ./beacon_<version>_linux_amd64.deb
- ```
-
- ```bash title="Fedora, RHEL, Rocky, Alma"
- sudo dnf install ./beacon_<version>_linux_amd64.rpm
- ```
- </CodeGroup>
+ ```bash
+ curl -fsSL https://github.com/asymptote-labs/agent-beacon/releases/latest/download/install.sh | bash
+ ```
- Replace `amd64` with `arm64` on ARM systems. See the [Linux install guide](/platforms/linux) for more options.
+ The installer verifies the package against the release checksums before installing it. See the [Linux install guide](/platforms/linux) for manual package, tarball, and rootless installs.
</Tab>
</Tabs>
diff --git a/docs/index.mdx b/docs/index.mdx
index 9f458593..ab950219 100644
--- a/docs/index.mdx
+++ b/docs/index.mdx
@@ -40,21 +40,14 @@ Use Beacon to understand agent behavior, debug workflows, and explicitly turn re
See the [Windows install guide](/platforms/windows) for silent installation, checksum verification, and service management.
</Tab>
<Tab title="Linux">
- Download the `.deb` or `.rpm` for your architecture from the [latest release](https://github.com/asymptote-labs/agent-beacon/releases/latest):
+ Install the latest `.deb` or `.rpm` for your distribution and architecture:
- <CodeGroup>
- ```bash title="Debian, Ubuntu"
- sudo apt install ./beacon_<version>_linux_amd64.deb
- beacon version
- ```
-
- ```bash title="Fedora, RHEL, Rocky, Alma"
- sudo dnf install ./beacon_<version>_linux_amd64.rpm
- beacon version
- ```
- </CodeGroup>
+ ```bash
+ curl -fsSL https://github.com/asymptote-labs/agent-beacon/releases/latest/download/install.sh | bash
+ beacon version
+ ```
- Replace `amd64` with `arm64` on ARM systems. See the [Linux install guide](/platforms/linux) for rootless and tarball installation.
+ The installer verifies the package against the release checksums before installing it. See the [Linux install guide](/platforms/linux) for manual package, rootless, and tarball installation.
</Tab>
</Tabs>
diff --git a/docs/platforms/linux.mdx b/docs/platforms/linux.mdx
index 24625032..a9c694aa 100644
--- a/docs/platforms/linux.mdx
+++ b/docs/platforms/linux.mdx
@@ -9,14 +9,21 @@ Installing the package is the whole setup. It unpacks the binaries, performs the
## Install
-Run the block for your distribution. It downloads the latest package for your architecture, checks it against the release checksums, and installs it.
+```bash title="Debian, Ubuntu, Fedora, RHEL, Rocky, Alma"
+curl -fsSL https://github.com/asymptote-labs/agent-beacon/releases/latest/download/install.sh | bash
+```
+
+The [installer](https://github.com/asymptote-labs/agent-beacon/blob/main/packaging/linux/install.sh) downloads the latest `.deb` or `.rpm` for your architecture into a temporary directory, checks it against the release checksums, installs it with `apt-get` or `dnf`, and cleans up. Set `BEACON_VERSION=<version>` to install a specific release.
+
+To run the same steps yourself, use the block for your distribution:
<CodeGroup>
```bash title="Debian, Ubuntu"
VERSION="$(curl -fsSLI -o /dev/null -w '%{url_effective}' https://github.com/asymptote-labs/agent-beacon/releases/latest)"; VERSION="${VERSION##*/v}"
PKG="beacon_${VERSION}_linux_$(dpkg --print-architecture).deb"
BASE="https://github.com/asymptote-labs/agent-beacon/releases/download/v${VERSION}"
-curl -fsSLO "${BASE}/${PKG}" && curl -fsSLO "${BASE}/checksums.txt"
+DIR="$(mktemp -d /tmp/beacon-install.XXXXXXXX)" && chmod 0711 "$DIR" && cd "$DIR"
+curl -fsSLO "${BASE}/${PKG}" && curl -fsSLO "${BASE}/checksums.txt" && chmod 0644 "${PKG}"
grep " ${PKG}$" checksums.txt | sha256sum --check - && sudo apt install "./${PKG}"
```
@@ -32,6 +39,10 @@ grep " ${PKG}$" checksums.txt | sha256sum --check - && sudo dnf install "./${PK
`amd64` and `arm64` packages are published for both formats. The package puts `beacon` on your `PATH`, so every command below works by name.
+<Note>
+APT reads a local package as its unprivileged `_apt` user. If the `.deb` sits somewhere `_apt` cannot read, such as your home directory, the install still succeeds, but APT ends with `Download is performed unsandboxed as root` and `pkgAcquire::Run (13: Permission denied)`. That is a warning, not a failure, and there is nothing to repair; `beacon version` confirms the install. The installer and the Debian block above download into a readable directory under `/tmp` so the warning does not appear.
+</Note>
+
### Without root, or without a package manager
If you are not an administrator on the machine, or you would rather not touch system paths, use the tarball and install in user mode:
diff --git a/packaging/linux/install.sh b/packaging/linux/install.sh
new file mode 100755
index 00000000..eaa20fd4
--- /dev/null
+++ b/packaging/linux/install.sh
@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# Install the Beacon endpoint package on Linux.
+#
+# curl -fsSL https://github.com/asymptote-labs/agent-beacon/releases/latest/download/install.sh | bash
+#
+# Downloads the .deb or .rpm for this machine's architecture, checks it against
+# the release checksums.txt, and installs it with apt-get or dnf/yum so package
+# dependencies resolve. Set BEACON_VERSION (for example 1.3.24 or v1.3.24) to
+# install a specific release instead of the latest.
+#
+# The package is downloaded into a fresh directory under /tmp rather than the
+# working directory. APT reads a local package as its unprivileged _apt user; a
+# package in a home directory _apt cannot traverse still installs, but APT ends
+# with "pkgAcquire::Run (13: Permission denied)", which reads like a failure.
+set -euo pipefail
+
+repo="asymptote-labs/agent-beacon"
+
+fail() {
+ echo "beacon install: $*" >&2
+ exit 1
+}
+
+[[ "$(uname -s)" == Linux ]] || fail "this installer supports Linux only. See https://docs.asymptotelabs.ai for other platforms."
+
+case "$(uname -m)" in
+ x86_64 | amd64) arch=amd64 ;;
+ aarch64 | arm64) arch=arm64 ;;
+ *) fail "Beacon publishes Linux packages for amd64 and arm64, not $(uname -m)." ;;
+esac
+
+if command -v apt-get >/dev/null 2>&1 && command -v dpkg >/dev/null 2>&1; then
+ format=deb
+ installer=(apt-get install -y)
+elif command -v dnf >/dev/null 2>&1; then
+ format=rpm
+ installer=(dnf install -y)
+elif command -v yum >/dev/null 2>&1; then
+ format=rpm
+ installer=(yum install -y)
+else
+ fail "no apt-get, dnf, or yum found. Use the tarball install instead: https://docs.asymptotelabs.ai/platforms/linux"
+fi
+
+for program in curl sha256sum awk mktemp; do
+ command -v "$program" >/dev/null 2>&1 || fail "required command not found: $program"
+done
+
+if ((EUID == 0)); then
+ sudo=()
+else
+ command -v sudo >/dev/null 2>&1 || fail "installing the package needs root; rerun as root or install sudo."
+ sudo=(sudo)
+fi
+
+tag="${BEACON_VERSION:-}"
+if [[ -z "$tag" ]]; then
+ latest_url="$(curl -fsSLI -o /dev/null -w '%{url_effective}' "https://github.com/${repo}/releases/latest")"
+ tag="${latest_url##*/}"
+fi
+[[ "$tag" == v* ]] || tag="v${tag}"
+if [[ ! "$tag" =~ ^v[0-9]+\.[0-9]+\.[0-9]+([.-][0-9A-Za-z.-]+)?$ ]]; then
+ fail "could not determine which Beacon release to install (got '${tag}')."
+fi
+version="${tag#v}"
+package="beacon_${version}_linux_${arch}.${format}"
+base="https://github.com/${repo}/releases/download/${tag}"
+
+tmp="$(mktemp -d /tmp/beacon-install.XXXXXXXX)"
+trap 'rm -rf -- "$tmp"' EXIT
+
+echo "Installing Beacon ${tag} (${arch}, .${format})..."
+curl -fsSL "${base}/${package}" -o "${tmp}/${package}"
+curl -fsSL "${base}/checksums.txt" -o "${tmp}/checksums.txt"
+
+checksum="$(awk -v name="$package" '$2 == name { print $1 }' "${tmp}/checksums.txt")"
+[[ "$checksum" =~ ^[0-9a-fA-F]{64}$ ]] || fail "no unique SHA-256 checksum for ${package} in checksums.txt."
+(cd "$tmp" && printf '%s %s\n' "$checksum" "$package" | sha256sum --check --quiet -) || fail "checksum mismatch for ${package}."
+
+# Let APT's _apt user reach the package so it does not fall back to an
+# unsandboxed download and print a permission warning.
+chmod 0711 "$tmp"
+chmod 0644 "${tmp}/${package}"
+
+"${sudo[@]}" "${installer[@]}" "${tmp}/${package}"
+
+echo
+beacon version
+echo "Beacon installed. Check the endpoint with:"
+echo " beacon endpoint status --system"