App management and runtime states
This page is a day-to-day reference. For a complete task flow, see Create, import, export, and delete apps.
When to use this page
- You need to know whether an app task belongs in App Hub or the editor.
- You need to understand Start, Debugging, Paused, or Error.
- You want to set the home page, thumbnail, or auto-start apps for the current target.
- You need to know when saved authoring changes enter the runtime.
Where to go
| Task | Entry point |
|---|---|
| Create a Blank app, import Git, or register a Project | Create in the App Hub sidebar |
| Import a ZIP | Import in the App Hub sidebar |
| Open the editor or runtime page | Double-click an app card or use its context menu |
| Edit the name, export, or delete | App card context menu |
| Set the home page, thumbnail, and modules | Editor Settings → General |
| Build, Start, Debug, Pause, Continue, or Stop | Editor toolbar |
| Select a Runtime target | Target selector to the left of Build |
| Configure auto-start | System Settings → Runtime → Auto-start Apps |
Manage apps
Create or connect a project
- Blank app: enter a name and an empty workspace directory. You can also enable Qixin Code for a hosted private repository.
- Git import: enter a repository URL, optional branch, and empty workspace directory. Supply credentials only through the authentication prompt after a failure.
- Project: enter the root of an existing Theseus app. Registration does not copy the project.
- ZIP import: use for offline delivery or recovery. Inspect the imported app in the editor before running it.
Home page and thumbnail
- The home page is the first Page opened by Open runtime and Player. Choose it in Settings → General, or right-click a Page under Resources → Pages and set it as home.
- Upload, replace, or remove the App Hub card thumbnail in Settings → General.
- When no home page is set, runtime entry points ask you to configure one instead of guessing.
Export and delete
- Export creates a ZIP for delivery or backup. Preserve Git history separately in a remote repository.
- Delete can unregister the app only or also delete the workspace from disk. Confirm that a recoverable backup exists before deleting files.
Runtime controls
Runtime controls are in the editor toolbar, not on App Hub cards.
| State | Meaning | Available action |
|---|---|---|
| Stopped | No running instance | Build, Start, Debug |
| Starting | Preparing and starting | Wait, or Stop when necessary |
| Running | Normal runtime operation | Stop |
| Debugging | Running with debugging | Pause, Stop |
| Paused | Debugging is paused and still owns the runtime | Continue, Stop |
| Stopping | Shutdown is in progress | Wait for completion |
| Error | Load or runtime failure | Inspect the error; Stop first if a live instance exists, otherwise rebuild or restart |
Start and Debug prepare the required artifacts for the selected Runtime target, deploy them, and then start the app. The build platform for a remote target is selected from the target machine.
Save is not a runtime reload
Saving Page, Graph, Object, module, or Safety files updates the editor. It does not replace a running instance. For changes that affect runtime logic or device configuration:
- Save all changes.
- Stop the app.
- Build content that requires compilation.
- Start or Debug again.
- Verify the new behavior on the runtime page and against real device state.
Auto-start
Under System Settings → Runtime → Auto-start Apps, select from apps already available on the current Runtime target. Save the selection. Auto-start belongs to the target machine and does not move automatically with a ZIP or Git project.
What success looks like
- App Hub opens the correct project, with the expected name, home page, and thumbnail.
- The editor toolbar shows the intended Runtime target and runtime state.
- Start or Debug reaches Running, Debugging, or Paused when a breakpoint is hit.
- Stop returns to Stopped, and a new start uses the saved changes.
- Configured auto-start apps run the next time that RuntimeHost starts.
Common issues
Create says that the workspace is invalid
Blank app and Git import require an available empty directory. Register an existing app through the Project tab instead of creating over it.
Open runtime says that no home page is set
Choose one in Settings → General, or set it from the Pages resource context menu.
I saved, but the runtime page still has the old behavior
Check whether the app is still Running, Debugging, or Paused. Stop it, build if required, and Start or Debug again.
Build is unavailable in Error state
If the failure belongs to a loaded runtime instance, Stop first and wait for Stopped. If no runtime instance was loaded, review Problems and rebuild or restart.
The app is missing after switching to a remote target
The editor project remains local. The first Start, Debug, or deployment delivers it to the selected target; switching targets alone does not upload it.
How AI can help
AI can inspect current app configuration, errors, and change scope. For example:
The current app failed to start. Perform a read-only review of Problems, module settings, and recent changes. Separate build failure, missing deployment, and runtime failure. Do not start, stop, or deploy anything; give me a human troubleshooting order.
AI cannot choose a production target, approve downtime, or confirm workspace deletion for you.
What a person must confirm
- The app name, workspace, home page, and Runtime target belong to the correct project.
- Start, Debug, Stop, and auto-start are appropriate for current production conditions.
- Runtime changes pass normal, failure, and recovery tests.
- A Git or ZIP backup exists before deletion or replacement.