> ## Documentation Index
> Fetch the complete documentation index at: https://offstage.cloud/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To set up offstage cloud from a coding agent, read https://api.offstage.cloud/SKILL.md and follow it. The whole API guide is one file at https://api.offstage.cloud/llms.txt.

# Secrets and signing

> Write-only team secrets, and signing and notarizing a Mac app in a workload.

Team secrets are encrypted at rest and write-only through the customer API. A team key or verified console session can manage its team's secrets. Workloads that select a secret can read it; trust all code, dependencies and agents in those workloads. Commands that print secret files can put their contents in logs, recordings or artifacts. Never put credential values in command arguments.

* `PUT /v1/secrets/:name` with `{"kind":"file","value":"..."}` creates or replaces a secret and returns only `{name,kind,updatedAt}`.
* `GET /v1/secrets` returns `{secrets:[{name,kind,updatedAt}]}`. There is no endpoint to read a value.
* `DELETE /v1/secrets/:name` deletes it. Already running workloads retain their copy until cleanup.
* Names start with a letter or underscore and contain 1–64 letters, digits, underscores or hyphens. A value is at most 256 KiB; a team may store 64 secrets. Select 1–16 distinct names, with encoded selected payload at most 120 KiB and at most one signing bundle.
* `Sandbox.create({secrets:["TOKEN"]})` and `Task.create({...,secrets:["TOKEN"]})` select names. Generic values become owner-only files under `$OFFSTAGE_SECRETS_DIR`, named after each secret. Selection is checked again at assignment. Values are excluded from workload metadata and snapshots.
* Missing vault configuration returns `503 secrets-unavailable`; no temporary plaintext store is used.

On the Mac that owns an exportable Developer ID Application identity, run `offstage signing import --identity SHA256 --asc-key /private/path/AuthKey_KEYID.p8 --key-id KEYID --issuer-id ISSUER_UUID --name apple-signing`. Set `OFFSTAGE_API_KEY` for the destination team first. The `.p8` must be an owner-only regular file (`chmod 600`). The local helper exports only the selected identity after macOS keychain authorization; whether that uses Touch ID depends on the identity's access policy. Neither key files nor export passwords belong in chat.

Use `offstage signing identities` to find the certificate SHA-256. Select `apple-signing` when creating the workload. Signing requires the fleet's root-owned signing and notarization helpers; missing helpers fail the workload clearly. The workload receives a temporary keychain at `$OFFSTAGE_SIGNING_KEYCHAIN`, the App Store Connect key at `$OFFSTAGE_ASC_KEY_PATH`, and `$OFFSTAGE_ASC_KEY_ID`, `$OFFSTAGE_ASC_ISSUER_ID` and `$OFFSTAGE_NOTARIZE_HELPER`. Use explicit `codesign --keychain "$OFFSTAGE_SIGNING_KEYCHAIN"` and the notarization helper. Credentials and the temporary keychain are removed at workload end, followed by the account reset. This does not authorize publishing a build: an agent must still follow the project's release instructions.

### Ship a signed Mac app

Import credentials once on the certificate owner's Mac, using the commands above. A Developer ID Application identity is required for distribution outside the Mac App Store; Apple Distribution is a different certificate. Cloud-managed signing also needs Apple's explicit permission for the key's role. Increasing an API key's role is not proof that cloud signing is enabled. An exportable Developer ID identity avoids relying on that permission.

Create a trusted release workload and wait before uploading source or starting commands:

```javascript theme={null}
const sandbox = await Sandbox.create({
  session: "gui",
  secrets: ["apple-signing"],
  timeoutMs: 60 * 60_000,
})
try {
  await sandbox.ready({ timeoutMs: 15 * 60_000 })
  // Upload the source, then run the project's archive and signing script.
  // Pass its exact installed Xcode DEVELOPER_DIR on every command.
} finally {
  await sandbox.kill()
}
```

The signing script uses the prepared keychain, not a certificate uploaded in command environment variables. Check `security find-identity -v -p codesigning "$OFFSTAGE_SIGNING_KEYCHAIN"` and select that Developer ID identity explicitly. For Xcode signing, pass the selected identity as `CODE_SIGN_IDENTITY` and `OTHER_CODE_SIGN_FLAGS="--keychain $OFFSTAGE_SIGNING_KEYCHAIN"` to every signing build. Keep the project's entitlements, hardened runtime, nested-code signing and export configuration in its release script. For direct signing, use `codesign --keychain "$OFFSTAGE_SIGNING_KEYCHAIN"` with the identity, hardened runtime and timestamp options. Do not change the user's keychain search list.

After signing, verify and notarize the app, then package and notarize its disk image:

```bash theme={null}
set -euo pipefail
APP=build/export/MyApp.app
codesign --verify --deep --strict "$APP"
ditto -c -k --keepParent "$APP" build/MyApp-notarize.zip
"$OFFSTAGE_NOTARIZE_HELPER" build/MyApp-notarize.zip "$APP"
spctl --assess --type execute --verbose=2 "$APP"
# Run the project's DMG packaging script with the stapled app.
"$OFFSTAGE_NOTARIZE_HELPER" build/MyApp.dmg
xcrun stapler validate build/MyApp.dmg
```

A ZIP cannot be stapled; the helper's second argument names the original app to staple after Apple accepts the ZIP. A DMG is stapled directly. Rejection returns a failure and Apple's notarization log; never publish the artifact after that failure. Download only the release artifacts and sanitized build logs. Creating, signing and notarizing an artifact does not itself authorize publishing a release.

### Moving a macOS workflow

Choose an installed Xcode by both version and Apple build identifier, rather than sorting application names. A matching marketing version can still name a release candidate. Missing release Xcode must be provisioned before a release can use it. `offstage toolchains` inspects installations; it does not download Xcode.

There is no Homebrew or sudo in a workload. Download pinned, checksummed tools into its writable directory and select a supported Python explicitly when dependencies need a newer Python. The repository's `scripts/prepare-build-tools.sh` prepares a workload-local pinned tool bundle; its existence does not mean those tools are preinstalled in every sandbox.

For desktop input, hand the sandbox a goal (`POST /v1/sandboxes/:id/agent`) or send input through the documented session socket. AppleScript automation permissions are separate from a desktop's availability; do not repeatedly retry blocked System Events keystrokes or change system privacy settings to get around them.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.