Locate by command and error keyword

From connecting to a build node to delivering iOS build artifacts.

For first-time users, release engineers, and CI/CD maintainers. Enter a command, error snippet, or task name to narrow the scope first, then verify each expected output.

Showing 8 action entries.

Rent a Mac build node now Contact the technical team
RUNBOOK / OAK-06 Build node acceptance index
01
Connection entry pointsSSH · VNC · Screen Sharing
Check
02
Build environmentXcode · Signing assets · Cache
Check
03
Task executionRunner labels · Isolated directories
Check
04
Delivery resultsarchive · export · logs
Archive
Troubleshooting principle Change one variable at a time
Action entry points

Enter the right dossier by symptom

Each entry provides checks, commands, or observation metrics. Filtering only changes the entries below; it never hides the complete operating chapters.

CONNECTION

First connection and local checks

Get connection details from the console and verify SSH, the graphical interface, the password, and the time zone.
BUILD

Automated iOS archiving and export

Verify the Xcode toolchain, signing inputs, archive path, and build artifact retention rules.
AUTOMATION

CI/CD runner integration

Separate platform registration, node labels, concurrency limits, and the working directory for each task.
DISPLAY

Remote display tuning

Isolate interaction lag layer by layer across resolution, color, frame rate, and network jitter.
GLOSSARY

Build environment glossary

Standardize the meanings of node, runner, cache, and signing assets to reduce ambiguity during collaboration.
DIAGNOSTICS

Command-based troubleshooting

Organize network, disk, Xcode, and signing issues by command, expected result, and troubleshooting branch.
ESCALATION

Prepare a support ticket

Include the region, time, task ID, and redacted logs so support can reproduce the path.
STORAGE

Cache and artifact storage checks

Separate rebuildable caches, archive results, and release artifacts that must be retained.
First connection

Verify the entry point before changing node settings

Use the current instance details in the console as the source of truth. Do not copy addresses or credentials from old tickets, chat messages, or historical scripts.

Recommended order · 4 steps

First-login acceptance checklist

Establish one stable connection first, then check the password and time zone. Do not change the network, resolution, and authentication method at the same time, or it will be difficult to identify the cause.

  1. 01

    Read the current connection details from the console

    Verify the node region, host address, port, username, and instance status. Store credentials only in a controlled password manager, never in a code repository or build log.

  2. 02

    Verify the basic connection with SSH first

    Run ssh -v user@host to view the resolution, handshake, and authentication stages. If it times out before the connection is established, check the local network and port first; if authentication fails, verify the username and current credentials.

  3. 03

    Choose a graphical connection for the task

    Use VNC or Screen Sharing when you need to operate the Xcode interface. Keep the default resolution and color settings initially, then tune image quality after confirming that the keyboard, mouse, and clipboard work correctly.

  4. 04

    Complete the first-login checks

    Change the initial password, run date and systemsetup -gettimezone to verify the time and time zone, and confirm that the project directory belongs to the current task user.

Automated builds

Record build inputs and artifact paths in the dossier

A reproducible iOS build requires a fixed toolchain, project entry point, signing assets, archive parameters, and export location. Recording only “build failed” is not enough for review.

01 / TOOLCHAIN

Lock the Xcode command-line tools

Run xcode-select -p and xcodebuild -versionto confirm the developer directory and Xcode version actually used by the script. Run both again after switching versions; do not rely on the terminal window title.

02 / SIGNING

Separate certificates, private keys, and provisioning profiles

Limit access to signing assets by project and environment. After importing them, use security find-identity -v -p codesigning to check available identities, and never output certificate passwords to pipeline logs.

03 / ARCHIVE

Define the workspace, scheme, and archive path

The script should explicitly specify the workspace or project, shared scheme, configuration, and -archivePath. Do not rely on a temporary selection from the previous Xcode graphical session on the build machine.

04 / EXPORT

Save results and logs together

Generate artifacts with -exportArchive and a version-controlled export configuration. Save the archive, export result, build log, and commit identifier; retain redacted diagnostic information even when the build fails.

BUILD RECORD Archive command skeleton 
xcodebuild \
  -workspace App.xcworkspace \
  -scheme App \
  -configuration Release \
  -archivePath "$PWD/output/App.xcarchive" \
  clean archive
InputsCommit identifier, dependency lockfile, Xcode version, scheme
OutputsArchive directory, export directory, raw log, task ID
Retain on failureExit code, first error section, environment versions; do not retain sensitive values
CI/CD integration

Runner registration is only the beginning; isolation rules determine whether it can run reliably over time

OakVM nodes are dedicated physical machines, not virtual machines. Scale concurrency by adding dedicated nodes; tasks on the same node should still have clear queue, label, and working-directory boundaries.

GITHUB ACTIONS

Route projects to designated nodes with labels

  • Create a self-hosted runner at repository or organization scope and record its registration ownership.
  • Use region, chip, and purpose labels; for example, separate project releases from routine tests.
  • Route workflows through runs-on with exact matching; do not use generic labels with ambiguous meanings.
  • After each task, clean up temporary keychains, temporary directories, and environment variables needed only for that run.
GITLAB CI

Define runner scope and task labels clearly

  • Confirm whether the runner belongs to an instance, group, or project to prevent unrelated projects from executing jobs.
  • Declare tags in the job and disable acceptance of untagged jobs when not needed.
  • Use project-level cache keys to prevent incompatible results from different branches or applications being shared.
  • Retain the job ID, commit identifier, and runner name to match the node logs.
GENERIC RUNNER

Define the lifecycle of a generic runner first

  • Put the registration script, service startup method, and log location in the team runbook.
  • Create an independent working directory for each task, then handle caches and artifacts according to the retention policy.
  • Set a clear concurrency limit for each physical node to prevent multiple heavyweight archive tasks from competing for resources.
  • Nodes operate normally 365 days a year; task retries should still have an upper limit and record the reason for failure.

Isolation baseline:Manage project directories, build caches, signing assets, and artifact directories separately. Do not clear an entire node as a routine isolation measure, and never let two projects share the same writable signing directories.

Remote display

Troubleshoot from display load to the network path

Perceived lag in VNC and Screen Sharing does not necessarily come from node compute load. Test in a fixed order to distinguish encoding pressure, local network jitter, and background task contention.

  1. 01

    Lower the resolution

    Lower the display resolution to the minimum needed for the current task and disable unused extra display areas. If responsiveness improves noticeably, the issue is more likely related to the amount of screen encoding.

    Observe pointer and window dragging
  2. 02

    Reduce color depth and dynamic content

    Pause video, animated previews, and continuously refreshing monitoring windows. Disable unnecessary simulator views during builds and check whether static editing becomes stable again.

    Compare static and dynamic views
  3. 03

    Set a realistic frame-rate target

    Code editing and release operations generally do not require a high frame rate. Prioritize input responsiveness and text clarity, then gradually increase visual smoothness.

    Record changes in input latency
  4. 04

    Check for network jitter

    Run continuous short-latency tests against the node address, focusing on variation and packet loss rather than only the single lowest value. After switching local networks, retest with the same number of samples.

    Keep a sample summary
  5. 05

    Confirm the team sharing method

    Keep one primary operator for each task; other members should collaborate through build logs and artifact records. Multiple people operating the graphical interface at once increases context conflicts.

    Identify the current operator
Glossary

Align terminology before discussing configuration and boundaries

The following terms are used across OakVM pages, the console, and support communications. They describe delivery models and workflows and do not imply endorsement by any third-party platform.

Physical node
A physical Apple Silicon device that directly hosts macOS and build tasks; it is the compute unit assigned to an order.
Dedicated
During the rental period, the node’s compute resources are used by the current order and the physical machine is not shared with other customers’ tasks.
Cloud Mac
A Mac environment deployed in a data center and accessed over a network for graphical work, command-line builds, and automation tasks.
Non-virtualized
The order delivers a dedicated physical machine, not a virtual compute instance split from a shared host.
VNC
One method for remotely viewing and operating the macOS graphical interface; the experience is affected by resolution, screen changes, and network jitter.
self-hosted runner
A runner agent registered with a CI/CD platform that accepts and executes pipeline jobs on an owned or rented node.
Build cache
Data retained to reduce repeated downloads or compilation, such as dependency caches and DerivedData; it should be invalidatable and rebuildable.
Signing assets
Certificates, private keys, provisioning profiles, and related access permissions required to sign an application; manage them with least privilege.
Troubleshooting

Record the command, expected output, and failure branch for every check

Save the original exit code and first valid error before making fixes. Running multiple cleanup commands in succession can destroy the evidence and may mistake a dependency error for a node failure.

Command-based checklist for common Cloud Mac issues
Check Command or action Expected result Failure branch
Network resolution and reachability ping -c 20 host
ssh -v user@host		 Address resolution is consistent; samples show no sustained packet loss; SSH reaches the handshake and authentication stages. For resolution errors, verify the address; for timeouts before connection, switch the local network and retest; for authentication failures, check only the current username and credentials.
Disk and build space df -h
du -sh ~/Library/Developer/Xcode/DerivedData		 The target volume has enough space for source code, dependencies, archives, and export results; cache size is within the team threshold. Move artifacts that must be retained first, then delete rebuildable project caches; do not directly delete archive directories whose ownership is uncertain.
Xcode toolchain xcode-select -p
xcodebuild -version		 The developer directory and version match the pipeline record, and the commands return successfully. Explicitly switch the toolchain when the path is wrong; stop the task when the version differs to avoid producing incomparable archive results.
Project and scheme xcodebuild -list -workspace App.xcworkspace The target scheme is visible and the scheme used for automation is shared. If the list is empty, check the working directory and dependency-generation steps; if the scheme is not visible, check project sharing settings and name capitalization.
Signing identity security find-identity -v -p codesigning The signing identity required by the current task is visible, without ambiguity from expired or duplicate choices. If the identity is missing, check the import scope, keychain access, and provisioning-profile match; never paste private keys or passwords into a public page.
Archiving and export Retain xcodebuild exit code, archive path, and export log. The archive directory exists, and the export result maps to the commit identifier and task ID. Start with the first error in the log; distinguish the compile, signing, archive, and export stages rather than summarizing the entire failure with the last line.
RULE 01

Change one variable at a time

Keep display settings unchanged after switching networks; keep the source commit unchanged after switching Xcode. Only then can you compare the results.

RULE 02

Retain the first valid error

Later errors are often cascading results. Record the earliest error section, exit code, and corresponding command.

RULE 03

Redact logs before sharing

Remove host credentials, tokens, private-key contents, and sensitive project paths while retaining the time, task ID, and tool versions.

Support escalation

When you cannot locate the issue yourself, submit a task record that can be reviewed

Existing users should sign in to the console to submit a ticket; if sign-in is unavailable, email support@oakvm.com. Neither channel requires connection credentials to be pasted on a public page.

SUPPORT PACKET 6 recommended details
01Node region

Singapore, Japan (Tokyo), South Korea (Seoul), Hong Kong, US East, or US West.

02Time of occurrence

Include the date, time, and time zone so node logs can be aligned.

03Task ID

Provide an identifiable number from the order, instance, or CI task.

04Reproduction steps

List the entry point, commands, and last successful step before the issue appeared.

05Expected vs. actual

Describe the expected and actual outputs separately; do not write only “unable to use.”

06Redacted logs

Retain the error context, exit code, and versions; remove credentials, tokens, and private-key contents.

Dedicated physical machine · Non-virtualized · USD billing

Need a Cloud Mac that connects to your existing pipeline?

Choose OakVM M4 or OakVM M4 Pro and configure the rental period across six available node regions. All regions operate normally 365 days a year; actual availability is based on the console’s real-time response.

Rent a Mac build node now View pricing and configurations