# Flyto2 Runtime

Experimental: the optional [locally paired HTTPS mobile companion gateway](docs/mobile-companion-gateway.md)
exports explicitly allowed installed Runtime capabilities to the Flutter
App without Flyto2 Cloud or the cybersecurity Engine. It does not grant
unrestricted host or physical robot control.

**Give ChatGPT secure access to your machine. Turn ChatGPT into Codex.**

ChatGPT can tell you what to change. **Flyto2 Runtime lets it actually do the work.**

No more copying files into chat, pasting commands into a terminal, sending the error back, and repeating the loop. Connect ChatGPT to your own machine over MCP and let it open your real project, edit code, run commands, test the result, use Git, and show you what changed.

Your machine stays the execution environment. You choose which project folders it can access.

## Why Flyto2 Runtime?

Without a local runtime, coding with ChatGPT often looks like this:

```text
ChatGPT suggests code
        ↓
you copy it into the repo
        ↓
you run the command
        ↓
it fails
        ↓
you paste the error back
        ↓
repeat
```

With Flyto2 Runtime:

```text
You ask ChatGPT
        ↓
ChatGPT opens your project
        ↓
edits → runs → tests → fixes
        ↓
shows you the result
```

That is the point of Flyto2 Runtime: **close the loop between the AI and your machine.**

## What it gives ChatGPT

Once connected, ChatGPT can work inside an approved local workspace and:

- read and edit your project files
- run terminal commands, tests, builds, Git, and package scripts
- keep long-running work alive without making you babysit the terminal
- review what changed before you continue
- work through OAuth instead of exposing an unauthenticated local shell
- optionally hand work to local coding agents or connect to Flyto2 Cloud

The normal model-facing surface stays intentionally small. Runtime handles process recovery, durable execution, filesystem events, service lifecycle, and tunnel supervision behind the scenes.

## Quick start

**On macOS or Windows, use the packaged download.** Get it from the
[Flyto2 Runtime download page](https://github.com/flytohub/flyto2/blob/main/products/runtime/README.md).
The macOS disk image and Windows x64 ZIP include their own Node.js,
production dependencies, and cloudflared, so nothing needs to be installed
first. On Windows, extract the ZIP and double-click `Install.cmd`. The rest
of this section installs from source instead.

Requirements: Node.js 22.19 or newer, below 27 (the installer from
[nodejs.org](https://nodejs.org) is fine). Nothing else needs to be installed
first: not pnpm, not Homebrew, not cloudflared, and no administrator password.

1. Download this repository: **Code → Download ZIP** on GitHub, then open the
   ZIP. (Or `git clone https://github.com/flytohub/flyto-runtime.git`.)
2. Double-click `Install.command` on macOS or `Install.cmd` on Windows.

The first run installs dependencies and builds, which takes a minute or two,
then walks you through setup and installs the background service and Desktop
launchers, so you do not need to keep a terminal window open. Running it again
later skips setup; to change it, double-click **Setup Flyto2 Runtime** on the Desktop.

On macOS, if it says the file cannot be opened because Apple cannot check it,
open **System Settings → Privacy & Security** and choose **Open Anyway**.

How the launcher gets its tools: pnpm comes from your PATH, else
`corepack pnpm`, else npm runs the pinned version; it never runs
`corepack enable`, which needs write access next to node. If you choose the free
Cloudflare URL, setup uses an existing cloudflared, or the one you downloaded
into Downloads, or fetches the official release, and runs it only after checking
Cloudflare signed it. It is kept in Runtime's own folder.

From a terminal the same steps are:

```bash
cd flyto-runtime
./"Flyto2 Runtime.command" install
```

## Connect ChatGPT

ChatGPT needs a public HTTPS URL that reaches your local Runtime. During setup, choose **ChatGPT**, then either:

- **Create a free Cloudflare URL for me** (the default). No account or domain is needed. Setup installs `cloudflared` if you allow it (Homebrew on macOS, winget on Windows), keeps a quick tunnel running in the background, and fills in its `https://<random>.trycloudflare.com` URL. That URL changes whenever the tunnel restarts, for example after a reboot. Runtime follows the new URL by itself; you then give ChatGPT the new one, which `flyto2-runtime doctor` or `flyto2-runtime service quick-tunnel status` shows.
- **Use my own HTTPS URL** for an address that never changes: a named Cloudflare tunnel on your own domain, a reverse proxy, Tailscale Funnel, or an ngrok domain pointed at `http://127.0.0.1:7676`.

```text
https://your-runtime-host.example.com
```

Flyto2 Runtime exposes MCP at:

```text
https://your-runtime-host.example.com/mcp
```

Setup can also generate an upload-ready ChatGPT Plugin ZIP for you.

Choose:

```text
Generate an upload-ready ChatGPT Plugin ZIP now?
Yes / No
```

If you choose **Yes**, Runtime creates the ZIP from **your own configured MCP URL**. Nothing is hard-coded to a Flyto2 hostname.

If you choose **No**, you can create it later:

```bash
flyto2-runtime plugin build
```

The ZIP contains only portable Plugin metadata, MCP configuration, and a small Runtime skill. It does **not** contain your Owner password, OAuth tokens, tunnel credentials, or `auth.json`.

Need a custom package for another machine or deployment?

```bash
flyto2-runtime plugin build \
  --url https://runtime.example.com/mcp \
  --name my-runtime \
  --server-name my-runtime \
  --display-name "My Runtime" \
  --output ./my-runtime-plugin.zip
```

Upload the ZIP in ChatGPT Plugins, approve the OAuth connection, and start working.

## The workflow

A normal session is intentionally simple:

```text
ChatGPT
   ↓
OAuth + MCP
   ↓
Flyto2 Runtime
   ↓
your approved local workspace
   ↓
files / Git / terminal / tests / builds
```

Flyto2 Cloud is optional. Flyto2 Runtime works standalone.

### Composable execution capabilities

Runtime also exposes a provider-neutral `flyto2.execution.v1` capability
contract so another Flyto2 product can compose machine-local execution without
importing Runtime internals. The standalone service remains the default product:
it owns workspace admission, filesystem access, processes, Git, durable
operations, credentials, and local provider configuration.

Capability registration is grouped into Runtime-local bundles defined in
[`src/flyto2/capability-bundles.ts`](src/flyto2/capability-bundles.ts): `read`,
`execution`, `mutation`, `observability`, plus the optional `agent` bundle.
Standalone Runtime explicitly enables its core bundles. The `agent` bundle is
added only when subagents are configured, and is implemented by
[`src/flyto2/agent-capabilities.ts`](src/flyto2/agent-capabilities.ts) over the
existing local-agent daemon rather than embedding provider SDKs into the wire
contract.

Core, Cloud, or another host may select a smaller bundle set through
[`src/flyto2/capability-runtime.ts`](src/flyto2/capability-runtime.ts). The live
manifest publishes only capabilities that are actually registered. Cross-language
consumers should use the generated JSON Schemas under
[`schema/flyto2.execution.v1/`](schema/flyto2.execution.v1/) instead of importing
Runtime's TypeScript implementation types.

When Core or another same-machine process needs to invoke those capabilities,
Runtime exposes a localhost-only bridge at
`http://127.0.0.1:<runtime-port>/flyto2/capabilities/v1`. `GET /manifest` returns
the live capability manifest and `POST /invoke` accepts one
`flyto2.execution.v1` invocation envelope. The bridge requires the persistent
same-user token stored at `<stateDir>/capability-bridge.token` (0600 on POSIX)
in the `x-flyto2-capability-token` header. Both the TCP peer and Host header must
be loopback, so the public MCP/tunnel URL cannot be used as an execution bridge.

### Durable continuation with MCP Events

Runtime supports the ChatGPT MCP Events draft (`2026-07-28`) on the same
authenticated `/mcp` endpoint as its tools. The event catalog exposes
`process.completed`, `process.failed`, `process.stalled`, and
`task.needs_attention`. A ChatGPT chat can subscribe with webhook delivery so a
long-running Runtime process can call the subscribed chat back when meaningful
state changes instead of requiring continuous polling.

Subscriptions are persisted in Runtime state across restarts. Callback URLs are
verified before activation, must use public HTTPS destinations, are re-resolved
for every connection, and receive Standard Webhooks HMAC signatures. Private,
loopback, link-local, multicast, documentation, and other non-public addresses
are rejected. Runtime does not follow callback redirects.

MCP Events are the push path, not the only recovery path. Process evidence,
Host Task checkpoints, `process_status`, and `open_workspace` recovery remain
durable fallbacks. If a terminal process fails or becomes orphaned, Runtime
moves the owning ChatGPT task to `needs_attention` rather than leaving it looking
indefinitely active.

Long-task debugging is structured rather than log-only. `background_task status`
and `open_workspace` recovery can include a bounded diagnosis projection with a
stable reason code, current phase, current process snapshot, correlation IDs,
and a recent task timeline. The projection is derived from durable Runtime
state and shallow events; raw source text and full command output remain in
local evidence instead of being copied into the timeline.

Those states are interpreted by one Runtime operational model rather than
tool-specific state rules. Host Tasks, processes, durable operations, and MCP
callback deliveries retain separate state families, while shallow events share
one correlation envelope across task/workspace/process/operation/invocation/
event IDs. Existing event history is reconstructed into the same envelope so
upgrades keep old recovery evidence useful.

Reason codes distinguish an actually running process, suspected stall,
non-zero exit, signal/orphan recovery, host continuation, and MCP event callback
delivery problems. This makes it possible to tell whether time was spent in a
test/build/command, waiting for ChatGPT to resume, or failing to deliver a
callback without searching unrelated logs.

## Desktop and background service

Flyto2 Runtime is designed to stay available after setup.

**macOS:** a LaunchAgent keeps Runtime running in the background.

**Windows:** Task Scheduler starts Runtime at login and a small supervisor restarts it if the process exits unexpectedly.

Useful commands:

```bash
flyto2-runtime doctor
flyto2-runtime service status
flyto2-runtime service start
flyto2-runtime service restart
flyto2-runtime service stop
```

The interactive launcher also includes setup, diagnostics, and **Export ChatGPT plugin**.

### Updating a machine you are not sitting at

```bash
flyto2-runtime service self-update
flyto2-runtime service self-update status
```

`self-update` returns immediately, so ChatGPT or any other connected host can run it through its shell tool. A separate job owned by launchd (macOS) or Task Scheduler (Windows) then:

1. fetches `main` from `github.com/flytohub/flyto-runtime` (the source is fixed; it cannot be pointed elsewhere);
2. refuses the commit unless every CI check on it finished green;
3. builds it in its own directory, never in your checkout;
4. switches the background service to that build and restarts it behind the `/healthz` gate, rolling back to the previous build if the check fails.

The connection drops for a few seconds during the restart. OAuth approvals survive it, so the host reconnects without asking for the Owner password again, as long as its URL does not change. Use a named Cloudflare tunnel with a fixed hostname; a quick `trycloudflare.com` tunnel gets a new URL whenever it restarts.

## Security

Flyto2 Runtime is powerful because it can operate on your machine. Treat a connected AI client like a trusted coding partner.

Access is restricted to the workspace roots you approve. Remote MCP access uses OAuth. Keep your Owner credential, tunnel credentials, and `auth.json` private.

Flyto2 Runtime does not pretend shell execution is a full OS sandbox. The security boundary is explicit workspace scope, authenticated access, and the permissions of the local user running Runtime.

See [Security Model](docs/security.md) for details.

## Built for real local work

The parts you should not have to think about are handled by Runtime: long-running commands, lost responses, process continuation, filesystem changes, service restarts, health checks, MCP compatibility, and recovery.

Those are implementation details, not the product.

The product is simpler:

> **Ask ChatGPT to work on your project, and let it finish the job on your machine.**

## Documentation

- [Setup Guide](docs/setup.md)
- [ChatGPT Coding Workflow](docs/chatgpt-coding-workflow.md)
- [Configuration Reference](docs/configuration.md)
- [Security Model](docs/security.md)
- [Troubleshooting](docs/gotchas.md)

## Development

```bash
pnpm typecheck
pnpm lint
pnpm test
pnpm build
flyto-index verify . --full-scan --strict --json
```

## Roadmap

Flyto2 Runtime will also connect with **Flyto2 Core** for reusable capabilities such as browser testing, crawling, automated validation, security testing, and agent-driven workflows.

## License

MIT.

Flyto2 Runtime is based on [Waishnav/devspace](https://github.com/Waishnav/devspace). The original copyright and license notice are preserved in [LICENSE](LICENSE).