createXCodeSandboxClient() Creates a client for interacting with a sandboxed Xcode build service.
import { createXCodeSandboxClient } from 'limrun' ; const client = await createXCodeSandboxClient ({ apiUrl: instance . status . sandbox . xcode . url , token: apiKey , });
Parameters options
CreateXCodeSandboxClientOptions
required
Configuration options for the Xcode sandbox client The API URL of the Xcode sandbox server
Auth token for the sandbox
Simulator (limulator) connection details. Only needed if the sandbox is not already configured (e.g., when created outside of an iOS instance). When provided, the client will call POST /simulator to set up the connection. The API URL of the simulator (limulator)
Auth token for the simulator. If not provided, uses the sandbox token.
Controls logging verbosity. One of: 'none', 'error', 'warn', 'info', 'debug'
Returns client
Promise<XCodeSandboxClient>
A promise that resolves to an XCodeSandboxClient instance
Examples Using iOS Instance
Standalone Sandbox
Complete Workflow
// When using an iOS instance (simulator already configured) const client = await createXCodeSandboxClient ({ apiUrl: instance . status . sandbox . xcode . url , token: apiKey , });
XCodeSandboxClient Client interface for interacting with a sandboxed Xcode build service.
Methods sync() Sync source code to the sandbox. In watch mode, keeps syncing on changes. Does NOT trigger builds - call xcodebuild() when ready.
const result = await client . sync ( './my-ios-app' , { watch: true , filter : ( path ) => ! path . startsWith ( 'build/' ), });
Path to the local code directory to sync
Sync configuration options cacheKey
string
default: "xcode-sandbox"
Cache scoping key for delta basis caching. This is not sent to the server.
Directory for the client-side folder-sync cache
Max patch size (bytes) to send as delta before falling back to full upload
If true, watch the folder and re-sync on any changes
log
(level: 'debug' | 'info' | 'warn' | 'error', msg: string) => void
Custom logging function
filter
(relativePath: string) => boolean
Optional filter function to include/exclude files and directories. Called with the relative path from the sync root (using forward slashes). For directories, the path ends with ’/’. Return true to include, false to exclude. // Exclude build folder filter : ( path ) => ! path . startsWith ( 'build/' ) // Only include source files filter : ( path ) => path . startsWith ( 'src/' ) || path . endsWith ( '.json' )
Sync result containing stopWatching function if watch mode is enabled Present only when watch=true; call to stop watching
xcodebuild() Trigger xcodebuild on the synced source code. Returns a ChildProcess-like object for streaming output.
const build = client . xcodebuild ({ scheme: 'MyApp' , workspace: 'MyApp.xcworkspace' , }); // Stream build output build . stdout . on ( 'data' , ( line ) => console . log ( line )); const { exitCode } = await build ;
Build configuration options Path to .xcworkspace file
A ChildProcess-like object that can be awaited or used for streaming. See exec for details. Types LogLevel type LogLevel = 'none' | 'error' | 'warn' | 'info' | 'debug' ;
Controls logging verbosity for the Xcode sandbox client.
XcodeBuildConfig type XcodeBuildConfig = { workspace ?: string ; project ?: string ; scheme ?: string ; };
Build configuration for xcodebuild command.
SimulatorConfig type SimulatorConfig = { /** The API URL of the simulator (limulator) */ apiUrl : string ; /** Auth token for the simulator. If not provided, uses the sandbox token. */ token ?: string ; };
Simulator connection details for configuring the sandbox.
SyncOptions type SyncOptions = { cacheKey ?: string ; basisCacheDir ?: string ; maxPatchBytes ?: number ; watch ?: boolean ; log ?: ( level : 'debug' | 'info' | 'warn' | 'error' , msg : string ) => void ; filter ?: ( relativePath : string ) => boolean ; };
Options for syncing source code to the sandbox.
SyncResult type SyncResult = { /** Present only when watch=true; call to stop watching */ stopWatching ?: () => void ; };
Result of a sync operation.