Infrastructure troubleshooting

Start with the exact host ID, organization, and operation that failed. Check both the control-plane record and the machine itself. A working login, healthy API endpoint, or saved host key is not proof that the host can execute your request.

Host stays offline

1. Confirm the server is awake and its network connection works.
2. Check the agent process on the host; for the systemd setup in Connect your first server, use the commands below.
3. Check outbound HTTPS and WebSocket access to api.miosa.ai on port 443; an HTTP health check alone does not test WebSocket proxying.
4. Confirm that the service runs as the user whose ~/.osa/open_computers.toml contains the intended host configuration.
5. Check that the host has not been revoked, then confirm a fresh heartbeat in MIOSA.

systemctl status osa-opencomputers.service --no-pager
journalctl -u osa-opencomputers.service -n 50 --no-pager

Use sudo for logs if your account cannot read the system journal. osa opencomputers status can help inspect configuration, but its session output describes the runtime queried by that command. Confirm the actual service and control-plane heartbeat before concluding that a separate background process is offline.

Key saved but no connection

osa opencomputers login saves a host key, and connect is an alias for that command. Start OSA with host mode enabled; saving the credential alone does not start the host session. Follow the startup steps. Do not substitute a platform API key for the host key.

Identity rejected after reinstall

The server’s identity file must match the identity pinned when the host first connected. Preserve the configured fingerprint file, normally ~/.osa/open_computers.ed25519, along with the host configuration during upgrades. If the identity is lost, use the supported revocation and new-registration flow rather than copying another machine’s identity or disabling verification.

Command fails or appears stuck

• cmd is required: send the cmd field to the exec endpoint; command is not the request field.
• Permission denied or command unavailable: run the same command locally as the agent user and check its permissions, working directory, PATH, and supported operations.
• HTTP request remains open: exec streams by default; inspect SSE events until exec_result or exec_error, or use stream: false for a short command.
• Timeout or connection loss: save the returned job ID, inspect the job and local process, and establish the outcome before retrying.

curl --fail-with-body -sS 
  "https://api.miosa.ai/api/v1/opencomputers/hosts/$HOST_ID/exec/$JOB_ID" 
  -H "Authorization: Bearer $MIOSA_API_KEY"

Use IDs from your request and the same authorized organization context. Avoid retrying a deployment, payment, file mutation, or other operation with side effects merely because the client disconnected.

Commands work but desktop does not

A headless server can execute commands without providing a desktop. Verify the selected host advertises desktop support and has the required session and streaming backend. Check the agent’s current platform support; registering macOS or Windows does not guarantee a working desktop stream. For a MIOSA-managed Computer, follow desktop readiness instead of installing a desktop on an arbitrary OpenComputer.

Tunnel does not reach the application

1. On the host, confirm the application is running and responds on the intended local port.
2. Check the tunnel’s configured target port and the host’s connection.
3. Open the returned tunnel URL; do not construct a hostname yourself.
4. Confirm the viewer meets the tunnel’s access policy.

A public URL cannot make an unavailable local service healthy. Do not change a private tunnel to public solely to troubleshoot authentication. See the tunnel API for supported access modes.

BYOC resources exist but placement is unavailable

Cloud infrastructure existing is only one onboarding step. Verify provider acceptance, a successful live canary, and host readiness before expecting placement. Use the AWS or Google Cloud guide for the applicable gates. Registering a cloud VM as an OpenComputer does not create a BYOC worker pool.

Information to include when asking for help

Include the host ID, operation or job ID, timestamp with timezone, agent version, OS and architecture, and the relevant error text. State whether the command works locally as the agent user and whether the heartbeat is fresh. Remove API keys, host keys, identity files, private URLs containing tokens, and sensitive command output from shared logs.