The machine module provides functions for interacting with the host machine.

​
Allowed in

  • build
  • deploy
  • destroy
  • task

​
Usage

Load the module:

load("github.com/ocuroot/sdk/v0/machine.star", "host")

​
Example

# Run a shell command
result = host.shell("echo 'Building application...'")
if result.exit_code != 0:
    fail("Build failed: " + result.stderr)

# Check OS and architecture
if host.os() == "darwin":
    # macOS-specific commands
    host.shell("xcodebuild clean build")
elif host.os() == "linux":
    # Linux-specific commands
    host.shell("make build")

# Use environment variables
java_home = host.env_var("JAVA_HOME")
if not java_home:
    fail("JAVA_HOME must be set")

# Run command with custom environment
host.shell(
    "mvn package",
    env={"JAVA_HOME": java_home},
    shell="bash",
    continue_on_error=False
)

​
API Reference

​
shell(command, shell=“sh”, env=, mute=False, continue_on_error=False)

Runs a shell command on the host machine.

Arguments

  • command: Shell command to run
  • shell: Shell to use (e.g., “sh”, “bash”)
  • env: Dictionary of environment variables
  • mute: Whether to suppress command output
  • continue_on_error: Whether to continue if command fails

Returns

  • Struct containing:
    • combined_output: Interleaved stdout and stderr
    • stdout: Command standard output
    • stderr: Command standard error
    • exit_code: Command exit code

​
os()

Returns the operating system of the host machine.

Returns

  • String like “linux”, “darwin”, “windows” (matches Go’s GOOS values)

​
arch()

Returns the architecture of the host machine.

Returns

  • String like “amd64”, “arm64” (matches Go’s GOARCH values)

​
env_var(name)

Returns the value of an environment variable on the host machine.

Arguments

  • name: Name of the environment variable

Returns

  • Value of the environment variable or None if not set

​
Stubs

def make_host():
    def shell(command, shell="sh", env={}, mute=False, continue_on_error=False):
        """
        Runs a shell command on the host machine.

        Args:
            command: The shell command to run.
            shell: The shell to use to run the command. Example: "bash".
            env: A dictionary of environment variables to set.
            mute: Whether to mute the output of the command.
            continue_on_error: Whether to continue the build if the command fails.

        Returns:
            A struct with the following fields:
                combined_output: The interleaved stdout and stderr of the command.
                stdout: The stdout of the command.
                stderr: The stderr of the command.
                exit_code: The exit code of the command.
        """
        pass
    
    def os():
        """
        Returns the operating system of the host machine. Example: "linux", "darwin", "windows".
        Analogous to GOOS values in Go, as listed here https://pkg.go.dev/internal/platform#pkg-variables
        """
        pass
    
    def arch():
        """
        Returns the architecture of the host machine. Example: "amd64", "arm64".
        Analogous to GOARCH values in Go, as listed here https://pkg.go.dev/internal/platform#pkg-variables
        """
        pass
    
    def env_var(name):
        """
        Returns the value of the environment variable `name` on the host machine.
        """
        pass

    return struct(
        shell = shell,
        os = os,
        arch = arch,
        env_var = env_var,
    )

host = make_host()