SHALL

SHALL — Support

SHALL is an iPhone client for an AI agent you run on your own computer. This page is short on purpose: almost everything that goes wrong with SHALL goes wrong in one of four places, and they are all below.

What SHALL needs before it does anything

SHALL is a client for an AI agent you already run, on a computer you own. It does not host an agent, it does not include one, and there is no SHALL server in between. Without your own agent to point it at, the app has nothing to connect to.

You need four things:

A running hermes-agent your phone can reach. SHALL was built and verified against 0.20.0 (v2026.8.3). That number is kept here because it is the one fact that lets you tell "SHALL is broken" apart from "SHALL has not met this version of the agent": SHALL reads the version your agent reports and shows it, but it does not check it against anything, so a newer agent is neither blocked nor promised. If hermes-agent changes its API, this page goes out of date before the app does — so if something behaves oddly, say which version you are on.

The agent has to listen on an interface your phone can actually reach — a loopback-only binding will not work. Bind it to your private network interface, and to nothing that is reachable from the open internet.

Tailscale, on the computer and on the iPhone, on the same tailnet. SHALL carries an App Transport Security exception for ts.net so that plain HTTP inside the WireGuard tunnel is permitted. Anywhere else, use HTTPS.

The full MagicDNS hostname. This is the single most common way to lose an hour with this app, so it is worth being blunt: the short machine name does not resolve from iOS. Use the complete name, with the tailnet in it, and include the scheme:

http://your-machine.your-tailnet.ts.net:8642

not http://your-machine:8642. SHALL accepts http and https and nothing else, and an address without a scheme is rejected with a message saying so.

The bearer token for that agent. Know what you are putting on a phone: that credential grants your agent's full toolset, terminal commands included, on the machine it runs on — the agent's own documentation says so. SHALL stores it in the iOS Keychain, marked available on this device only, and reads it fresh on every request, so revoking it on your host takes effect immediately. SHALL cannot make the token less powerful than it is. Keep the agent on a private network.

You also need an iPhone running iOS 17.0 or later.

If you do not run an agent of your own, there is a demo built into the app. It answers on the device, reaches nothing, is labelled as the demo everywhere it appears, and exists so you can see what the product does before you decide to connect anything.

Setting it up

  1. Open SHALL and choose Connect your agent.
  2. Enter the address and the key. The address is the full MagicDNS URL above. The key field is deliberately a secure field: iOS does not let any third-party keyboard — including SHALL's own — see what you type into it.
  3. Tap Connect. SHALL asks your agent whether it is there and tells you which of two things happened: it could not be reached at all, or it answered and refused the key. Those are different problems and the message says which one you have.
  4. Add the keyboard, from the screen that follows or from Settings → General → Keyboard → Keyboards → Add New Keyboard… → SHALL.
  5. Allow Full Access when it asks, if you want to reach your agent from the keyboard. iOS shows a serious warning here, and it is right to; what SHALL uses the permission for is below.
  6. Try it: tap into a text field, switch to SHALL with the globe key, then tap the Agent key — the key carrying SHALL's own mark, the two carets either side of a seam, which is the app icon drawn in one colour. On a new install it is the bottom-left key; SHALL → Settings → Keyboard → Agent key offers Bottom left and Beside Return. Type a request, tap Review, read the exact text it is about to send, and confirm.

The keyboard is available in text fields that support third-party keyboards. iOS replaces it with the system keyboard in password fields and number pads, and an app is allowed to refuse third-party keyboards altogether. That is iOS, not a fault in SHALL.

What Full Access is for

iOS requires Allow Full Access before any third-party keyboard can use the network or the clipboard. SHALL uses it for exactly two things:

  1. Reaching your agent from the keyboard. A keyboard extension cannot make a network request without it.
  2. The clipboard, and only inside the Clipboard action or the Copy action you tapped.

Nothing else the switch permits is used: no location, no contacts, no photos, no iCloud, no background uploads. Typing never needs it. With Full Access off the SHALL keyboard types, switches layers and languages, and runs its local demo exactly as before; what you lose is the clipboard action and the ability to reach your agent from the keyboard. The app itself can still reach it. SHALL re-checks the permission every time it would matter, so switching it off in iOS Settings takes effect at once rather than at the next launch.

Revoking the key

The token is issued by your host, so it is revoked on your host — SHALL has no way to reach into your machine and cancel it, and you should be suspicious of any client that claims otherwise.

  1. On the computer running the agent, change or remove the token in hermes-agent's own configuration and restart it. How that is done is documented by hermes-agent, not by us.
  2. In SHALL, remove the stored key. It is on the agent's own screen:
    1. Open Settings in SHALL and find the Agent section at the top.
    2. Tap the Connection row — the one showing your agent's name. Its own screen opens; Remove agent is at the bottom of it, in red. It asks you to confirm.

    That removes the stored key and your agent's address from this device. It also deletes that agent's runs — so runs you started from the share sheet go with it — and the run identifiers the keyboard had handed over, because they all belong to an agent that has just been removed. Other agents are untouched. Your settings are left alone — the keyboard preferences, the appearance and the notification choices are as you set them. Removing the agent does nothing to the token on your machine; step 1 is the one that ends it.

  3. Reconnect with the new token if you meant to rotate rather than to stop.

Use Remove agent before deleting the app, if you want the key gone for certain: iOS does not guarantee that a Keychain item is destroyed when an app is removed, and a later reinstall can find it again.

If you think the token has travelled somewhere it should not have — a screenshot, a chat message, a bug report — rotate it on your host. That is the only action that actually ends its authority.

When something does not work

Reporting a problem

Write to hello@getshall.com. That is the only support channel for SHALL.

Include: what you did, what you expected, what happened instead; which part — the app, the keyboard, or the share sheet; whether Full Access was on; your hermes-agent version and your iOS version; and roughly when it happened, so you can line it up against your own agent's logs. Those are the only logs in existence: SHALL writes none.

Never send your API key. Not in a message, not in a screenshot. Nobody debugging this needs it, and it is a shell on your machine. Remember that a screenshot of a run can contain your own content and your machine's hostname.

If it looks like a security problem — SHALL sending something you did not confirm, a credential turning up somewhere it should not, a run you did not start — report it privately and directly rather than in public.

Privacy

What SHALL stores, what it sends, and what Apple passes on: the SHALL privacy policy.