Mobile - Allternit Docs

Overview

The Allternit iOS client is a native SwiftUI application that brings the Allternit platform to iPhone. It supports chat with agents, cowork project tracking, cloud-instance management, BYOC monitoring, agent hub management, and push-driven live activities. The mobile surface uses the same backend APIs as the web and desktop surfaces: Clerk authentication, agent-sessions, agent-chat, and the full platform REST API.

Base URL

The iOS client connects to the Allternit platform API:

https://api.allternit.com/api

Local development targets:

http://127.0.0.1:8013/api

Authentication is performed with the Clerk iOS SDK. The backend receives Authorization: Bearer <Clerk JWT>.

Key platform endpoints

The mobile client consumes these live platform endpoints.

Method	Path	Purpose
`POST`	`/api/v1/agent-sessions`	Create a chat session
`GET`	`/api/v1/agent-sessions`	List sessions / history
`GET`	`/api/v1/agent-sessions/:id/messages`	Fetch session messages
`POST`	`/api/agent-chat`	Send a message and stream the reply
`POST`	`/api/v1/agent-sessions/:id/abort`	Stop an in-flight reply
`GET`	`/api/v1/agent-preferences`	Read user response-style preferences
`PUT`	`/api/v1/agent-preferences`	Update response-style preferences
`GET`	`/agents/:id/workspace/file`	Read an agent workspace file
`PUT`	`/agents/:id/workspace/files`	Write an agent workspace file

Request / response examples

Create a session

curl -X POST https://api.allternit.com/api/v1/agent-sessions \
  -H "Authorization: Bearer $CLERK_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Mobile chat",
    "origin_surface": "chat",
    "session_mode": "regular",
    "metadata": { "device": "ios" }
  }'

{
  "id": "ses_abc123",
  "name": "Mobile chat",
  "origin_surface": "chat",
  "session_mode": "regular",
  "created_at": "2026-08-13T19:50:00Z"
}

Stream a chat reply

curl -X POST https://api.allternit.com/api/agent-chat \
  -H "Authorization: Bearer $CLERK_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "chatId": "ses_abc123",
    "message": "Explain this code",
    "runtimeModelId": "default"
  }'

Response body is SSE-style data: {json} lines:

data: {"type":"message_start","messageId":"msg_1","modelId":"default","runtimeModelId":"default"}
data: {"type":"content_block_delta","messageId":"msg_1","partId":"p1","delta":{"type":"text_delta","text":"This function..."}}
data: {"type":"finish","status":"complete"}

Read agent preferences

curl https://api.allternit.com/api/v1/agent-preferences \
  -H "Authorization: Bearer $CLERK_JWT"

{
  "response_style": "concise",
  "custom_instructions": "Prefer TypeScript examples."
}

Update agent preferences

curl -X PUT https://api.allternit.com/api/v1/agent-preferences \
  -H "Authorization: Bearer $CLERK_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "response_style": "verbose",
    "custom_instructions": "Include unit tests in answers."
  }'

{
  "updated": true,
  "style_md_synced": true
}

Abort a session

curl -X POST https://api.allternit.com/api/v1/agent-sessions/ses_abc123/abort \
  -H "Authorization: Bearer $CLERK_JWT"

{
  "aborted": true
}

Capabilities

Chat — streaming conversations with agents, markdown rendering, syntax highlighting, and artifact cards.
Agent Hub — browse, create, edit, and template agents; switch agents from the composer.
Cowork — view and manage cowork projects and tasks.
Cloud instances — monitor and operate cloud and BYOC deployments.
IntelliSchedule — time-aware agent scheduling from the device.
Live Activities — keep a long-running loop visible on the lock screen.
Push notifications — background refresh and push-driven alerts.

Technology stack

Component	Choice
Deployment target	iOS 17
Auth	Clerk iOS SDK
Chat UI	Custom SwiftUI with `LazyVStack` or `exyte/Chat`
Markdown	`MarkdownView` incremental streaming renderer
Code artifact preview	`WKWebView` with custom `WKURLSchemeHandler`
Inline code highlight	`Highlightr`
SSE transport	Hand-rolled `URLSession.bytes(for:)` + `AsyncThrowingStream`

Build and run

cd surfaces/allternit-mobile/ios
# open Allternit.xcodeproj in Xcode
# or build from the command line with xcodebuild

Error codes

The iOS client surfaces API errors through the standard HTTP status codes:

Status	Meaning
`200 OK`	Success
`400 Bad Request`	Invalid request payload
`401 Unauthorized`	Clerk JWT missing, expired, or invalid
`404 Not Found`	Session or agent not found
`429 Too Many Requests`	Rate limited
`500 Internal Server Error`	Backend error

Client-side errors are reported as device alerts and logged to the in-app diagnostics view.

Allternit Factory on the phone

Shipping with the Allternit Factory build. Applies to the ai.allternit.com phone layout and the m.allternit.com app. Not live yet.

The bot phone is the main surface: one bot, its threads, its Work app and Approve.
Code: one terminal with a bot strip above it to switch between Terminal bots’ panes.
The Board and the Node page are one-column lists, and Approve works from them.
“Needs you” arrives as a push notification with Approve and Open buttons, and on your own channels with a one-time code. See Approvals.

The phone reads the same Allternit Factory engine as Desktop and Gizzi, through the fabric relay.

Mode controls and shell rail tabs share the desktop glass selection style. The Chat/Cowork control uses the same glass highlight on ai.allternit.com and the installed PWA. Touch targets keep their phone sizing, and motion and transparency follow system accessibility preferences. Bot avatar packs, expression rendering, visible sizing and category controls are shared with Desktop. The same assets and renderer ship in both the web phone layout and the PWA.

​Overview

​Base URL

​Key platform endpoints

​Request / response examples

​Create a session

​Stream a chat reply

​Read agent preferences

​Update agent preferences

​Abort a session

​Capabilities

​Technology stack

​Build and run

​Error codes

​Allternit Factory on the phone

​Related links

​Navigation appearance

Overview

Base URL

Key platform endpoints

Request / response examples

Create a session

Stream a chat reply

Read agent preferences

Update agent preferences

Abort a session

Capabilities

Technology stack

Build and run

Error codes

Allternit Factory on the phone

Related links

Navigation appearance