This quickstart is for developers and CI/CD engineers using Oakmini for the first time. Choose a dedicated Mac mini physical node, connect over SSH or VNC, restore the Apple Silicon toolchain, complete a reproducible build, and connect a self-hosted runner to your existing pipeline.
$ uname -m
arm64
$ sw_vers -productVersion
macOS ready
$ system_profiler SPHardwareDataType
Chip: Apple M4
$ xcodebuild -version
Xcode toolchain detected
$ git --version
git ready
✓ environment baseline recordedClarify compatibility, region, term, and permissions first. This prevents discovering after connection that dependencies use the wrong architecture, storage is insufficient, or the pipeline lacks repository access. Save the results in the project's migration record.
Check whether dependencies provide arm64 versions, focusing on binary tools, container images, native extensions, and legacy scripts. If the project comes from an Intel environment, list components that must be replaced or rebuilt first.
file ./your-binaryConfirm the target architectureChoose from Singapore, Japan (Tokyo), South Korea (Seoul), Hong Kong, or the US West. For interactive VNC use, prefer a location near primary operators; for unattended builds, consider the locations of the code source, artifact storage, and collaboration team.
ping / tracerouteMeasure from the actual office networkDaily terms suit short validation, weekly terms suit migration sprints, and monthly or quarterly terms suit ongoing development and always-on runners. Estimate the full time for setup, builds, acceptance, and artifact export—not just one task run.
day / week / month / quarterDo not mix order termsEstimate repositories, dependency caches, simulator data, archives, and exported artifacts separately. Leave headroom in build directories to prevent dependency resolution or archiving from failing when storage runs out. Define a cache cleanup policy for long-running tasks.
df -hVerify again after connectingFor command-line work, prepare an SSH client and key. When you need the macOS graphical interface, prepare a VNC client. Confirm that your local network permits the connection and record how corporate firewalls, proxies, or VPNs affect the route.
ssh -VVerify the local client firstConfirm the permissions required to read repositories, access dependency sources, register a CI runner, use build-signing materials, and upload artifacts. Prefer task-specific credentials and grant automation the minimum required scope.
read / build / uploadMark each permission scopeOak Core and Oak Forge are dedicated Mac mini physical nodes, not virtual machines. Choose based on peak memory, concurrent build count, working-set size, and artifact volume—not vague performance multipliers.
Suitable for single-project debugging, dependency validation, low-concurrency automation, and short migration checks. Add storage at checkout if repositories, simulators, and archives are large.
Suitable for parallel projects, large dependency graphs, high-memory compilation, Apple Silicon AI inference experiments, and workloads that retain extensive caches and build artifacts.
| Order field | Available options | Selection basis | Confirmation |
|---|---|---|---|
| Billing term | Day, week, month, quarter | Covers environment setup, task execution, acceptance, and artifact export | The start and end dates shown on the order match the plan |
| Node | Singapore, Japan (Tokyo), South Korea (Seoul), Hong Kong, US West | Actual network path between users, code sources, and artifact targets | Region name matches the baseline record |
| Storage expansion | +1TB SSD or +2TB SSD | Total repositories, dependency caches, working directories, archives, and exported artifacts | Reserve space for cleanup and temporary files |
| Parallel option | Thunderbolt 5 parallel connection (per machine) | Choose only for a planned multi-node workflow | Verify quantity and topology for each machine |
Read the current host status, address, port, and credential instructions from the portal. Do not guess parameters from an old order or local history. Use SSH for command-line work and VNC when you need a graphical interface.
ssh -p <PORT> <USER>@<HOST>
hostname
sw_vers
uname -m
system_profiler SPHardwareDataType
df -h
systemsetup -gettimezone
dateSave the output in the migration record. At minimum, confirm the hostname, macOS version,arm64 architecture, chip model, storage capacity, time zone, and current time.
The host should be ready for connection. If its status is still changing, wait for the portal to update instead of repeatedly retrying credentials.
Verify the host address, port, username, and access method individually. Store key files only on controlled devices.
Record the fingerprint on the first SSH connection. If it changes unexpectedly later, stop connecting and verify it through a console ticket.
When using VNC, start with a resolution and image quality suited to the current network, then check the keyboard layout, clipboard policy, and sleep settings.
Establish a reviewable base environment before installing project dependencies. Do not copy the entire old user directory; migrate inventories, configuration, and lock files first to reduce architecture differences and stale caches.
Restore the software inventory and run diagnostics, checking the installation prefix and shell environment. Common Apple Silicon paths must match hard-coded script paths or be updated.
brew bundle check && brew doctorSet the commit identity, line-ending policy, and credential access method. Pull a read-only test repository first to confirm network access and permissions before handling the production project.
git config --list --show-originRestore Ruby, Node.js, Python, or other runtime versions from the lock files. Record the version manager, global tools, and project-level versions; do not rely on “latest version” descriptions.
ruby -v; node -v; python3 --versionConfirm the selected developer directory, Xcode version, SDK, and command-line tools. When projects require different versions, document the switching steps explicitly in the pipeline.
xcode-select -p; xcodebuild -versionRestore dependencies from the repository's lock files and retain the complete resolution log. If dependencies require native extensions, confirm that the output architecture is arm64.
file ./path/to/native-extensiondate
hostname
sw_vers
uname -m
xcode-select -p
xcodebuild -version
git --version
brew --version
brew list --versions
ruby -v
node -v
python3 --version
df -hThe goal of the first build is not the shortest run time, but proving that dependency resolution, signing permissions, output directories, and logs are reproducible. Test a fixed commit first, then expand to the full project after it succeeds.
Check out the specified commit or tag and confirm that submodules, private dependencies, and large-file objects are complete. Record the repository commit hash so inputs cannot change during testing.
git rev-parse HEAD
Restore dependencies from the lock files and write stdout and stderr to the log. When an architecture issue occurs, identify the specific binary instead of repeatedly clearing the entire environment.
command 2>&1 | tee dependency.log
Confirm that the build process can read the signing materials and configuration files it needs. Grant automation accounts only the permissions required by the relevant project and build steps.
security find-identity -v -p codesigning
Place DerivedData, archives, test results, and exported artifacts in clearly defined directories. Avoid uncontrolled temporary paths shared with other tasks.
mkdir -p build logs artifacts
Logs should include the commit version, Xcode version, SDK, command, start time, end time, and exit code. Redact sensitive fields before uploading.
echo "$?" > logs/exit-code.txt
Run again with the same commit and configuration to confirm that dependencies, paths, and permissions do not depend on temporary actions from the first session. Both results should be explainable and comparable.
./scripts/verify-build.sh
xcodebuild \
-project Example.xcodeproj \
-scheme Example \
-configuration Release \
-derivedDataPath ./build/DerivedData \
build 2>&1 | tee ./logs/first-build.logThe command exits with code 0; logs identify the fixed commit and toolchain versions; expected artifacts exist in the output directory; and a second run requires no undocumented manual actions.
Prepare the three paths in parallel if needed, but bring them together against a shared baseline: pin the repository version, record toolchain versions, define runner labels, then trigger a reproducible validation task.
Migrate only data you can explain; do not carry over historical state that cannot be traced.
Restore tools from the inventory and confirm the result with version output.
Make the scheduling rules target this dedicated physical machine explicitly.
A working environment is not necessarily ready for long-term use. After the first build, immediately address initial credentials, key storage, repository scope, and sensitive information in scripts.
Search for common sensitive fields before committing, and inspect shell history, environment files, CI configuration, and logs. If plaintext credentials are found, revoke and replace them first, then clean the file history.
Restrict private-key file permissions, remove unused public keys, and configure identifiable key names and purpose records for automated connections.
chmod 600 ~/.ssh/private_key
Keep timestamps, commands, versions, exit codes, and error stacks; remove access tokens, private-key contents, signing material, and other information that could directly authorize access.
Acceptance should be based on reproducible results, not on whether it “works in the current session.” Disconnect and reconnect, then run the key commands again from a clean shell.
Disconnect SSH and VNC intentionally, then reconnect using the saved, correct parameters. The host fingerprint, username, port, and graphical session all match the record.
Restore dependencies from the lock files; the command exits with code 0; native components use the correct architecture; and the installation log is saved without sensitive information.
Build with the pinned commit and toolchain versions, use a clearly defined output directory, and ensure the second run requires no undocumented manual actions.
Archives, test results, and other target artifacts can be exported from the specified directory, with filenames, versions, and verification methods meeting team conventions.
The self-hosted runner is online, its labels match the target task, and it does not accept jobs from unauthorized projects.
The environment baseline, dependency logs, build logs, exit codes, and artifact paths are archived, with sensitive fields redacted.
Verify the host status, order information, and management entry point in the portal. All nodes run normally 365 days a year with continuous availability.
Open the portal to view currently available nodes, then choose Oak Core or Oak Forge, a billing term, and storage options. After ordering, follow this page to complete connection, toolchain restoration, and acceptance.