# Installation

> Install InkIt from the release DMG or build from source with XcodeGen. Prerequisites, bundle identifier, deployment target, entitlements (no App Sandbox), and the requirement to replace `/Applications/InkIt.app` after local builds.

- Repository: cartesia-ai/InkIt
- GitHub: https://github.com/cartesia-ai/InkIt
- Human docs: https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b
- Complete Markdown: https://www.grok-wiki.com/public/docs/cartesia-ai-inkit-18975554254b/llms-full.txt

## Source Files

- `README.md`
- `project.yml`
- `InkIt/Info.plist`
- `InkIt/InkIt.entitlements`
- `Config/Signing.local.xcconfig.example`

---

---
title: "Installation"
description: "Install InkIt from the release DMG or build from source with XcodeGen. Prerequisites, bundle identifier, deployment target, entitlements (no App Sandbox), and the requirement to replace `/Applications/InkIt.app` after local builds."
---

InkIt ships as a macOS application bundle (`InkIt.app`) with bundle identifier `ai.cartesia.InkIt`, deployment target macOS 14.0, and App Sandbox disabled so global hotkey capture and synthesized Cmd+V paste via Accessibility can run unsandboxed. End users install from a GitHub release DMG; developers generate `InkIt.xcodeproj` with XcodeGen and must copy the built app into `/Applications/InkIt.app` for changes to take effect.

## Prerequisites

| Requirement | Value | Notes |
| --- | --- | --- |
| Operating system | macOS 14.0+ | `LSMinimumSystemVersion` and `MACOSX_DEPLOYMENT_TARGET` are both `14.0` |
| Architecture | Apple silicon (`arm64`) | Release artifacts are published as `InkIt_<version>_arm64.dmg` |
| End-user install | None beyond macOS | Download the release DMG; no separate runtime |
| Source build | Xcode 15+, XcodeGen | `brew install xcodegen`; `InkIt.xcodeproj` is generated — edit `project.yml`, not the `.pbxproj` |
| Optional notarized builds | Apple Developer ID + `Config/Signing.local.xcconfig` | Maintainer path only; ad-hoc signing works for local dev |

<Warning>
InkIt targets Apple silicon Macs. Intel Macs are not supported in the published release artifacts.
</Warning>

## Install paths

<Tabs>
<Tab title="Release DMG">

The README download button resolves to the latest GitHub release asset:

```
https://github.com/cartesia-ai/InkIt/releases/latest/download/InkIt.dmg
```

<Steps>
<Step title="Download the DMG">

Download `InkIt.dmg` from the [latest GitHub release](https://github.com/cartesia-ai/InkIt/releases/latest/download/InkIt.dmg).

</Step>
<Step title="Move InkIt to Applications">

Open the DMG and drag `InkIt.app` into `/Applications`.

</Step>
<Step title="Launch and verify">

Launch InkIt from Applications. The app appears in the Dock (`LSUIElement` is `false`) and begins onboarding for Microphone and Accessibility permissions.

</Step>
</Steps>

Sparkle checks for updates automatically. The feed URL is configured in `Info.plist`:

<ParamField body="SUFeedURL" type="string">
`https://github.com/cartesia-ai/InkIt/releases/latest/download/appcast.xml`
</ParamField>

<ParamField body="SUEnableAutomaticChecks" type="boolean">
`true` — automatic update checks are enabled on launch.
</ParamField>

</Tab>
<Tab title="Build from source">

<Steps>
<Step title="Install XcodeGen">

```bash
brew install xcodegen
```

</Step>
<Step title="Generate the Xcode project">

```bash
xcodegen generate
open InkIt.xcodeproj
```

</Step>
<Step title="Build Release">

Build the **Release** configuration in Xcode, or from the command line with an explicit derived data path:

```bash
xcodebuild \
  -project InkIt.xcodeproj \
  -scheme InkIt \
  -configuration Release \
  -derivedDataPath build \
  build
```

The built app lands at `build/Build/Products/Release/InkIt.app`.

</Step>
<Step title="Install to Applications">

```bash
cp -R build/Build/Products/Release/InkIt.app /Applications/
```

</Step>
</Steps>

<Warning>
Rebuilding alone is not enough. Changes only take effect after you replace `/Applications/InkIt.app`. Quit any running InkIt instance before copying the new bundle.
</Warning>

Debug builds use ad-hoc signing with `InkIt-Debug.entitlements` (`get-task-allow=true`) for debugger and XCTest attachment. Release builds use `InkIt.entitlements` with hardened runtime enabled. See [Build from source](/build-from-source) for signing, notarization, and Sparkle deep-sign details.

</Tab>
</Tabs>

## App identity

| Field | Value |
| --- | --- |
| Display name | `InkIt` |
| Bundle identifier | `ai.cartesia.InkIt` |
| Bundle ID prefix | `ai.cartesia` |
| Deployment target | macOS `14.0` |
| Current version | `0.1.2` (`CFBundleShortVersionString`) |
| Build number | `4` (`CFBundleVersion`) |
| Test bundle ID | `ai.cartesia.InkItTests` |

`Info.plist` usage descriptions gate permission prompts at first launch:

- **Microphone** — records voice while the dictation hotkey is held and streams audio to Cartesia STT.
- **Apple Events** — pastes transcribed text into the focused application.

## Entitlements and sandbox

InkIt runs **without App Sandbox**. `ENABLE_APP_SANDBOX` is `NO` in `project.yml` because synthesized Cmd+V paste through Accessibility requires an unsandboxed binary.

Release entitlements (`InkIt/InkIt.entitlements`):

| Entitlement key | Release value | Purpose |
| --- | --- | --- |
| `com.apple.security.device.audio-input` | `true` | Microphone capture for dictation |
| `com.apple.security.automation.apple-events` | `true` | Paste into focused apps via Apple Events |
| `com.apple.security.get-task-allow` | `false` | Required for notarized distribution |

Debug builds swap in `InkIt/InkIt-Debug.entitlements`, which is identical except `get-task-allow` is `true` so `xcodebuild test` and the Xcode debugger can attach to the host app.

Signing configuration by build type:

| Configuration | Identity | Hardened runtime | Entitlements file |
| --- | --- | --- | --- |
| Debug | Ad-hoc (`-`) | Off | `InkIt/InkIt-Debug.entitlements` |
| Release (default) | Ad-hoc (`-`) | On | `InkIt/InkIt.entitlements` |
| Release (maintainer) | Developer ID Application | On | `InkIt/InkIt.entitlements` + `Config/Signing.local.xcconfig` |

To produce a notarized, distributable build, copy the example signing config and supply your Team ID:

```bash
cp Config/Signing.local.xcconfig.example Config/Signing.local.xcconfig
```

Then set `DEVELOPMENT_TEAM`, `CODE_SIGN_STYLE = Manual`, and `CODE_SIGN_IDENTITY = Developer ID Application` in the local file.

## Replace `/Applications/InkIt.app` after local builds

macOS resolves Accessibility grants and running instances by bundle path. When developing locally:

1. **Quit** any running InkIt before installing a new build.
2. **Copy** the freshly built `InkIt.app` over `/Applications/InkIt.app` — do not rely on Xcode's default DerivedData output path alone.
3. **Launch** the `/Applications` copy, not a stale build left in DerivedData or a duplicate path.

If multiple copies with bundle ID `ai.cartesia.InkIt` run simultaneously, `AppCoordinator` surfaces an error naming both paths and instructs you to quit the duplicate and grant Accessibility to only one app bundle. This commonly happens when both a release DMG install and a local build are running, or when Accessibility was granted to an old build path.

<Info>
After replacing the app bundle, you may need to re-grant Accessibility if macOS still associates the permission with a previous binary path. See [Permissions model](/permissions-model) for the onboarding and silent-relaunch flow.
</Info>

## Verify installation

<Check>
**Release install** — `InkIt.app` exists at `/Applications/InkIt.app`, launches from Dock, and onboarding prompts for Microphone access appear.
</Check>

<Check>
**Local build** — `codesign -dvv /Applications/InkIt.app` reports the expected signing identity (ad-hoc `Signature=adhoc` for contributor builds, or `Developer ID Application` for maintainer releases).
</Check>

<Check>
**Single instance** — Only one InkIt process runs; Activity Monitor shows a single `InkIt` entry under `/Applications/InkIt.app`.
</Check>

## Next

<CardGroup>
<Card title="Quickstart" href="/quickstart">
Complete onboarding, configure your Cartesia API key, and run your first dictation after install.
</Card>
<Card title="Permissions model" href="/permissions-model">
Microphone and Accessibility requirements, tri-state permission flow, and post-grant relaunch behavior.
</Card>
<Card title="Build from source" href="/build-from-source">
XcodeGen project generation, Debug vs Release signing, notarized builds, and Sparkle deep-sign post-build scripts.
</Card>
<Card title="Runtime troubleshooting" href="/runtime-troubleshooting">
Duplicate bundle instances, Accessibility grant mismatches, and other non-API runtime issues.
</Card>
</CardGroup>