# Swift SDK (/reference/swift-sdk)

Give an iPhone, iPad or Mac app a working copy of an instance that reads offline, queues its writes and keeps itself current.



The Swift SDK is the `marfa-swift` package. **An app built on it is a [device](/build/devices)**: it keeps a working copy of part of an instance on the machine, reads it with or without a connection, and sends its writes when it reaches the server.

Use it for an app that must keep working offline. A script or a server needs no working copy: use the [TypeScript SDK](/reference/typescript-sdk) or the [HTTP API](/reference/api). [Build an app with Swift](/build/swift-app) builds a SwiftUI app on the SDK, step by step.

## Install [#install]

The SDK supports iOS 27 and macOS 27 and builds with Xcode 27 on a Mac with Apple silicon. In Xcode, choose **File** > **Add Package Dependencies**, enter `https://github.com/withmarfa/marfa-swift`, set **Dependency Rule** to **Exact Version**, and enter the version of the [latest release](https://github.com/withmarfa/marfa-swift/releases/latest). In a `Package.swift`:

```swift title="Package.swift"
.package(url: "https://github.com/withmarfa/marfa-swift", exact: "<latest release>"),
// in your target's dependencies:
.product(name: "Marfa", package: "marfa-swift"),
```

* **Update deliberately.** Every release adds 0.0.1, whatever it changes, and until 0.1 any release can rename a call or add an enum case. Read the [release notes](https://github.com/withmarfa/marfa-swift/releases), then change the version.
* **The SDK's enums are exhaustive.** Switch over them without `@unknown default`, so a case a later release adds stops the build where it must be handled.
* **Each release carries the core of one Marfa release,** already built, so the app needs no Rust toolchain. Update the SDK when you upgrade the instance.
* **The core is built for Apple silicon only.** In the app target's build settings, set **Excluded Architectures** for **Any iOS Simulator SDK** to `x86_64`, or some simulator builds fail to link.

## A first run [#a-first-run]

This signs the app in with the owner's approval, opens a working copy and fills it with the person's files. On a later launch the sign-in comes from the keychain and the copy opens with what it holds:

```swift
import Marfa

let serverURL = URL(string: "https://marfa.example.com")!
let auth = try Authorization(
    server: serverURL,
    client: .init(
        name: "Shoebox",
        redirect: URL(string: "com.example.shoebox:/signed-in"),
        scopes: ["core.file:read", "core.file:write"]),
    service: "com.example.shoebox")

let credential: Credential
if let kept = try auth.credential() {
    credential = kept
} else {
    credential = try await auth.signIn(presentingFrom: window)
}

let server = try Server(url: serverURL, credential: credential)
let store = URL.applicationSupportDirectory.appending(path: "marfa.sqlite")
let copy = try await WorkingCopy.open(store: store, server: server)
if try await copy.status().hydration == .never {
    _ = try await copy.hydrate(types: ["core.file"], tier: .library)
}
```

[Sign-in and server calls](/reference/swift-sdk/server-calls#sign-in) covers `Authorization`, and [Working copy](/reference/swift-sdk/working-copy) opening and filling the copy.

## Products [#products]

| Product | Holds |
| - | - |
| `Marfa` | **The SDK:** the working copy, sign-in, server calls and folders. Add it to the app target. |
| `MarfaAPI` | `Client`, for the [operations the working copy doesn't make](/reference/swift-sdk/server-calls#the-api-client), such as registering a type. It includes `MarfaTypes`. |
| `MarfaTypes` | The server's wire types, generated from the API description, and `marfaContractVersion`. |
| `MarfaTesting` | A [fake working copy](/reference/swift-sdk/errors-and-testing#test-against-a-fake-copy) and a keychain and key store in memory. It compiles empty in a release build, so wrap its uses in `#if DEBUG`. |
| `MarfaIcons` | `TypeIcon`, which [draws a type's icon](/reference/swift-sdk/server-calls#draw-a-types-icon). |
| `MarfaBrandIcons` | The brand marks a type's icon can name. An app that doesn't add it ships none of the artwork. |

## What the SDK decides [#what-the-sdk-decides]

* **Marfa decides what things mean:** an item's name and preview, what a link points to, whether an edge is allowed, what a filter matches. The SDK passes on the answers of Marfa's core, so every app agrees.
* **The SDK does what every Swift app needs:** keeping the copy in step, retrying with back-off, sorting errors into kinds, keeping keys, reading dates and drawing icons.
* **The app decides the rest:** its screens, its words, and choices such as what to call an item with no name.

The rules behind the SDK are in the contract's [device](https://github.com/withmarfa/marfa/blob/main/conformance/spec/device.md), [queue and verdicts](https://github.com/withmarfa/marfa/blob/main/conformance/spec/queue-and-verdicts.md), [stores](https://github.com/withmarfa/marfa/blob/main/conformance/spec/stores.md) and [folder sync](https://github.com/withmarfa/marfa/blob/main/conformance/spec/folder-sync.md) chapters. The source is in the [marfa-swift repository](https://github.com/withmarfa/marfa-swift).
