Orchard Documentation

To quickly set up a local Orchard environment, install the CLI via Homebrew and run the development command. This starts both the Orchard Controller and a single Orchard Worker on your local machine. You can then interact with the cluster via the orchard CLI or the built-in REST API.

brew install openai/tools/orchard
orchard dev

Port-forwarding specifications are defined using a colon-delimited string format (localPort:remotePort).

• Single port (remotePort): If only one port is provided (e.g., 8080), it is treated as the remotePort, and the localPort defaults to 0.
• Two ports (localPort:remotePort): If two ports are provided (e.g., 8080:9000), the first is the localPort and the second is the remotePort.

Constraints:

• Ports must be integers in the range [1, 65535].
• Invalid formats or out-of-range ports will return an ErrInvalidPortSpec error.

# Example: Remote port only (local port defaults to 0)
8080

# Example: Local port and remote port
8080:9000

The --synthetic flag (hidden) allows you to run a worker without instantiating real Tart VMs. Instead, it uses synthetic in-memory VMs and a TCP echo server to emulate a VM's TCP/IP stack. This is suitable for load testing the Controller and networking logic without the overhead of real virtualization.

orchard worker run <CONTROLLER_URL> --bootstrap-token <TOKEN> --synthetic

You can use a path-based syntax to retrieve the value of a specific field within a VM instead of the full table. This is useful for automation or scripts where you only need one specific attribute (e.g., the status).

To use this, append the field path to the VM name using a forward slash /.

Usage: orchard get vm <NAME>/<FIELD_PATH>

Example: To get the status of a VM named macos: orchard get vm macos/status

The orchard command is the primary entrypoint for managing Orchard resources and performing administrative tasks. It is organized into functional groups: 'Working With Resources' for standard lifecycle and access operations, and 'Administrative Tasks' for system-level management.

To see all available commands, run orchard --help.

# General usage pattern
orchard <command> [flags]

Orchard is a command-line tool. The binary is initialized with a root command that supports signal-interruptible execution. When running commands via the CLI, you can interrupt the process using standard OS interrupt signals (e.g., Ctrl+C), which will trigger a graceful shutdown of the command context.

# Example of running the orchard binary (assuming it is in your PATH)
$ orchard --help

The NewPortSpec function parses a raw string into a PortSpec struct. It supports the localPort:remotePort or remotePort formats.

Returns:

• *PortSpec: A struct containing LocalPort and RemotePort as uint16.
• error: Returns ErrInvalidPortSpec if the string is malformed or the port numbers are outside the valid range [1, 65535].

// Example usage
spec, err := NewPortSpec("8080:9000")
if err != nil {
    // handle error (e.g., ErrInvalidPortSpec)
}
fmt.Printf("Local: %d, Remote: %d\n", spec.LocalPort, spec.RemotePort)

The Client struct provides entry points to various service namespaces. Use these methods to access specific API domains:

• Workers(): Returns a *WorkersService.
• VMs(): Returns a *VMsService.
• ServiceAccounts(): Returns a *ServiceAccountsService.
• Controller(): Returns a *ControllerService.
• ClusterSettings(): Returns a *ClusterSettingsService.
• RPC(): Returns an *RPCService.

// Example: Accessing the VMs service
vmService := cl.VMs()
// Now use vmService to call VM-related methods

The Check(ctx) method performs a simple GET / request to verify that the client can communicate with the Orchard API.

err := cl.Check(ctx)
if err != nil {
	fmt.Printf("Connection failed: %v\n", err)
} else {
	fmt.Println("Connected successfully!")
}