rust sdk

https://crates.io/crates/ix-sdk release planned

ix-sdk is the sdk: a typed async client for the ix api. the python and typescript packages are generated from this crate, so the errors and the wire behavior you read here hold everywhere. some rust names are older than the generated surface (Branch is the generated Machine, commit is snapshot); the generated packages carry the current vocabulary.

run a command

set IX_TOKEN first, or run ix login. from_env reads the same credential ladder every ix client uses; nobody types a server url.

use ix_sdk::{CreateTarget, CreateVm, IxClient};

let client = IxClient::from_env()?;

let created = client
    .create_vm_from_target(CreateVm::new(CreateTarget::Base).name("sdk-example"))
    .await?;
let vm = created.branch;
let result = vm.exec(vec!["uname".into(), "-a".into()], None).await?;
println!("{}", result.stdout);
vm.delete().await?;

create_vm_from_target returns a CreatedVm. branch is the handle for one machine, and everything you do to a machine is a method on it: exec, logs, commit for a snapshot, fs() for files.

the machine is booted by the time this returns. the wait happens on the server next to the guest, as part of the create call rather than a second round trip, so there is no poll loop to write and no interval to tune. readiness says how that wait ended — Ready with the instant the server observed it, or NotReady with how long it waited and what it last saw. ready_wait_ms(0) hands the machine back as soon as it is started instead.

retrying a create safely

give a create an idempotency_key and a retry finds its machine instead of booting a second one:

let created = client
    .create_vm_from_target(
        CreateVm::new(CreateTarget::Base)
            .name("sdk-example")
            .idempotency_key(request_id),
    )
    .await?;
if created.deduplicated {
    println!("this machine already existed");
}

the key is scoped to your account and names the parameters, not the call. the same key with different parameters is a conflict, not a replay: one name for two machines is a bug, and returning either one silently would be the wrong one half the time. ready_wait_ms is not part of the parameters, so retrying with a shorter deadline is still the same request.

errors are one enum, SdkError, classified by method instead of string matching: is_retryable(), is_unauthorized(). cancellation is structural: drop the future and the work stops.