The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
Add a Linux one-line installer and a paste-back path for headless beacon login
Claudeda390d88e4b6
diff --git a/CLAUDE.md b/CLAUDE.mdindex 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.mdindex 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.yamlindex 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.shfooter: |## 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 DownloadDownload 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.goindex 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.InspectaccountRevoke = account.RevokeaccountNow = 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 errdiff --git a/cli/beacon/internal/account/login.go b/cli/beacon/internal/account/login.goindex b4975f06..77df7104 100644--- a/cli/beacon/internal/account/login.go+++ b/cli/beacon/internal/account/login.go@@ -1,6 +1,7 @@package accountimport (+ "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 := trueif 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 = falsefmt.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.goindex 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.goindex 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.goindex 55548758..ae7403d8 100644--- a/cli/beacon/internal/auth/server.go+++ b/cli/beacon/internal/auth/server.go@@ -2,10 +2,12 @@ package authimport ("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.mdxindex 92962d2b..f3a3d65a 100644--- a/docs/cli/account-auth.mdx+++ b/docs/cli/account-auth.mdx@@ -23,33 +23,49 @@ beacon logoutbeacon 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):```bashbeacon 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:```textNo 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.mdxindex 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 firSee 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.mdxindex 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 reSee 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.mdxindex 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 managerIf 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.shnew file mode 100755index 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"