Troubleshoot by task

Turn error symptoms into actionable troubleshooting steps

This guide covers first connections, SSH keys, VNC, MLX inference services, CI, and order issues on VMMini Cloud Mac Nodes. Start with the basic checks for your symptom, then submit a ticket with logs and a time range.

This page will never ask for passwords, private keys, or recovery phrases. For existing orders, sign in to the console and submit a ticket to link the order and node automatically.

Submit a console ticket Read the getting-started guide
Support runbook Locate, collect, submit
Clear path
03 Troubleshooting stages
Symptom Connection, build, storage, service, or order
Evidence Time, commands, exit codes, and redacted logs
Action Self-recovery or an order-linked ticket
Node coverage Singapore · Japan (Tokyo) · South Korea (Seoul) · Hong Kong
Quick search

Enter an error message, tool name, or task goal

Search matches this page’s guides, troubleshooting flows, and terminology. If an error contains an order ID, hostname, or address, redact it before searching.

Connections & access

Verify the delivery details before choosing a connection method

Connection issues usually come from the address, port, key permissions, client cache, or local network path. Never skip host-fingerprint verification.

SSH: Start with the host fingerprint

Have the delivered host address, SSH port, username, and private key matching the public key ready. Keep the private key only on a controlled device or in a key store; never paste it into a ticket.

  1. First connection:Compare the host fingerprint shown in the console with the client prompt line by line.
  2. Permission check:Make sure the private key is readable only by the current user and that the public key has not been damaged by line breaks.
  3. Disconnection troubleshooting:Check the local network, DNS or address, port reachability, and the username-to-key mapping in order.
  4. Collect evidence:Keep verbose output with timestamps, but remove sensitive parts of the address, username, and key path.
ssh -vvv -p <port> <user>@<host>

VNC: Verify the session and display state first

You need the node address, port, connection credentials, and an available graphical session. Store connection credentials in a password manager; never put them in a script repository or build log.

  1. First login:Check the system version, disk capacity, time zone, keyboard layout, and current network status.
  2. Black screen:First confirm that the graphical session is still running, then check the client color depth and scaling settings.
  3. Frequent disconnections:Record when they occur, how long they last, the local network type, and whether SSH access works at the same time.
  4. Display lag:Lower the display quality for comparison testing; do not treat a single instance of client lag as a node failure.

Remote desktop: Validate the client and node separately

First confirm that the client supports the delivered connection method, then verify the address, port, and session credentials. Do not repeatedly try expired credentials, as this can obscure the real cause.

  1. Local side:Disable the proxy or switch networks for comparison, and record the client version and exact error text.
  2. Node side:If SSH works, check the graphical service process, available disk space, and system load.
  3. Network path:Compare connection results across different networks to determine whether the issue occurs only on one path.
  4. Submit a ticket:Provide the order ID, node, time of occurrence, and redacted screenshots. Do not provide the connection password.
MLX inference support

Locate model-service issues with five checkpoints

First verify that the runtime and model files are complete, then check the listening address, health endpoint, and logs. Expose only the ports the workload needs and restrict the source range.

01

Verify the environment

Record the macOS version, Python version, virtual-environment path, MLX package versions, and available disk space. Confirm the task runs on a VMMini M4, M4, 16GB, 256GB SSD Cloud Mac Node rather than carrying over shared-environment parameters.

02

Prepare the model

Verify the model-file path, file count, checksums, and required space. Keep models and caches in clearly defined directories so download jobs and service processes do not write to the same temporary location.

03

Check listening

Bind to the local address first for validation, then expand the listening range only as needed. Confirm the port is not occupied by another process; expose only necessary ports and sources externally.

04

Run a health check

Call the health endpoint locally on the node and record the HTTP status, response time, and response body. If local access works but external access fails, investigate ports, access rules, and network paths instead of repeatedly restarting the model.

05

Collect reproducible logs

Keep a redacted version of the startup command, stdout, stderr, exit code, model name, and occurrence time. Remove access tokens, request bodies, and user data before submitting logs.

Local health check

Verify the service from the loopback address first

Replace the port and health path in the command with the actual values. The health endpoint should be lightweight and stable, and should not trigger a full inference task.

curl --fail --show-error \
  --max-time 10 \
  http://127.0.0.1:<port>/health
Continuous integration support

Make runners revocable, cleanable, and reproducible

A self-hosted runner is more than a long-running process. Registration, credentials, caches, artifacts, and revocation actions all need clear owners and retention boundaries.

01

Register the runner

Use a dedicated service account and separate work directory. Record the runner name, labels, project, and registration time. Labels should describe real capabilities so multiple projects are not mistakenly scheduled in the same work directory.

Definition of done The queue can identify the runner, and a test job returns a clear exit code.
02

Isolate project credentials

Separate tokens by project and environment, preferably using controlled secret storage or runtime environment variables. Never write long-lived credentials to the repository, runner configuration backups, or downloadable artifacts.

Definition of done Job logs contain no secret values, and revoking one project does not affect others.
03

Manage build caches

Use separate directories for dependency caches, DerivedData, temporary files, and archives. When disk space is low, identify what is growing first and clean by project; never delete directories used by active jobs.

Definition of done Cache paths are traceable, and cleanup does not delete final artifacts.
04

Retain build artifacts

Record the commit version, build number, toolchain version, and checksum information for each artifact. After the job ends, move files that must be retained out of the runner work directory so cache cleanup will not remove them.

Definition of done Failed logs and successful artifacts can both be tied to the same build.
05

Safely revoke the runner

Stop accepting new jobs, wait for the current job to finish, then revoke the registration token from the project and remove the service. Finally, verify that the work directory, cache, and credentials were handled according to the data-migration plan.

Definition of done The control plane no longer schedules jobs, and no reusable registration credentials remain on the node.
Terminology glossary

Eight terms to standardize first

Consistent terminology helps keep node, software, network, and billing issues separate during troubleshooting.

Physical node
The Mac Mini M4 host actually delivered for an order. It is a Cloud Mac hardware node, not a virtual machine instance.
Dedicated
The order uses the physical machine’s processor, memory, and local storage resources without sharing the same compute resources with other rental orders.
VNC
A remote-display method for accessing the macOS graphical interface. Troubleshooting requires separating the graphical session, client, and network path.
self-hosted runner
A CI execution endpoint registered and maintained by a team. It pulls jobs, runs builds, and returns logs and artifacts.
MLX
A machine-learning toolkit for Apple Silicon, used for model preparation, inference experiments, and service validation.
Build cache
Data retained to reduce repeated downloads and compilation, including dependency caches, DerivedData, and tool-generated intermediate files.
Node
The service region where the physical host is located. The current directory includes nodes in Singapore, Japan (Tokyo), South Korea (Seoul), and Hong Kong.
Billing period
The usage period selected for an order, available by day, week, month, or quarter. The console order record determines the period, start time, and expiration time.
Troubleshooting decision tree

Choose the next step by symptom; do not change several settings at once

Change one condition at a time and record the result. Resetting multiple settings at once erases the fault boundary and prevents the support team from reproducing the issue.

NET Unable to connect to node Timeout, connection refused, changed fingerprint, or credential mismatch
Check first

Whether the order is valid, the address and port match the current node, the local network can reach the target port, and the username matches the key.

Collect information

Time of occurrence, client version, exact error text, redacted verbose connection output, and comparison results after switching networks.

When to submit a ticket

Stop trying and submit a ticket if two independent networks both fail to connect, or if the host fingerprint differs from the console record.

BLD Build failed Dependency resolution, compilation, signing, or runner job failure
Check first

Whether the commit, lockfile, toolchain version, environment variables, runner labels, and work directory match the latest successful build.

Collect information

The complete exit code, logs around the failed stage, build command, tool versions, and comparison results after clearing the cache.

When to submit a ticket

Submit a ticket when the same commit and configuration still fail consistently in a clean work directory and the logs point to a node-system or disk issue.

DSK Insufficient disk space Models, build caches, logs, or archives continue to grow
Check first

Measure usage by directory and distinguish models, dependency caches, DerivedData, logs, temporary files, and final artifacts that need to be moved.

Collect information

Free filesystem space, largest directories, when growth began, active jobs, and the latest cleanup record.

When to submit a ticket

Submit a ticket if the filesystem report clearly conflicts with directory totals, or if space is not released after deleting cleanable content.

SRV Service unavailable The process exists, but the health endpoint times out or cannot be reached externally
Check first

Process status, listening address, port usage, local health check, available memory, and recent stderr output.

Collect information

A redacted startup command, process exit code, local and external request results, response time, and the service-log time range.

When to submit a ticket

Submit a ticket if local requests also fail and service logs show a system-level error, or if multiple services become unavailable at once.

ORD Console order issue Order status, period, node, or billing record does not match expectations
Check first

Whether the order ID, selected VMMini M4 configuration, node, billing period, add-ons, and payment record belong to the same order.

Collect information

Order ID, status shown on the page, time of occurrence, steps taken, and redacted screenshots. Do not submit complete payment credentials.

When to submit a ticket

Submit an order-linked ticket from the console if the discrepancy remains after refreshing and signing in again, or if the order cannot proceed.

Service availability

Nodes run year-round; verify incidents against order records

VMMini nodes are designed to run normally 365 days a year. Specific order availability and incident records are determined by the console’s real-time response and linked records.

Four-node coverage All nodes in the directory are available for VMMini M4 orders; the console provides current availability in real time.
View order events

Singapore

A good first path to test for Southeast Asian teams and workloads.

Japan (Tokyo)

Suitable for comparing access to Japanese or East Asian code sources.

South Korea (Seoul)

Suitable for connection testing from Northeast Asian access paths.

Hong Kong

Useful for comparing routes from southern China and Southeast Asia.

How to tell whether this is a service incident: Retest the connection over two independent networks, then verify the node’s local service and the user’s software state. An external network path, user configuration, or single-process failure should not be treated as physical-node unavailability.
Submit a support request

What a troubleshooting-ready ticket should include

For existing orders, use a console ticket first so the node, period, and incident records can be linked. If you cannot sign in, contact the service team at support@vmmini.com.

Request information checklist

Six required details

No account secrets
  1. 01
    Order ID

    Provide the order ID from the console; do not substitute other personal information from a screenshot.

  2. 02
    Relevant node

    Specify Singapore, Japan (Tokyo), South Korea (Seoul), or Hong Kong, along with the corresponding host.

  3. 03
    Time of occurrence

    Provide the time zone, first occurrence, latest reproduction time, and whether the issue is ongoing.

  4. 04
    Reproduction steps

    List commands, input conditions, expected results, and actual results in operation order.

  5. 05
    Exact error text

    Keep the exit code and key context; do not write only “unusable” or “build failed.”

  6. 06
    Redacted logs

    Remove passwords, private keys, access tokens, user data, and unnecessary complete addresses before attaching logs.

No order or unable to sign in

Email support@vmmini.com, and state the issue type in the subject. The email must also include the node, time, reproduction steps, and redacted logs.

View contact options

Do not submit these items

Passwords, private keys, access tokens, recovery phrases, complete payment credentials, unredacted user data, or unrelated repository contents.

Read our data privacy policy
Bring evidence into your ticket

For existing orders, continue troubleshooting with the linked node record

Prepare the order ID, node, time of occurrence, reproduction steps, and redacted logs. Use console tickets for technical and order issues; pre-sales questions can also be sent to the sole support email.

Submit a console ticket Read the getting-started guide