# Quickstart {#quickstart}

This page covers installing [Takumi Agent](/docs/t/endpoint/index.md) on a Mac: create an enrollment key in the console, run the installer package, and approve the macOS prompts in the setup window. You don't need the Terminal.

## Prerequisites {#prerequisites}

- **An Apple silicon Mac.**
- **macOS 13 (Ventura) or later.**
- **An administrator account.** You need one to install the package, enroll the device, and trust the Mac's device certificate.

## The prompts to expect {#prompts}

Setup shows these system prompts, in this order. Approving them is the installation.

1. **The installer's administrator password**, when the package installs.
2. **Notification permission** (optional). If you decline, the Mac can't alert you when it stops being protected.
3. **Administrator credentials to trust the device certificate.**
4. **The system extension approval**, in System Settings, followed by your administrator password.
5. **"TakumiAgent Would Like to Add Proxy Configurations"**. This one starts capturing installs.
6. **"… would like to filter network content"**. A separate prompt, for the egress lock.

## Step 1: Download the package {#download}

Download the latest installer: [takumi-agent-latest.pkg](https://shisho.dev/releases/takumi-agent-latest.pkg). Each release is also kept at `https://shisho.dev/releases/takumi-agent-<version>.pkg`. You only install once. After that the agent updates itself (see [Updates](/docs/t/endpoint/features/managing-devices.md#updates)).

## Step 2: Create an enrollment key {#enroll-key}

In the console, open **Endpoint → Enrollment Keys → Create enrollment key**.

<img src={require("./installation-step2-enrollment-keys.png").default} alt="The enrollment key list in the console" className="zoomable" />

In the dialog, set a label, the maximum number of activations, and how long the key is valid. The toggles below limit which Guard capabilities devices enrolled with this key get. Leave them all on for no restriction. [Managing devices](/docs/t/endpoint/features/managing-devices.md#enrollment-keys) describes each toggle.

<img src={require("./installation-step2-create-key-dialog.png").default} alt="The create enrollment key dialog" width="460" className="zoomable" />

Copy the key, which looks like `tg_enroll_…`, right away. It is only shown once.

Creating and viewing enrollment keys needs the **Owner** or **Takumi Manager** role (see [Roles and Permissions](/docs/c/iam/permission.md)). If you don't see the **Create enrollment key** button, ask an organization owner.

## Step 3: Install the package {#install-pkg}

Double-click the package and enter an administrator password. The package always installs to `/Applications`.

<img src={require("./installation-step3-installer.png").default} alt="The Takumi Agent installer" width="640" className="zoomable" />

Besides the app, the installer sets up a background service, so protection keeps running when nobody is logged in.

On a **first install, with someone logged in to the Mac's desktop**, the setup window opens when the installer finishes. Otherwise it opens at the next login, or you can open Takumi Agent from `/Applications`.

### Scripted install {#scripted-install}

To install from the command line, download the package and pass the enrollment key to `installer` in the `TAKUMI_AGENT_ENDPOINT_ENROLLMENT_TOKEN` environment variable:

```sh
curl -fLO https://shisho.dev/releases/takumi-agent-latest.pkg
sudo TAKUMI_AGENT_ENDPOINT_ENROLLMENT_TOKEN=tg_enroll_… installer -pkg takumi-agent-latest.pkg -target /
```

On a first install, the device enrolls during installation, and the setup window skips [Step 4](#enroll) and starts at [Step 5](#trust-ca). If the key is rejected, the install still completes, and the setup window asks for the key at [Step 4](#enroll) as usual.

## Step 4: Paste the enrollment key {#enroll}

Paste the key from step 2 into the setup window. This registers the Mac as a device in your organization.

<img src={require("./installation-step4-setup-window.png").default} alt="The setup window asking for the enrollment key" width="516" className="zoomable" />

## Step 5: Trust the device certificate {#trust-ca}

macOS asks for administrator credentials so the Mac trusts its own device certificate in the System keychain.

<img src={require("./installation-step5-trust-prompt.png").default} alt="The certificate trust prompt" width="296" className="zoomable" />

macOS only allows this with an administrator's direct approval, so the installer can't do it for you. Until it's done, the device shows **Not protected** everywhere and captured installs **fail closed**. Nothing is let through unchecked.

If you dismiss the dialog, the app asks again at the next launch, and the menu bar shows a **Finish setup…** button.

:::warning If the Mac's user is not an administrator
A non-administrator can't complete this step or enroll the device, and the app says so. The device stays Not protected until an administrator opens Takumi Agent.
:::

## Step 6: Approve the system extension, proxy configuration and filter {#approve-filter}

Next come three separate approvals. Approve all three.

### Allow the system extension {#approve-sysext}

First, macOS asks you to **allow the system extension**. Without it, Takumi Agent can't see registry traffic at all. Click **Open System Settings**: it opens **Login Items & Extensions** with the **Network Extensions** list. Turn **TakumiAgent** on and enter your administrator password.

<div style={{display: "flex", flexWrap: "wrap", gap: "0.75rem", alignItems: "flex-start", marginBottom: "1.25rem"}}>
  <figure style={{margin: 0, textAlign: "center"}}>
    <img src={require("./installation-step6-sysext-prompt.png").default} alt="The network extension approval prompt" style={{height: 260, width: "auto"}} className="zoomable" />
    <figcaption style={{fontSize: "0.85rem"}}>1. Click <b>Open System Settings</b></figcaption>
  </figure>
  <figure style={{margin: 0, textAlign: "center"}}>
    <img src={require("./installation-step6-settings-network-extension.png").default} alt="The TakumiAgent switch under Network Extensions" style={{height: 260, width: "auto"}} className="zoomable" />
    <figcaption style={{fontSize: "0.85rem"}}>2. Turn on <b>TakumiAgent</b></figcaption>
  </figure>
  <figure style={{margin: 0, textAlign: "center"}}>
    <img src={require("./installation-step6-sysext-password.png").default} alt="The administrator password prompt for the system extension" style={{height: 260, width: "auto"}} className="zoomable" />
    <figcaption style={{fontSize: "0.85rem"}}>3. Enter your password</figcaption>
  </figure>
</div>

If you closed the prompt, open **System Settings → General → Login Items & Extensions** and select **By Category**, and click the ⓘ next to **Network Extensions**.

### Allow the proxy configuration {#approve-proxy}

Then macOS shows **"TakumiAgent Would Like to Add Proxy Configurations"**. Click **Allow**. Nothing is inspected until you do.

### Allow content filtering {#approve-filter-prompt}

The last dialog asks to let Takumi Agent **filter network content**. This is the egress lock, which blocks direct connections to the supported registries so they can't be reached around Takumi Guard. Click **Allow**. Capture works without it, but the Mac shows **Needs attention** until you approve it.

<img src={require("./installation-step6-filter-prompt.png").default} alt="The filter network content prompt" width="296" className="zoomable" />

The setup checklist updates as the app sees each step complete:

| Checklist step         | Meaning                                       |
| ---------------------- | --------------------------------------------- |
| **Extension approved** | The system extension is approved              |
| **Network filter on**  | The network filter is enabled                 |
| **Installs inspected** | The background service is inspecting installs |

<img src={require("./installation-step6-checklist.png").default} alt="The finished setup checklist" width="516" className="zoomable" />

If the window still says **"This Mac is still not protected"** with all three steps checked, see [Troubleshooting](/docs/t/endpoint/references/troubleshooting.md#still-not-protected).

If you dismissed a prompt, use **Reopen the approval prompt** or **Open System Settings…** to get it back. A **Turn on network filter** button appears when the filter is off, and the panel shows **Enable egress lock…** if you declined the content filter.

## Step 7: Check the menu bar {#verify-menubar}

When setup is done, the Takumi panda <img src={require("./installation-step7-menubar-icon.png").default} alt="The Takumi panda in the menu bar" width="44" style={{verticalAlign: "middle", borderRadius: 6}} /> shows up in the menu bar with a status badge in its corner. A green dot means Protected. [Device states](/docs/t/endpoint/features/states.md) lists the others.

Click the panda to open the panel. The header shows the same state. Below it is a row for each part of the protection (**Guard**, which expands to show each ecosystem, **Containers**, **Egress lock**, **Identity** and **Health**), with a button wherever there's something you can fix yourself. At the bottom are the agent version, the last check-in time, a **Check now** button, **Open Takumi Agent**, which opens [the app window](/docs/t/endpoint/features/app-window.md), **Help**, and **Quit status icon** (protection stays on).

<img src={require("./installation-step7-menubar-panel.png").default} alt="The menu bar panel" width="356" className="zoomable" />

The panel uses the Mac's language setting for Takumi Agent (English or Japanese).

## Step 8: Check the console {#verify-console}

The device shows up in the console a few seconds after enrolling. After that it reports its state about every 5 minutes.

Open **Endpoint** in the left navigation (it opens on **Devices**) and click the device to open its detail panel. Check that the Mac shows **Protected**.

You can also test with a real package manager. No npm configuration is needed:

```sh
npm install @panda-guard/test-malicious
```

Run it in a new terminal window, because a terminal opened before setup doesn't trust the device certificate yet. npm reports `403 Forbidden`: Takumi Guard checked the request and blocked it. If you see something else, open the menu-bar panel and check [Device states](/docs/t/endpoint/features/states.md).

The Guard test module for Go works the same way, with no configuration, and also reports `403 Forbidden`:

```sh
cd $(mktemp -d) && go mod init verify-takumi-guard && go get github.com/flatt-security/hola-takumi-go@v0.1.0
```

## Before you start working {#next}

Quit and reopen your terminals, IDEs and AI coding agents. If you install packages inside containers, set up container trust once. [Developing with Takumi Agent](/docs/t/endpoint/development.md) explains both.

## Updates {#updates}

The agent updates itself; see [Managing devices](/docs/t/endpoint/features/managing-devices.md#updates).

## Uninstalling {#uninstall}

See [Uninstalling](/docs/t/endpoint/features/uninstall.md). Deleting the app alone leaves the system extension and network configuration behind.