Apple Shortcuts Integration¶

Apple Shortcuts on macOS, iPhone, and iPad can call Backend.AI GO's local inference API directly using the built-in Get Contents of URL action. This lets you build system-wide automations such as translating selected text in any app, summarizing long articles from the clipboard or Share Sheet, and drafting message replies, all powered by models running on your own hardware.

Integration Methods Overview¶

Backend.AI GO provides three ways to interact with Apple Shortcuts depending on your platform and workflow:

For most Shortcuts that work across both Mac and iPhone or iPad, use the Get Contents of URL action with the Management REST API (POST /api/v1/inference/chat/completions).

Prerequisites and Setup¶

Before building a Shortcut, verify the following requirements in Backend.AI GO:

1. Load a model: Open the Models page in Backend.AI GO, download a model (for example, a Qwen or Llama instruct model), and click Run so the inference server is active. Note the exact model ID shown on the card.
2. Verify Management API status: Open Settings > API Server > Management API. The Management API runs on http://127.0.0.1:8001 by default.

3. Check authentication settings:

   • Same Mac (127.0.0.1): While Require API key is off (the default on localhost), local Shortcuts can call http://127.0.0.1:8001/api/v1/inference/chat/completions without an authentication header.
   • API key enabled or remote devices: When Require API key is on, open Settings > API Server > Access keys, create a key with the Inference Write and Inference Read scopes, and pass it in the X-API-Key header (or Authorization: Bearer <your-key>).

4. Use non-streaming requests: Apple Shortcuts' Get Contents of URL action waits for a single complete HTTP response and cannot parse Server-Sent Events (SSE) token streams. Always set "stream": false (or omit the "stream" field, which defaults to false).

Testing with curl¶

Before assembling actions in the Shortcuts app, test your endpoint and model name from the terminal using curl.

1. Check Server Health and Loaded Models¶

Verify that the Management API is reachable and your model is listed:

# Check Management API health
curl http://127.0.0.1:8001/api/v1/health

# List models available through the inference proxy
curl http://127.0.0.1:8001/api/v1/inference/models

If Require API key is enabled, include -H "X-API-Key: YOUR_ACCESS_KEY" in each command.

2. Send a Basic Chat Completion Request¶

curl http://127.0.0.1:8001/api/v1/inference/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-7b-instruct",
    "messages": [
      {"role": "user", "content": "Say hello in Korean."}
    ],
    "stream": false
  }'

3. Test with a System Prompt and Generation Parameters¶

You can control output length and creativity using system messages, temperature, and max_tokens:

curl http://127.0.0.1:8001/api/v1/inference/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-7b-instruct",
    "messages": [
      {
        "role": "system",
        "content": "You are a concise translator. Translate the user text into English and return only the translation."
      },
      {
        "role": "user",
        "content": "로컬 LLM을 사용하면 개인정보를 안전하게 보호할 수 있습니다."
      }
    ],
    "temperature": 0.2,
    "max_tokens": 256,
    "stream": false
  }'

Sample JSON Response:

{
  "id": "chatcmpl-8f3a9b2c",
  "object": "chat.completion",
  "created": 1710000000,
  "model": "qwen2.5-7b-instruct",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Using a local LLM keeps your personal information safe."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 38,
    "completion_tokens": 12,
    "total_tokens": 50
  }
}

In every Apple Shortcut below, you will extract the assistant's reply from choices -> first item -> message -> content.

Step-by-Step Shortcuts Examples¶

Example 1: Translate Selected Text¶

This Shortcut takes text selected in any macOS app (via Quick Actions / Services) or shared via the iOS Share Sheet, translates it locally, and copies or displays the result.

Action Sequence¶

1. Create a new Shortcut and name it Translate with Local AI.

2. Configure input:

   • On macOS: Click the Shortcut details (i) icon, enable Use as Quick Action, enable Services Menu, and set the input type to Receive Text input from Quick Actions (if there is no input: Ask for Text).
   • On iPhone / iPad: Enable Show in Share Sheet and accept Text.

3. Add a Get Contents of URL action and configure it as follows:

1. Inside the Get Contents of URL JSON body, add the following keys (or build the payload with a Dictionary action first; see Safely Escaping Input Text below):

   • model (Text): qwen2.5-7b-instruct (replace with your loaded model ID)
   • temperature (Number): 0.2
   • max_tokens (Number): 1024
   • stream (Boolean): false

   • messages (Array of 2 Dictionaries):

     • Item 1 (Dictionary): role = system, content = You are a professional translator. Translate the user's text into Korean. Output only the translated text without explanations.
     • Item 2 (Dictionary): role = user, content = Shortcut Input variable

Equivalent JSON payload structure:

{
  "model": "qwen2.5-7b-instruct",
  "messages": [
    {
      "role": "system",
      "content": "You are a professional translator. Translate the user's text into Korean. Output only the translated text without explanations."
    },
    {
      "role": "user",
      "content": "<Shortcut Input>"
    }
  ],
  "temperature": 0.2,
  "max_tokens": 1024,
  "stream": false
}

1. Add the response-parsing actions right after Get Contents of URL:

   1. Get Dictionary Value: Get Value for choices in Contents of URL.
   2. Get Item from List: Get First Item from Dictionary Value.
   3. Get Dictionary Value: Get Value for message in Item from List.
   4. Get Dictionary Value: Get Value for content in Dictionary Value.

2. Add Copy to Clipboard and Show Result (passing the final Dictionary Value) so you can see the translation immediately and paste it anywhere.

Example 2: Summarize Messages or Clipboard¶

This Shortcut reads long text from the clipboard (or Share Sheet), summarizes it into key bullet points, and displays the summary in a notification alert.

Action Sequence¶

1. Create a new Shortcut named Summarize Clipboard.
2. Add Get Clipboard (or accept Text from the Share Sheet).

3. Add Get Contents of URL with:

   • URL: http://127.0.0.1:8001/api/v1/inference/chat/completions
   • Method: POST
   • Headers: Content-Type: application/json
   • Request Body: JSON

Equivalent JSON payload structure:

{
  "model": "qwen2.5-7b-instruct",
  "messages": [
    {
      "role": "system",
      "content": "Summarize the following text into 3 to 5 concise bullet points. Focus on key facts and action items."
    },
    {
      "role": "user",
      "content": "<Clipboard>"
    }
  ],
  "temperature": 0.3,
  "max_tokens": 512,
  "stream": false
}

1. Extract the summary text using the same four actions:

   1. Get Dictionary Value -> choices from Contents of URL
   2. Get Item from List -> First Item
   3. Get Dictionary Value -> message
   4. Get Dictionary Value -> content

2. Add Show Result (with the final Dictionary Value) to display the bulleted summary on screen.

Example 3: Draft a Reply¶

This Shortcut takes an incoming message, prompts you briefly for how you want to respond, generates a polished reply locally, and copies the draft to your clipboard.

Action Sequence¶

1. Create a new Shortcut named Draft Reply with Local AI.
2. Add Get Clipboard (or receive text from Quick Actions / Share Sheet) and add Set Variable to store it as OriginalMessage.
3. Add Ask for Input with prompt "What is your main point or desired tone?" (for example, "Politely decline and suggest next Tuesday"), and add Set Variable to store it as ReplyIntent.

4. Add Get Contents of URL with:

   • URL: http://127.0.0.1:8001/api/v1/inference/chat/completions
   • Method: POST
   • Headers: Content-Type: application/json
   • Request Body: JSON

Equivalent JSON payload structure:

{
  "model": "qwen2.5-7b-instruct",
  "messages": [
    {
      "role": "system",
      "content": "You write clear, polite message replies. Draft a ready-to-send reply to the original message following the user's intent. Output only the reply body."
    },
    {
      "role": "user",
      "content": "Original message:\n<OriginalMessage>\n\nMy reply intent:\n<ReplyIntent>"
    }
  ],
  "temperature": 0.5,
  "max_tokens": 512,
  "stream": false
}

1. Parse the response:

   1. Get Dictionary Value -> choices from Contents of URL
   2. Get Item from List -> First Item
   3. Get Dictionary Value -> message
   4. Get Dictionary Value -> content

2. Add Copy to Clipboard and Show Notification (or Quick Look) so you can review and paste the drafted reply.

macOS Alternative: Using Run Shell Script with the aigo CLI¶

On macOS, you can skip HTTP and JSON parsing altogether by using the Run Shell Script action with the bundled aigo CLI:

1. Add the Receive Text input action.
2. Add Run Shell Script (Shell: /bin/zsh, Pass Input: as stdin).
3. Use aigo chat with a system prompt:

input_text="$(cat)"
aigo chat --system "Translate the user's text into Korean. Output only the translation." "$input_text"

1. Add Show Result or Copy to Clipboard.

See the CLI Reference for all aigo chat and aigo translate flags.

Using Shortcuts on iPhone and iPad¶

On an iPhone or iPad, 127.0.0.1 and localhost refer to the mobile device itself, not your Mac. Because Backend.AI GO binds its API servers to 127.0.0.1 by default, mobile Shortcuts cannot reach your Mac until you configure network access.

You have two ways to connect your iPhone or iPad to Backend.AI GO running on your Mac.

Option 1: Local Wi-Fi (LAN Binding)¶

Use this option when your Mac and your iPhone or iPad are on the same trusted home or office Wi-Fi network.

1. On your Mac, open Backend.AI GO and go to Settings > API Server > Access keys.
2. Click Create Key, give it a name (such as iPhone Shortcuts), select the Inference Read and Inference Write scopes, and copy the generated key.

3. Go to Settings > API Server > Management API:

   • Turn on Require API key.
   • Turn on Allow access from other devices (this binds the Management API to 0.0.0.0 on port 8001).

4. Find your Mac's local LAN IP address in macOS System Settings > Wi-Fi > Details (for example, 192.168.1.50).

5. In your iPhone or iPad Shortcut, update the Get Contents of URL action:

   • URL: http://192.168.1.50:8001/api/v1/inference/chat/completions
   • Headers: Add X-API-Key: <your-access-key>

Option 2: Tailscale or WireGuard VPN (Recommended)¶

If you use your iPhone or iPad away from home, or on networks where client isolation blocks device-to-device LAN traffic, a mesh VPN such as Tailscale provides encrypted access without opening ports on your router:

1. Install Tailscale on both your Mac and your iPhone or iPad, and sign in to the same Tailnet.
2. In Backend.AI GO on your Mac, enable Require API key and Allow access from other devices under Settings > API Server > Management API, and issue an access key with Inference Write.
3. Copy your Mac's Tailscale IPv4 address (100.x.y.z) or MagicDNS hostname from the Tailscale menu bar app.
4. In your Shortcut on iPhone or iPad, set the URL to http://100.x.y.z:8001/api/v1/inference/chat/completions and include the X-API-Key header.

Security Considerations for Remote Access¶

• Always require an API key: Backend.AI GO prevents enabling Allow access from other devices on the Management API unless Require API key is turned on.
• Use least-privilege scopes: Create a dedicated key for Shortcuts with only Inference Read and Inference Write rather than Admin.
• Do not expose ports to the public internet: Avoid port-forwarding port 8001 or 39080 on your home router. Use Tailscale or a VPN when connecting from outside your local network.
• Rotate compromised keys: If a Shortcut containing a hardcoded API key is shared with someone else, revoke that key immediately in Settings > API Server > Access keys.

Tips and Troubleshooting¶

Safely Escaping Input Text¶

When input text from the clipboard or selection contains double quotes (") or line breaks, inserting it into a raw text JSON block can break JSON syntax. By building the request body with native Dictionary fields inside Get Contents of URL (setting the body type to JSON and inserting the Shortcut Input token into the content field of the dictionary), Apple Shortcuts automatically JSON-escapes quotes, backslashes, and newlines for you.

Checking Server Status Before Running¶

If you want your Shortcut to fail gracefully with a friendly message when Backend.AI GO is not running or no model is loaded, add a quick check at the top of the Shortcut:

1. Call Get Contents of URL on http://127.0.0.1:8001/api/v1/inference/status (or /api/v1/inference/models).
2. Check whether running is true (or whether the data list is non-empty) using Get Dictionary Value and an If action before sending the chat completion request.

Model Size and Performance Expectations¶

Shortcuts run interactively, so response latency matters:

• Small models (1B to 4B parameters): Respond in 1 to 3 seconds on Apple Silicon Macs. Ideal for quick text translations and short replies.
• Medium models (7B to 14B parameters): Offer stronger summarization quality and nuanced drafting, typically completing within 3 to 10 seconds depending on input length.
• Large or reasoning models (30B+ or thinking models): Can take 15 seconds or longer to finish generating a complete non-streaming response. Keep max_tokens bounded (for example, 512) so Apple Shortcuts does not time out waiting for the HTTP response.

Common Issues¶

Related Pages¶

• API Server Overview: Overview of the Management API and Continuum Router
• External Access: Safely exposing the API server to other devices on your network
• Building Apps with the API: Using the OpenAI-compatible API with Python, TypeScript, and curl
• Private Document Translation: Translating text and documents locally
• CLI Reference: Full documentation for the aigo command-line tool