# Secrun: let HackerGPT run commands on your own machine

Published: 2026-10-31 · By HackerGPT Team
Canonical: https://hackergpt.org/blog/secrun-run-commands-on-your-machine/

> Secrun is a small binary you download from a HackerGPT CTF session. While it runs, the commands the model chooses execute on your Linux or macOS machine, with your tools and your network. How to install it, approve it on macOS, and run it safely.

**TL;DR:** Secrun is a small binary you download from the **Commands** tab of a HackerGPT CTF session. While it runs on your Linux or macOS machine, the commands the model chooses execute there, with that machine's tools, network and disk, and every result lands in the folder you started it from. Put it in a new, empty folder, run `chmod +x secrun` and `./secrun`; on macOS, approve it once in **System Settings → Privacy & Security → Security → Open Anyway**.

This guide is for CTF players and learners who use [CTF Mode](https://hackergpt.org/features/ctf-mode/) and want the model to work in a real terminal instead of only reasoning about one. By the end you will have Secrun installed on Linux or macOS, approved by Gatekeeper, and running in a folder of its own, and you will know what it can and cannot do on your machine. For what the release adds to CTF Mode as a whole, see [the Secrun announcement](https://hackergpt.org/blog/hackergpt-secrun-release/).

As with everything on this site: point it only at a CTF you are entered in, [CyberGym](https://cybergym.hackergpt.app), your own site, or a target you have written permission to test. [The rules of legal hacking](https://hackergpt.org/legal-hacking/) cover what counts as permission.

## What is Secrun, and why use it in a CTF?

Secrun connects your HackerGPT CTF session to a machine you control, so the commands the model decides to run actually run, on your machine, and come back with real output. A CTF session already has a Browser, Network and HTTP view of the target; Secrun adds a shell.

That changes three things while you work:

- **Real tools, real output.** The model can run the scanners, fuzzers and scripts installed on your machine and read what they actually printed, instead of describing what they would probably print. Its next step is based on the target's real behaviour.
- **Your network.** Commands go out from your machine's network. If the challenge or lab is only reachable from there, for example through a VPN you connected for the event or a lab VM on your own network, that is where the model can reach it from.
- **Results you keep.** Scan output, downloaded files and command logs are written to the folder you started Secrun in, so after the session you still have every file to read, rerun or write up.

You still see each step and the reasoning behind it, as in the rest of CTF Mode. The difference is that the step is executed, not imagined.

![The Commands tab in a HackerGPT CTF session: platform buttons, the Download secrun button and the three setup steps](https://hackergpt.org/blog/secrun-run-commands-on-your-machine/commands-tab.webp) *The Commands tab of a CTF session. Pick your platform, download, then follow the three steps.*

## How does Secrun work?

Secrun runs the commands the model sends from your session, and nothing else. Each one is executed with `bash` on your machine, and its output goes back to the session so the model can decide what to do next.

![Secrun loop: the CTF session sends a command, secrun runs it on your machine, output returns and results stay in your folder](https://hackergpt.org/blog/secrun-run-commands-on-your-machine/how-secrun-works.webp) *The model decides what to run; secrun runs exactly that on your machine and keeps every result in the engagement directory.*

A few properties follow from that design, and they are worth knowing before you start it:

- **It is tied to you.** The binary you download carries your token and a client certificate. That is how the session knows the machine on the other end is yours. It also means **the file is a credential**: do not share it, upload it or commit it to a repository.
- **One build at a time.** Downloading Secrun again replaces your build, and the previous one stops working. If you think a copy has leaked, downloading a fresh one is how you cut it off.
- **The folder is the workspace.** The directory you start it in becomes the session's workspace. Two sessions sharing one directory overwrite each other's scan output, so use one fresh directory per engagement.
- **You decide its privileges.** Started as `./secrun`, it runs commands as your user and cannot install packages. Started as `sudo ./secrun`, it can install tools that are missing. Ctrl-C stops it at any time.
- **No Windows build.** Secrun needs `bash`, so there are builds for Linux x86-64, Linux ARM64 and macOS on Apple silicon only.

## Which build do I need?

Pick the build that matches your operating system and CPU architecture. If you are not sure, `uname -m` prints the architecture ([uname(1)](https://man7.org/linux/man-pages/man1/uname.1.html)):

```bash
uname -m
```

| `uname -m` prints | Operating system | Choose |
| --- | --- | --- |
| `x86_64` | Linux | Linux x86-64 |
| `aarch64` | Linux | Linux ARM64 |
| `arm64` | macOS | macOS Apple silicon |

An Intel Mac prints `x86_64` under macOS, and there is no build for it. Run the Linux x86-64 build in a Linux virtual machine on it instead.

Warning

**On a Mac, there is one extra step.** macOS blocks Secrun until you approve it in **System Settings → Privacy & Security → Security → Open Anyway**. See [how to install Secrun on macOS](https://hackergpt.org/blog/secrun-run-commands-on-your-machine/#how-do-i-install-and-run-secrun-on-macos).

## How do I install and run Secrun on Linux?

Download the build from the Commands tab, put it in an empty folder for this engagement, make it executable and start it. In a terminal:

```bash
# 1. a new, empty folder for this engagement
mkdir -p ~/ctf/my-event && cd ~/ctf/my-event

# 2. move the download into it (adjust the path if your browser saves elsewhere)
mv ~/Downloads/secrun .

# 3. make it executable, then start it
chmod +x secrun
./secrun   # or: sudo ./secrun for more rights (it can then install missing tools)
```

Replace `my-event` with a name for the engagement. The `chmod +x` step is needed because a file saved by a browser is not marked as executable ([chmod(1)](https://man7.org/linux/man-pages/man1/chmod.1.html)).

If you want the model to be able to install tools it finds missing, start it with `sudo ./secrun` instead. Do that only inside a VM or container you are prepared to throw away (see [below](https://hackergpt.org/blog/secrun-run-commands-on-your-machine/#how-do-i-run-secrun-safely)).

Leave the terminal open. Secrun works while it is running and connected; Ctrl-C ends it.

## How do I install and run Secrun on macOS?

On a Mac with Apple silicon the steps are the same as on Linux, plus one approval: macOS blocks a downloaded program that is not from the App Store or an identified developer until you allow it in **Privacy & Security**.

Warning

**macOS users: Secrun will not run until you approve it.** The first `./secrun` is blocked by macOS. Then:

1. Click **Done** in the dialog (not Move to Trash).
2. Open **System Settings → Privacy & Security** and scroll down to the **Security** section.
3. Click **Open Anyway** next to the message about `secrun`, and confirm with your password or Touch ID.
4. Run `./secrun` again and choose **Open Anyway** if asked.

Do it within about an hour of the blocked launch, while the button is still there. The steps below show each one in detail.

### 1\. Put it in a folder and make it executable

Download the **macOS Apple silicon** build, then in Terminal:

```bash
mkdir -p ~/ctf/my-event && cd ~/ctf/my-event
mv ~/Downloads/secrun .
chmod +x secrun
./secrun   # or: sudo ./secrun for more rights (it can then install missing tools)
```

### 2\. macOS blocks the first launch

The first `./secrun` does not start. Instead macOS shows a dialog saying it could not verify `secrun`, and offers **Move to Trash** or **Done**. Click **Done**; do not move it to the Trash. This is [Gatekeeper](https://support.apple.com/en-us/102445), which checks programs downloaded from the internet before they first run.

### 3\. Approve it in Privacy & Security

1. Open **System Settings** from the Apple menu and click **Privacy & Security** in the sidebar.
2. Scroll down to the **Security** section. Under **Allow applications from** there is now a line saying that `secrun` was blocked.
3. Click **Open Anyway** next to it.
4. Enter your login password (or use Touch ID) to confirm.

![macOS System Settings, Privacy & Security, the Security section where the Open Anyway button for secrun appears](https://hackergpt.org/blog/secrun-run-commands-on-your-machine/macos-security-section.webp) *System Settings → Privacy & Security, scrolled down to Security. After a blocked launch, the message about secrun and its Open Anyway button appear here.*

Apple's guide notes that the **Open Anyway** button is available for about an hour after the blocked launch ([Open a Mac app from an unknown developer](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unknown-developer-mh40616/mac)). If you do not see it, run `./secrun` again and go straight back to the Security section.

### 4\. Run it again

Back in Terminal, in the same folder:

```bash
./secrun   # or: sudo ./secrun for more rights (it can then install missing tools)
```

If macOS asks once more whether to open it, choose **Open Anyway**. From now on it starts without the prompt. A new download is a new file, so after you download Secrun again you approve the new copy the same way.

Approve Secrun this way, for this one file. Do not lower Gatekeeper for every app to make it run: the per-app exception is all it needs.

## How do I run Secrun safely?

Run it in a dedicated virtual machine or container, not on the laptop you use every day. Secrun runs the commands the model sends with your user's rights, and with `sudo` it can install software, so the machine it runs on should be one you can wipe.

- **A fresh directory per engagement.** It keeps each session's output apart and makes it obvious what was produced where.
- **No `sudo` on your daily machine.** If a tool is missing there, install it yourself and run Secrun without `sudo`.
- **Nothing private in reach.** Keep SSH keys, cloud credentials and personal files off the VM you run it in.
- **Stop it when you stop.** Ctrl-C when the session ends; there is no reason to leave it connected.
- **Treat the binary like a password.** Keep it out of shared folders and repositories, and download a new one if a copy may have leaked: the old one stops working.

A Linux VM is also the way to use Secrun from an Intel Mac or from Windows, which have no build of their own.

## What does a session with Secrun look like?

You work in CTF Mode as usual, and the steps that need a terminal now run in one. A typical flow on a web challenge:

1. Start a CTF session with the challenge description, as in [our beginner's guide to web CTFs](https://hackergpt.org/blog/ctf-for-beginners-web-challenges/).
2. Open the **Commands** tab, download Secrun and start it in a fresh folder, as above.
3. Ask for a step that needs a shell, for example to list the open ports on the challenge host and save the result.
4. The model sends the command; Secrun runs it on your machine; the model reads the real output and explains what it means and what to try next.
5. When you are done, Ctrl-C. The folder holds every scan, download and command log from the session.

Every command Secrun runs appears in the **Commands** tab with its exit code, how long it took and how much output it produced. Here is part of that log from one of our CTF sessions:

![Commands tab log of a CTF session: curl, python3 and jq commands run through Secrun, each with exit code, time and output size](https://hackergpt.org/blog/secrun-run-commands-on-your-machine/commands-log.webp) *Part of the Commands log from a CTF session run through Secrun. Each line is one command the model sent, with its exit code, run time and output size; the red ones exited with an error.*

A few things are visible in it:

- **Ordinary tools.** The model works with `curl`, `python3`, `jq` and shell redirection, the same tools you would reach for, so you can read every step and rerun it yourself.
- **Labelled output.** Many commands start with `echo "=== ... ==="`, so the output of each probe is easy to tell apart when you read it back.
- **Files in the workspace.** Request bodies and responses are written to a `tmp/` folder inside the engagement directory (`tmp/sqli.json`, `login.json`) and reused by later commands, which is why they are still there after the session.
- **Failures stay visible.** Two commands exited with `1` and `2`. The log keeps them next to the ones that worked, so you can see what was tried and did not work, not only the path that did.

The copy button on each line lets you take a command and run it again yourself.

Everything the model learns about the target stays in the **Memory** tab, and you can still steer it mid-run, as introduced in [HackerGPT 0.5.7](https://hackergpt.org/blog/hackergpt-update-stateful-ctf-engagements-concurrent-steering-and-decoupled-browsing/). Secrun adds the shell; the rest of the session works as before.

## Key takeaways

- Choose the build with `uname -m`: Linux x86-64, Linux ARM64 or macOS Apple silicon; there is no Windows or Intel Mac build.
- Start Secrun in a new, empty folder for each engagement; that folder collects all scan output, downloads and logs.
- On macOS, approve it once in System Settings → Privacy & Security → Security → Open Anyway, within about an hour of the blocked launch.
- Run it in a VM or container, and use `sudo ./secrun` only on a machine you can throw away.
- The downloaded binary is a credential: never share or commit it, and download a new one to revoke an old copy.

## FAQ

### What is Secrun in HackerGPT?

Secrun is a small binary you download from the Commands tab of a HackerGPT CTF session. While it runs on your machine, the commands the model chooses are executed there with `bash`, and their output goes back to the session. It runs only the commands the model sends and stops when you press Ctrl-C.

### Why does macOS say it cannot open secrun?

macOS Gatekeeper blocks programs downloaded from the internet that are not from the App Store or an identified developer until you approve them. Open System Settings, go to Privacy & Security, scroll to the Security section and click Open Anyway next to the message about secrun, then confirm with your password. Run `./secrun` again afterwards.

### Is there a Windows or Intel Mac version of Secrun?

No. Secrun runs commands with `bash`, and the builds are Linux x86-64, Linux ARM64 and macOS on Apple silicon. On Windows or an Intel Mac, run the Linux build inside a Linux virtual machine.

### Should I run Secrun with sudo?

Only if you want it to install missing tools, and only on a VM or container you can wipe. Without `sudo` it runs commands as your user and cannot install packages, which is the safer choice on any machine you also use for other work.

### What happens if I download Secrun again?

The new download replaces your build and the previous copy stops working. That is also how to revoke a copy you think has leaked. On macOS the new file needs the Open Anyway approval once more.

## Sources

- Apple: [Open a Mac app from an unknown developer](https://support.apple.com/guide/mac-help/open-a-mac-app-from-an-unknown-developer-mh40616/mac)
- Apple: [Safely open apps on your Mac](https://support.apple.com/en-us/102445)
- Linux man-pages: [uname(1)](https://man7.org/linux/man-pages/man1/uname.1.html)
- Linux man-pages: [chmod(1)](https://man7.org/linux/man-pages/man1/chmod.1.html)
- HackerGPT: [CTF Mode](https://hackergpt.org/features/ctf-mode/)

Try it in your next CTF session at [hackergpt.app](https://hackergpt.app), or practise first on [CyberGym](https://cybergym.hackergpt.app).