pan-fly

Fly.io Operations for Overdeck

Use this skill when the task involves Fly.io-backed Overdeck remote workspaces or Fly-hosted application instances.

What This Covers

• pan remote setup / pan remote status
• Fly-backed remote workspaces created by Overdeck
• Fly Machines lifecycle: create, inspect, start, stop, destroy
• SSH/exec into Fly machines
• Port proxy/tunneling with fly proxy
• Debugging deployed apps on Fly
• Verifying what version is actually deployed

First Principles

1. Prefer Overdeck commands for Overdeck-managed remote workspaces.
2. Use Fly CLI/API when Overdeck does not expose the needed detail.
3. For deployed app version checks, prefer non-destructive verification:
   • public health/bootstrap/version endpoints
   • fly ssh console + read-only inspection
   • status/metadata commands
4. Never perform destructive Fly actions unless the user explicitly asked.

Overdeck Remote Workspace Workflow

Initial setup

pan remote setup
pan remote status

Key config lives in ~/.overdeck/config.toml under [remote] and [remote.fly].

Important fields:

• app
• org
• region
• vm_size
• vm_memory
• image
• auto_stop
• auto_stop_timeout

Reference: docs/fly-provider.md

Create and inspect remote workspaces

pan workspace create --remote PAN-42
pan remote status
pan workspace list

Start/stop/delete a remote workspace

pan workspace start PAN-42
pan workspace stop PAN-42
pan workspace delete PAN-42

Fly CLI Patterns

If flyctl is required, check it first:

fly version
fly auth whoami

Useful commands:

fly status -a <app>
fly machines list -a <app>
fly machine status <machine-id> -a <app>
fly ssh console -a <app>
fly ssh console -a <app> -C "<command>"
fly logs -a <app>
fly proxy <local>:<remote> -a <app>

Determining Deployed Version

Prefer this order:

1. Public bootstrap/health/config endpoints

Many apps expose a bootstrap/config endpoint that includes version/build metadata.

Examples:

curl -fsSL https://<app>.fly.dev/healthz
curl -fsSL https://<app>.fly.dev/__openclaw/control-ui-config.json

2. Inspect the deployed frontend bundle

If the app serves a JS bundle and the bootstrap endpoint is not obvious, inspect the HTML and referenced assets for version metadata.

3. SSH and inspect runtime directly

If public endpoints do not expose the version:

fly ssh console -a <app> -C "openclaw --version"

Or inspect package metadata:

fly ssh console -a <app> -C "node -p 'require(\"./package.json\").version'"

Use read-only inspection first. Do not restart, deploy, or mutate state unless requested.

OpenClaw-on-Fly Notes

For the personal OpenClaw fork deployment, a Fly config like fly.eltmon.toml typically identifies the app name and runtime shape.

Useful checks:

curl -fsSL https://<app>.fly.dev/healthz
curl -fsSL https://<app>.fly.dev/__openclaw/control-ui-config.json
fly status -a <app>
fly ssh console -a <app> -C "openclaw --version"

If the Control UI bootstrap endpoint returns JSON with serverVersion, treat that as the deployed server version.

Troubleshooting

Not authenticated

fly auth whoami
printenv | grep '^FLY_'

If needed:

• FLY_API_TOKEN
• fly auth login

Remote unavailable in Overdeck

Run:

pan remote status

Then inspect:

• config in ~/.overdeck/config.toml
• whether flyctl is installed
• whether auth is valid

Tunnel/proxy issues

fly proxy 4173:4173 -a <app>
fly ssh console -a <app> -C "ss -tlnp"

Machine exists but app is unhealthy

fly status -a <app>
fly machines list -a <app>
fly logs -a <app>

Safety Rules

• Never delete machines, apps, or volumes unless explicitly requested.
• Never deploy or restart just to inspect version/state.
• Prefer additive diagnosis: status, logs, health endpoints, bootstrap JSON, SSH read-only commands.
• For Overdeck-managed remote workspaces, do not bypass Overdeck when a Overdeck command exists.

Related References

• docs/fly-provider.md
• src/lib/remote/fly-provider.ts
• src/cli/commands/remote/setup.ts
• src/cli/commands/remote/status.ts