> For the complete documentation index, see [llms.txt](https://docs.1kosmos.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.1kosmos.com/authentication/macos-workstation-mfa-beta/installation.md).

# Installation

The plugin can be installed using the provided `install.sh` helper script, which handles installation and configuration in a single step, or by installing the `.pkg` directly and configuring it manually. Both methods require a reboot to complete. <br>

### Using install.sh (recommended)

Copy both `install.sh` and the `.pkg` to the target machine, then run and reboot.

```
Bash
 
sudo ./install.sh
--dns "your-tenant.1kosmos.net"
--community "default"
--seed "your-community-seed-here"
--bypass-user "admin"
--pkg ./1KosmosPlugin-1.0.0.pkg 
```

**Parameters:**

| Flag            | Required | Description                                                        |
| --------------- | -------- | ------------------------------------------------------------------ |
| `--dns`         | Yes      | Tenant DNS (e.g. `your-tenant.1kosmos.net`)                        |
| `--community`   | Yes      | Community name (e.g. `default`)                                    |
| `--seed`        | No       | Community seed for offline OTP. Stored securely in keystore.       |
| `--bypass-user` | No       | Username that bypasses MFA (recovery account).                     |
| `--pkg`         | No       | Path to the .pkg file. Defaults to `dist/1KosmosPlugin-1.0.0.pkg`. |

The script validates the configuration after installation and reports any issues.

### Direct pkg install (without install.sh)

```
Bash 

sudo installer -pkg 1KosmosPlugin-1.0.0.pkg -target /
```

Then manually configure:

```
Bash

Set DNS and community
sudo /usr/libexec/PlistBuddy -c "Set :dns 'blockid-uat.1kosmos.net'" "/Library/Application Support/1Kosmos/config.plist" 
sudo /usr/libexec/PlistBuddy -c "Set :communityName 'default'" "/Library/Application Support/1Kosmos/config.plist"

Set bypass user (optional recovery account)
sudo /usr/libexec/PlistBuddy -c "Set :bypassUser 'admin'" "/Library/Application Support/1Kosmos/config.plist" 2>/dev/null ||
sudo /usr/libexec/PlistBuddy -c "Add :bypassUser string 'admin'" "/Library/Application Support/1Kosmos/config.plist"

Set community seed in keystore (for offline OTP)
sudo /usr/libexec/PlistBuddy -c "Add :communitySeed string 'your-seed'" "/Library/Application Support/1Kosmos/keystore.plist" 
sudo chown root:_securityagent "/Library/Application Support/1Kosmos/keystore.plist" 
sudo chmod 640 "/Library/Application Support/1Kosmos/keystore.plist"
```

### What the installer does

1. Installs `1KosmosPlugin.bundle` to `/Library/Security/SecurityAgentPlugins/`
2. Installs `uninstall.sh` to `/Library/Application Support/1Kosmos/`
3. Creates `/Library/Application Support/1Kosmos/` directory
4. Seeds `config.plist` from template if it doesn't exist (preserves existing config on upgrade)
5. Sets bundle ownership to `root:wheel` with 755 permissions
6. Fixes keystore permissions to `root:_securityagent 640`
7. Wires the plugin into the macOS authorization database:
   * `system.login.console` → `1KosmosPlugin:login` (login screen)
   * `authenticate` → `1KosmosPlugin:unlock` (lock screen)
8. Backs up original auth DB rules to `/Library/Application Support/1Kosmos/backups/`

### Verification

```
Bash

Verify the package is registered
pkgutil --pkgs | grep com.1kosmos.plugin.pkg

Verify the bundle is installed
ls /Library/Security/SecurityAgentPlugins/1KosmosPlugin.bundle

Check configuration
cat "/Library/Application Support/1Kosmos/config.plist"
```

**Logs:**

To view the logs, run the following command:

```
Bash

All plugin logs
log show --predicate 'subsystem == "com.1kosmos.plugin"' --last 5m --info --debug
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.1kosmos.com/authentication/macos-workstation-mfa-beta/installation.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
