System overview Using the editor The Exotool language HTML templates The diagram The element catalog Deploying an app
Deploying an Exotool app
This guide is for the person who takes an app from the editor to a server of their own, and for the assistant that helps them. It covers what a deployment is, where it can go, what the host needs, the first run, keeping the app running, the settings an operator may change on the server, and what to do when something fails. Everything here happens from the editor's share icon → Deploy; Claude cannot deploy through the MCP, and will point you to that dialog.
Contents
- What a deployment is
- Where the app can go
- What is sent, and what the host needs
- Running a deployment
- The first run
- Keeping it running
- Settings the operator may change on the server
- The native iOS build
- When something fails
1. What a deployment is
While you build, your app runs as a preview on Exotool's own system: the app on the left of
the editor, at an address under exotool.app. The preview is a complete, running app — people
can use it, add it to a phone's home screen — but it lives on Exotool's servers, its data is kept
there, and it is not meant for production use.
A deployment copies the app to a web host of your own: a server that you rent or own, from a hosting company or your organization, which serves the app at an address of your own. From then on the deployed app runs on that host and keeps its data there, separate from the preview's. You choose the address; your hosting account decides how the app is kept running, backed up and scaled. The preview keeps working as before, as your development copy.
A deployment is a snapshot of the app as it is. Change the design, and the deployed app does not change until you deploy again.
2. Where the app can go
The place an app goes is a web host: a resource of your account (Resources in the editor, or added on the spot in the deploy dialog with Add a web host). A host is set up once and every project can deploy to it. The kinds:
| Kind | What happens | You give |
|---|---|---|
| FTP web host | The files are uploaded over FTP to a directory of the host, which serves them at your public address. | server, user name, password, directory, public address |
| SFTP web host (over SSH) | The same, over SSH, as most hosting accounts and every cloud server allow. | server, port (22 unless said otherwise), user name, a password or a private key (and its passphrase if it has one), directory, public address |
| Subversion repository | The files are committed to a folder of the repository, one revision per deployment, so that they are versioned; your own process serves them from there. | repository address, folder, user name and password, and the public address if there is one |
| GitHub repository | The files are committed to a folder of a branch, one commit per deployment; your own process (GitHub Actions, a webhook, a pull on the server) serves them from there. | repository (owner/name), branch, folder, an access token with Contents: read and write |
| Zip file to download | The files are packed into one zip that you download and put on any host yourself. For a host Exotool cannot reach directly, or when you want the files in hand. | the public address, if you know it |
With a repository or a zip file, Exotool never reaches the server that will serve the app; the public address you give is only shown back to you after the deployment.
The directory you name on an FTP or SFTP host is the folder your public address points at (a
hosting account's public_html, www, htdocs, or a folder under it). It is created when it
does not exist yet — the deploy asks first.
3. What is sent, and what the host needs
A deployment sends the whole app: the page and its scripts and stylesheets for the browser,
the icons and the web manifest, and the app's server program, backend.php, with its helper
files and an empty backend/data folder. The settings of the app's resources — the database,
the mail account, the payment account, the Other resources — are compiled in, so that the app
runs with nothing else configured; section 7 says what an operator may change afterwards.
The host needs:
- PHP 7.2 or later, with the extensions a plain hosting plan has:
json,mbstring,curl(for payments, mail through an API, a secret store),gd(for the images people upload),mysqliwhen the app uses a MySQL resource, andsodium(in PHP since 7.2) when a setting is given encrypted. PHP 8 is fine. - A writable
backend/datafolder: the app keeps its data there (its store,heap.data, and, when the project uses the file-per-object store, one file per record). Images people upload go to the app'simgfolder, which must be writable too. On most hosts a folder the upload created is writable; if not, give it write permission (chmod 775, or the host's file manager). - An Apache-style web server that honours
.htaccess, or a server configured to the same effect: the app's.htaccessmakesindex.htmlthe index, lets the browser revalidate the app's files on every use, and allows only the file types the app is made of to be served; with the project settingssl_requiredit also redirects to HTTPS. On nginx, serveindex.htmlas the index and passbackend/backend.phpto PHP; nothing else is needed. - HTTPS, for a real address: a browser installs a web app to the home screen only from a secure address, and the camera, the location and notifications need it too. Hosting companies give certificates; a cloud server gets one from Let's Encrypt.
4. Running a deployment
Click the share icon in the editor's top bar and choose Deploy. The dialog says, before anything runs:
- Where the app goes — the web host, chosen among your account's hosts or added there and then with Add a web host; the chosen host's kind and settings are shown.
- What goes there — the files and the host's needs, as section 3 says.
- What to deploy — the web app (PWA), the native iOS app files, or both (section 8).
- The administrator's password — when your app has a sign-in form and this is the first deployment to that host (section 5).
- Settings the host's operator may change afterwards — the exact variable names of this project's resources, all optional (section 7).
Deploy now runs it. If your diagram has changes that are not saved yet, the deploy saves and generates them first and tells you so — you never have to Save/Generate beforehand. Then it generates the app for the host (a deployment is compiled with the deployment template, with the resources' settings compiled in), sends the files the way the host's kind says, and ends with the app's public address — or, for a zip file, the download link and what to do with the files, or, for a repository, the revision or commit it made.
Sample projects cannot be deployed; copy one into a project of your own first.
5. The first run
The first time the deployed app is opened, its server program sets itself up: it creates its
store in backend/data and its two built-in accounts, the administrator admin and the
visitor guest.
The administrator's password. When the app has a sign-in form, the deploy dialog asks for
the administrator's password at the first deployment to a host; the password is hashed in the
deploy build and the first run gives it to admin. Later deployments to the same host do not
ask again. Change the password in the app afterwards if you need to; a deployment never resets
it (the setup runs once). An app with no sign-in form is not asked, and its admin keeps the
default password admin — such an app has no way to sign in, but if it holds data worth
protecting, add a sign-in form before you deploy, so that the password gets set.
The data starts empty. A deployed app has none of the preview's data. If you tried things in the preview, that is where they stay. If you want to seed a deployed app, do it through the app itself, or through MySQL when the app uses a MySQL resource.
The resources. The deployed app uses the resources bound to the project at the time of the deployment: the same database, mail, payment and other accounts as the preview, unless you bind others first. A common arrangement is one set of resources for development (a test mail account, Stripe's test keys) and another for production; bind the production ones, deploy, and bind the development ones back. The project's settings remember which host it was deployed to.
6. Keeping it running
Deploying again. Deploy as often as you like. The files are replaced; the data stays:
backend/data is sent as an empty folder and never overwritten, FTP and SFTP never delete
anything, and a repository folder keeps whatever is under backend/data. People who have the
app open get the new version at their next load (the app's files are revalidated on every use).
Backups. The app's data is the backend/data folder (and img for uploaded images): copy
it as your host backs up files, or on a schedule of your own. For a MySQL resource, back up the
database as you back up any database.
Moving hosts. Deploy to the new host, copy backend/data (and img) from the old one, then
point the address at the new host. The app's design travels with the deployment; only the data
needs copying.
Several apps on one host. Each app has its own directory and its own backend/data. With a
MySQL resource, give each app a table prefix in the resource, or a database of its own.
7. Settings the operator may change on the server
Nothing on the server has to be configured: the app runs as compiled, with its resources'
settings inside backend.php. The head of that file repeats everything in this section for
the app at hand, with its exact variable names. Whoever runs the server may:
Override any setting of a resource with an environment variable named
EXOTOOL_RES_<NAME>_<KEY> — the resource's name as the editor's Resources page shows it and
the field's key, both in upper case: EXOTOOL_RES_MAILER_SMTP_PASSWORD,
EXOTOOL_RES_MAPS_API_KEY. The environment always wins over the compiled value, so the
production database or mail account can be set on the server without a rebuild, and a secret
need never be in the file at all (set the variable and leave the field blank in the resource).
The deploy dialog and the head of backend.php list the names this app reads.
Give a value encrypted. A value that starts enc: is a ciphertext, which the server
opens with the key in EXOTOOL_RESOURCE_KEY (32 bytes, base64). The cipher is XChaCha20-Poly1305
(libsodium), and the ciphertext is bound to the resource and the field it is for. To make one on
the server, with PHP:
<?php // encrypt_setting.php path/to/backend.php RESOURCE key "the value"
list(, $backend, $name, $key, $value) = $argv;
preg_match('/\$EXOTOOL_RESOURCES = (array \(.*?\n\));\n/s', file_get_contents($backend), $m);
eval('$t = ' . $m[1] . ';');
$guid = $t[$name]['guid']; $stored = $t[$name]['fields'][$key]['stored'];
$k = getenv('EXOTOOL_RESOURCE_KEY') ?: base64_encode(random_bytes(32));
$nonce = random_bytes(24);
$ct = sodium_crypto_aead_xchacha20poly1305_ietf_encrypt($value, "$guid/$stored", $nonce, base64_decode($k));
echo "EXOTOOL_RESOURCE_KEY=$k\n", "EXOTOOL_RES_" . strtoupper("{$name}_{$key}") . "=enc:1:" . base64_encode($nonce) . ":" . base64_encode($ct) . "\n";
It prints the key to keep (once; reuse it for every value) and the variable to set. A value the key does not open is skipped with one line in the app's log and the next source is used.
Read the values from a secret store. With EXOTOOL_SECRETS_PROVIDER=aws the app asks AWS
Secrets Manager first, with gcp Google Secret Manager; a secret named <prefix><NAME>_<KEY>
(the prefix is exotool/ unless EXOTOOL_SECRETS_PREFIX says otherwise; / and - become _
in a Google secret id) holds the field's value, or a secret named <prefix><NAME> holds a JSON
object with the resource's keys. The credentials are the usual ones of the platform: on AWS the
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY variables or the instance's role, the region from
AWS_REGION; on Google the service account of the VM or Cloud Run service. A store that cannot
be reached is logged once and skipped.
The order in which a setting is looked up: the secret store, then the environment variable, then the value compiled in, then the default.
Where to set environment variables, by kind of host:
- A hosting account (cPanel, Plesk and the like): the account's PHP settings or a
.htaccesslineSetEnv EXOTOOL_RES_MAILER_SMTP_PASSWORD "..."— put it in a.htaccessabove the app's directory, since the app's own.htaccessis replaced at every deployment; the server must havemod_env. Some hosts offer an Environment variables page; those work too. - A server of your own: the PHP-FPM pool (
env[EXOTOOL_RES_...] = ...), the Apache virtual host (SetEnv), or the systemd unit of the web server. - AWS: Elastic Beanstalk's environment properties, an EC2 instance role with Secrets
Manager (
EXOTOOL_SECRETS_PROVIDER=aws), or Lightsail's web server configuration. - Google Cloud: Cloud Run's environment variables and secret references, or Compute Engine
with Secret Manager (
EXOTOOL_SECRETS_PROVIDER=gcp).
Keys that live in the browser — a Google Maps browser key, Stripe's publishable key — are not
secrets: a page can read them. They are secured on the provider's side, by restricting them to
your app's addresses (the preview's address under exotool.app among them while you develop).
8. The native iOS build
Beside the web app, the deploy dialog offers a native iOS app: your app's screens inside a small iOS program (a "shell"), delivered as an Xcode project in a zip file. You open it on a Mac, run it on an iPhone or iPad, and submit it to the App Store from Xcode. Exotool does not build, sign or submit the app: that takes a Mac and your own Apple developer account.
What the iOS app is. The app's pages, scripts, styles, images and library files travel inside
the app, so its screens open with no network. Its data stays on a server: the app calls the
same server program a web deployment uses, backend.php, at the address of your web host, or,
when the project has no host with a public address, at the project's preview. The completion
notice names the address the app was built for. So:
- Deploy the web app to your own host first, with the host's public address set, then generate the iOS app. An iOS app built against the preview is for trying things out: it shares the preview's data, and it stops working when the preview does.
- The iOS app and the web app at that address are one app with one set of data; a person can use either.
- When the host's address changes, or after any change to the app, deploy again and build the new project in Xcode: the pages inside an installed app do not update themselves.
- The server must run a build made since the iOS app existed (November 2026): only such a
backend.phpanswers calls from the iOS app. Deploying the web app again takes care of it.
Generating it. In the deploy dialog tick Native iOS app (with or without the web app) and
choose Deploy now. The completion notice offers <project>-ios-<date>.zip for download; the
link works for that editor session, and the project keeps its three newest zips.
Building it. You need a Mac with Xcode 16 or later; running on your own iPhone, TestFlight and the App Store need membership of the Apple Developer Program.
- Unpack the zip and open
xcodeproject.xcodeproj. - Select the project, then the target, then Signing & Capabilities, and choose your team.
- Choose a simulator or a connected iPhone and press Run.
- For TestFlight and the App Store: Product → Archive, then Distribute App.
What is in the project, and what you may change in Xcode.
- The name under the icon is the app's title. The bundle identifier is
exotool.<your user name>.<project>with anything but letters, digits and hyphens turned into hyphens; change it to one of your own (com.yourcompany.app) before you publish, and keep it the same from then on. - The version (1.0) and build number (1) are set in the target's General tab; the App Store wants a new build number for every upload.
- The icon is one 1024 × 1024 image drawn from your app's icon. Exotool keeps an app icon at
512 pixels at the most, so it is scaled up: for a sharp icon replace
AppIcon.pnginAssets.xcassetswith a 1024 × 1024 PNG that has no transparency. Info.plistholds the sentences iOS shows when the app first asks for the camera, the microphone or the photo library (an image or file upload in your app); reword them to say what your app does with them. App Store review reads them.- The project, the target and the built program are named
xcodeproject; people never see that name. iPhone and iPad are both supported, from iOS 16. - The shell is three Swift files with no other software in it.
www/is your app; do not edit it there, change the app in the editor and generate again.
How the app behaves, compared with the web app.
- Links to other web sites, and
mailto:andtel:links, leave the app and open in Safari or the system's own app. Alerts, confirmations and prompts are the system's. - Uploads work: the picker offers the photo library, files, and on a device the camera.
- An image or file your app stores shows in the iOS app as in the browser, provided the app shows it from the stored object handed to the device, as the language reference says, and never from an address kept as text.
- The keyboard shortens the page instead of pushing it up; the bar at the top stays put.
- A person is signed out when the app is closed and opened again: the app keeps its session in memory only, as a reloaded web page does. This is the main difference people notice today.
- The app's pages are not a "secure context" for the browser engine, so the few features that
need one are not available inside the shell: a camera or microphone stream read by script
(
getUserMedia), and service workers. A script that fetches a stored image's bytes (to draw it on a canvas, say) is refused as well; showing the image is not affected. - The "Built with Exotool" badge of the free plan is shown as in the web app.
Before you submit. App Store Connect asks about encryption (the app uses only the system's HTTPS), about the data the app collects, and for a privacy policy address: those answers are yours, for what your app does. Apple also expects an app to be more than a web site in a frame; the review is Apple's, and Exotool cannot promise its outcome.
How far it has been tested. The generated project builds in Xcode 26 for the simulator and for a device, and was exercised in the iPhone and iPad simulators against an app on Exotool's servers: screens, navigation, forms and the keyboard, saving and deleting data, photo upload and display, links out. It has not yet been run on a physical device by Exotool, nor taken through App Store review. Tell us what you find.
Without a Mac, the web app remains the way onto an iPhone: it installs to the home screen from Safari (Share → Add to Home Screen), with no store and no review.
9. When something fails
The deploy reports the step that failed in its own words; the usual ones:
- "Could not connect" to an FTP or SSH server: the server name or port is wrong, the host
allows only SFTP (or only FTP), or a firewall is in the way. Check the host's documentation for
the exact server name; many hosts use the site's domain or a
ftp./ssh.prefix. - "refused the sign-in": the user name or password (or key) is wrong, or the account has no shell/SFTP access. Hosting accounts often have a separate FTP user.
- "Target directory ... does not exist": the deploy asks whether to create it; say yes, or correct the directory in the host's resource.
- "Could not upload" a file: the directory is not writable by the FTP user, or the account is out of space.
- A repository refuses: the token lacks Contents: read and write (GitHub), the branch does not exist (make it first), or the user may not commit to that folder (Subversion).
- The app's page is blank or shows the source: PHP is not running for that directory, or
the host ignores
.htaccess(ask forAllowOverride All, or configure the index and PHP as section 3 says). - "failure on fopen of .../backend/data/heap.data", or nothing is saved: the
backend/datafolder is not writable by the web server. - Mail is not sent: the resource's settings; a host that blocks outgoing SMTP (use a mail API resource instead: SendGrid or Mailgun); the from-address not allowed by the account.
- A Map element shows nothing: a deployment needs a Maps resource with your own Google Maps key (the preview uses Exotool's); the key's referrer restriction must include your address.
- "This PHP has no libsodium" or a key does not open a value: see section 7; a value that cannot be opened is skipped and the compiled value is used.
Opening backend/backend.php in a browser answers No such protocol: that is the server
program telling you it is there and waiting for the app's requests. The app writes a line per
server-side error to backend/runtime.log (the editor's Help panel shows the preview's; on your
host, read the file).