SDK reference
Generated from the Rust source the TypeScript and Python packages are built from (crates/ix/sdk-bind). Pick a language in any tab group and every table on the site follows. Names are camelCase in TypeScript and snake_case in Python and Rust.
Objects
Ci
CI runner-pool credentials, reached as client.ci.
Trade a GitHub Actions OIDC token (requested with the ix audience) for a GitHub App installation token scoped to the workflow's own repository.
ci.githubRunnerToken(oidcToken: string): Promise<GithubRunnerToken>Client
The ix API client.
Connect using an explicit token, or the ambient credential when token is omitted.
new Client(token?: string, baseUrl?: string): ClientThe API endpoint this client is talking to.
client.baseUrl(): stringThe keys namespace.
client.keys: KeysThe machines namespace.
client.machines: MachinesThe snapshots namespace.
client.snapshots: SnapshotsThe usage namespace.
client.usage: UsageThe authenticated account.
client.me(): Promise<Me>The secrets namespace: the ACCOUNT's secret store. One machine's own copies are machines.connect(id).secrets.
client.secrets: SecretsThe ci namespace: credentials for runner pools that run CI on ix machines.
client.ci: CiThe credits namespace: model spend paid in ix credits.
client.credits: CreditsThe groups namespace: private networks between machines.
client.groups: GroupsThe previews namespace: disposable copies of a deployment.
client.previews: PreviewsThe volumes namespace: persistent disks and their snapshots.
client.volumes: VolumesThe observability namespace: traces and logs, correlated by id.
client.observability: ObservabilityThe regions namespace.
client.regions: RegionsCredits
Spend ix credits directly.
Debit amount_microcredits from the account and get a receipt.
credits.burn(amountMicrocredits: number, idempotencyKey: string): Promise<BurnReceipt>Credit back what a burn did not spend: spent_microcredits of it was used, and the rest returns. Repeating it for a settled burn returns the same outcome.
credits.unburn(burnId: string, spentMicrocredits: number): Promise<CreditBurn>Groups
The groups namespace: private east-west networks between machines.
Create a group.
groups.create(slug: string): Promise<Group>Delete a group. Its members lose the overlay; the machines are untouched.
groups.delete(slug: string): Promise<void>Every group the caller owns.
groups.list(): Promise<Group[]>Put a machine in a group, resolvable inside it as <dns_name>.ix.internal.
groups.addMember(group: string, machineName: string, dnsName?: string): Promise<AddedMember>Take a machine out of a group.
groups.removeMember(group: string, machineName: string): Promise<void>Who is in a group, and at which address.
groups.listMembers(group: string): Promise<GroupMember[]>Keys
API keys: one capped credential per user or per agent, over the account's single balance.
Mint a key. The returned secret is the only copy that will ever exist in plaintext.
keys.create(name: string, limitUsd?: number, scopes?: string[], expiresAt?: number): Promise<CreatedKey>Every key on the account, flattened, children tagged with parent_id.
keys.list(includeRevoked?: boolean): Promise<ApiKey[]>One key by id, whatever its state.
keys.get(id: string): Promise<ApiKey>Change a key's label, cap, paused state, or scopes.
keys.update(id: string, name?: string, limitUsd?: number, clearLimit?: boolean, disabled?: boolean, scopes?: string[]): Promise<ApiKey>Permanently revoke a key and every key beneath it.
keys.revoke(id: string): Promise<void>The key this client is authenticated with: its own cap, spend and headroom. ix keys self on the CLI.
keys.current(): Promise<ApiKey>A page of one key's burns, newest first: what it spent through Credits::burn and through ix's model gateway, each with what it reserved and what it settled to.
keys.burns(id: string, limit?: number, before?: string): Promise<KeyBurnPage>Machines
The vms namespace: the account's machines as data.
Every machine the caller owns, in any state.
machines.list(): Promise<MachineInfo[]>Delete several machines and their disks. Not reversible.
machines.deleteMany(ids: string[]): Promise<DeleteResult[]>One machine by id, name, or ix_... typed id.
machines.get(machine: string): Promise<MachineInfo>A handle onto one machine: exec, files, logs, snapshots.
machines.connect(id: string): MachineThe migrations namespace: moving a running machine between nodes.
machines.migrations: MigrationsCreate a machine and return a handle onto it, booted.
machines.create(options: CreateMachineOptions): Promise<Machine>Create a machine, streaming progress as it happens.
machines.createStream(options: CreateMachineOptions): Promise<unibind_runtime::UniStream<MachineProgress>>The latest resource usage of every machine the caller can see.
machines.metrics(): Promise<MachineUsage[]>Machine addresses reachable directly from the caller's own network.
machines.localEndpoints(): Promise<LocalEndpoint[]>Machine
A live machine: commands, files, logs, status, snapshots.
Create a machine and return a handle onto it.
Machine.create(options?: CreateMachineOptions): Promise<Machine>Adopt a machine that already exists, by name or id.
Machine.attach(machine: string): Promise<Machine>Every machine the caller owns, in any state.
Machine.list(): Promise<MachineInfo[]>This machine's id.
machine.id(): stringWhether the create that produced this handle replayed an earlier one instead of booting a new machine.
machine.deduplicated(): booleanHow the create that produced this handle finished waiting for the guest to boot.
machine.readiness(): MachineReadinessThe lifetime this handle created the machine with: persistent or ephemeral (a TTL machine is ephemeral; read Self::ttl).
machine.lifetime: Lifetime | undefinedThe deadline this handle created an ephemeral machine with, as a duration string ("1h" for the ephemeral default, "20m" for an explicit one). Absent for a persistent or adopted handle.
machine.ttl: string | undefinedThe machine's current record.
machine.info(): Promise<MachineInfo>Start a stopped machine, and wait for the platform to report it running.
machine.start(): Promise<MachineInfo>Stop the machine, keeping its disk.
machine.stop(options?: StopOptions): Promise<MachineInfo>Restart the machine.
machine.restart(options?: RestartOptions): Promise<MachineInfo>Rename the machine.
machine.rename(name: string): Promise<MachineInfo>Delete the machine and its disk. Not reversible.
machine.delete(): Promise<void>Release the handle, deleting the machine only if this handle created it ephemeral.
machine.close(): Promise<void>Run a command and return its Process at once.
machine.exec(command: string[], options?: ExecOptions): ProcessRun a shell script and return its Process at once.
machine.shell(script: string, options?: ExecOptions): ProcessStart a command and return its guest pid, without waiting.
machine.spawn(command: string[], cwd?: string): Promise<number>Read a guest file as text.
machine.readFile(path: string): Promise<string>Create or truncate a guest file and write text to it.
machine.writeFile(path: string, contents: string): Promise<number>List a guest directory's direct children.
machine.listDir(path: string): Promise<DirEntry[]>The most recent log lines.
machine.logs(stream?: LogStream, limit?: number, since?: number): Promise<LogEntry[]>Follow the machine's logs as they are written, one line per item.
machine.tailLogs(stream?: LogStream): Promise<unibind_runtime::UniStream<String>>Follow the machine's status.
machine.watch(): Promise<unibind_runtime::UniStream<MachineStatusEvent>>Whether the guest has finished booting.
machine.isReady(): Promise<boolean>Wait until the guest finishes booting.
machine.waitReady(timeoutMs?: number): Promise<boolean>Capture a snapshot of this machine's disk.
machine.snapshot(): Promise<SnapshotRef>Wait until a captured snapshot is ready to restore.
machine.waitSnapshotReady(snapshotId: string, timeoutMs?: number): Promise<SnapshotWait>Copy this machine into a new one: snapshot, wait until the snapshot is restorable, restore.
machine.fork(options?: ForkOptions): Promise<Machine>Open an interactive shell and return the live session.
machine.openShell(command?: string[], cols?: number, rows?: number, term?: string, env?: std::collections::HashMap<String, String>): Promise<ShellSession>Re-attach to a shell session that is already running.
machine.attachShell(sessionId: number, cols?: number, rows?: number): Promise<ShellSession>Every shell session on the machine, running or exited-but-unreaped.
machine.listShells(): Promise<ShellInfo[]>Dial a TCP port inside the machine and return the raw stream.
machine.connectPort(port: number): Promise<ByteStream>Dial a UDP port inside the machine. The datagram counterpart to Self::connect_port.
machine.connectUdpPort(port: number): Promise<UdpForward>Attach to the machine's bootstrap console.
machine.openConsole(): Promise<ByteStream>Start the machine, reporting each phase as it happens.
machine.startStreaming(): Promise<unibind_runtime::UniStream<MachineProgress>>Follow the machine's logs as raw bytes, exactly as they were written.
machine.tailLogsBytes(stream?: LogStream): Promise<unibind_runtime::UniStream<Vec<u8>>>Read a guest file as a stream of byte chunks.
machine.readFileStream(path: string, offset?: number, length?: number): Promise<unibind_runtime::UniStream<Vec<u8>>>This machine's OWN secrets, as distinct from the account store at client.secrets.
machine.secrets: MachineSecretsBind a local TCP port that forwards to remote_port in this machine.
machine.forwardPort(remotePort: number, localPort?: number): Promise<PortForward>Restart this machine's in-guest platform daemons without rebooting it.
machine.reload(guest?: boolean, console?: boolean, agent?: boolean): Promise<ReloadedDaemons>Send a Magic SysRq key to this machine's guest kernel.
machine.sysrq(letter: string): Promise<void>This machine's latest resource sample.
machine.metrics(): Promise<MachineMetrics | undefined>Turn this machine's inbound and outbound internet access on or off.
machine.setInternet(ingress?: boolean, egress?: boolean): Promise<MachineInfo>Converge this machine's east-west group membership onto exactly groups.
machine.applyGroups(groups: string[]): Promise<GroupChanges>How long this machine's last start took, stage by stage.
machine.startupInfo(): Promise<StartupInfo | undefined>Re-apply this machine's networking on the node hosting it.
machine.reconfigureNetwork(): Promise<void>Read a byte range of a guest file.
machine.readBytes(path: string, offset?: number, length?: number): Promise<number[]>Read a whole guest file as bytes.
machine.readAllBytes(path: string): Promise<number[]>Create or truncate a guest file and write bytes to it.
machine.writeAllBytes(path: string, contents: number[], mode?: number): Promise<number>What the machine's host can see of its live runtime.
machine.runtimeStatus(): Promise<RuntimeStatus>Migrations
The migrations namespace: moving a running machine between nodes.
Start moving a machine onto another node.
migrations.start(machineId: string, targetNode?: string): Promise<StartedMigration>The machine's current migration, or nothing when it is not migrating.
migrations.get(machineId: string): Promise<Migration | undefined>Ask the coordinator to abandon an in-flight migration.
migrations.cancel(machineId: string, migrationId: string): Promise<void>PortForward
A local TCP port that maps onto a port inside a machine.
The local port now accepting connections.
portForward.localPort(): numberThe guest port this forward reaches.
portForward.remotePort(): numberThe machine this forward reaches.
portForward.machineId(): stringStop forwarding and release the local port.
portForward.close(): Promise<void>Observability
The observability namespace: traces and logs, correlated by id.
Traces matching a correlation id, as summaries.
observability.traces(traceId?: string, requestId?: string, operationId?: string, since?: number, until?: number, limit?: number): Promise<TraceSummary[]>One trace expanded: a flattened span tree, or the journald fallback. See TraceDetail for which you get and why.
observability.trace(traceId: string): Promise<TraceDetail>Platform log lines matching a correlation id.
observability.logs(traceId?: string, requestId?: string, operationId?: string, since?: number, until?: number, limit?: number): Promise<PlatformLog[]>Previews
The previews namespace: disposable copies of a deployment.
Bring up a preview.
previews.create(imageTag?: string, forkVolumes?: boolean): Promise<PreviewDetail>Every preview, with its service and health counts.
previews.list(): Promise<Preview[]>One preview, with a row per service.
previews.get(id: string): Promise<PreviewDetail>Tear a preview down.
previews.stop(id: string): Promise<void>Make this preview the live deployment.
previews.promote(id: string): Promise<PreviewDetail>Process
A running command on a machine.
Awaiting a Process calls wait.
Wait for the command to end and return what it produced.
process.wait(): Promise<ExecResult>The command's stdout as byte chunks, from the start.
process.stdout: unibind_runtime::UniStream<Vec<u8>>The command's stderr as byte chunks, from the start.
process.stderr: unibind_runtime::UniStream<Vec<u8>>Both streams merged in arrival order, from the start.
process.output: unibind_runtime::UniStream<OutputChunk>The merged output as text lines, each stream split on its own.
process.text(): unibind_runtime::UniStream<String>The command's stdin.
process.stdin: ProcessStdinKill the command: close its session so the guest sends SIGTERM, waits a grace window, then SIGKILLs its process group. Resolves once the session is closed. Killing a finished process does nothing.
process.kill(): Promise<void>ProcessStdin
A running command's stdin.
Write bytes to the command's stdin.
processStdin.write(data: number[]): Promise<void>Write text to the command's stdin, as UTF-8. Nothing is appended.
processStdin.writeText(text: string): Promise<void>Close the command's stdin, so a command reading to EOF finishes. Closing twice is fine.
processStdin.close(): Promise<void>Regions
The regions namespace: where machines can be placed.
Every region this account can place machines in.
regions.list(): Promise<Region[]>Secrets
The account's secret store: values a machine is built with.
Store a secret, or overwrite one under the same name.
secrets.set(name: string, value: string): Promise<SecretWrite>Every stored secret's name and timestamps. Never the values.
secrets.list(): Promise<Secret[]>Delete the ACCOUNT value.
secrets.delete(name: string): Promise<void>MachineSecrets
One machine's own secrets, reached as machines.connect(id).secrets.
This machine's secrets as metadata: name, injection shape, timestamps. Never the values.
machineSecrets.list(): Promise<MachineSecret[]>Set one secret on this machine alone.
machineSecrets.set(key: string, value: string): Promise<void>Remove one secret from this machine.
machineSecrets.delete(key: string): Promise<void>ShellSession
A live interactive shell on a machine: a real pty, not a command run.
This session's number, for Machine::attach_shell later.
shellSession.id(): numberThe shell's exit status, or absent while it is still running.
shellSession.exitCode(): number | undefinedEverything the shell writes, as it writes it.
shellSession.output(): unibind_runtime::UniStream<Vec<u8>>Send bytes to the shell's input.
shellSession.write(data: number[]): Promise<void>Send text to the shell's input, as UTF-8.
shellSession.writeText(text: string): Promise<void>Tell the shell its terminal was resized.
shellSession.resize(cols: number, rows: number): Promise<void>End the session.
shellSession.close(): Promise<void>ByteStream
A raw two-way byte stream to a machine.
Bytes arriving from the far end, until it closes.
byteStream.output(): unibind_runtime::UniStream<Vec<u8>>Send bytes to the far end, flushed before returning.
byteStream.write(data: number[]): Promise<void>Stop writing and release the read direction.
byteStream.close(): Promise<void>UdpForward
A UDP tunnel to a port on a machine.
Datagrams arriving from the guest port, one item per packet.
udpForward.datagrams(): unibind_runtime::UniStream<Vec<u8>>Send one datagram to the guest port.
udpForward.send(payload: number[]): Promise<void>Close the tunnel.
udpForward.close(): Promise<void>Snapshots
The snapshots namespace.
Every snapshot captured from one machine, newest first.
snapshots.list(machineId: string): Promise<Snapshot[]>Restore a snapshot into a NEW machine and return a handle onto it.
snapshots.restore(id: string, name?: string): Promise<Machine>Restore a snapshot into a new machine, reporting each phase.
snapshots.restoreStreaming(id: string, name?: string): Promise<unibind_runtime::UniStream<MachineProgress>>Usage
The usage namespace: what the account has spent, and what is left.
The account's balance and lifetime totals.
usage.summary(): Promise<UsageSummary>The whole billing picture: the money in Self::summary, plus where an unpaid account sits on the grace ladder, its recent purchases, its auto-recharge settings, and the bounds a Self::checkout amount must fall inside.
usage.status(): Promise<BillingStatus>The individual metered charges against ONE API key, newest first.
usage.events(keyId: string, since?: number, until?: number, resourceType?: string, limit?: number): Promise<UsageEvent[]>Spend over a window, rolled up by resource type, by individual resource, and by day.
usage.report(since?: number, until?: number, resourceType?: string, limit?: number, bucketSeconds?: number): Promise<UsageReport>This UTC month's spend: total so far, a projection to month end, compute consumed, and what each machine cost.
usage.monthToDate(now?: number): Promise<MonthSpend>Open a hosted payment page for buying credit.
usage.checkout(amountMicrocredits: number, savePaymentMethod?: boolean): Promise<Checkout>Volumes
The volumes namespace: persistent disks and their snapshots.
One volume by id.
volumes.get(id: string): Promise<Volume>Every volume the caller owns, attached or not.
volumes.list(): Promise<Volume[]>Every snapshot captured from one volume.
volumes.listSnapshots(id: string): Promise<VolumeSnapshot[]>Records
BillingLifecycle
Where an account sits on the unpaid-balance ladder.
| Field | Type | Description |
|---|---|---|
phase | string | One of active, compute_grace, data_retention, deleted. |
zeroBalanceStartedAt | number | undefined | When the balance first hit zero, if it has. |
computeGraceEndsAt | number | undefined | When compute stops running for an unpaid account. |
dataRetentionEndsAt | number | undefined | When an unpaid account's data is removed. |
deletedAt | number | undefined | When the account was deleted, if it was. |
AutoRecharge
Automatic top-up settings.
| Field | Type | Description |
|---|---|---|
enabled | boolean | Whether the platform will recharge at all. |
thresholdMicrocredits | number | Balance at or below which a recharge fires. |
thresholdUsd | number | That threshold in US dollars. |
amountMicrocredits | number | How much each recharge buys. |
amountUsd | number | That amount in US dollars. |
paymentMethodId | string | undefined | Saved payment method selected for automatic recharges. |
paymentMethodEligible | boolean | Whether the saved payment method can actually be charged without the customer present. enabled with this false never recharges, which is the state worth noticing before the balance runs out. |
lastFailure | string | undefined | Why the last attempt failed, if one did. |
TopUp
One credit purchase.
| Field | Type | Description |
|---|---|---|
id | string | Stable id. Opaque: pass it back, never parse it. |
amountMicrocredits | number | What was bought. |
amountUsd | number | That amount in US dollars. |
status | string | One of pending, paid, failed, canceled. |
savePaymentMethod | boolean | Whether the payment method was kept for future charges. |
createdAt | number | When the purchase was started (Unix epoch milliseconds). |
paidAt | number | undefined | When the money landed, if it has. |
BillingLimits
Bounds for top-ups and automatic recharge. The server refuses values outside these ranges, so a payment form reads them before submit.
| Field | Type | Description |
|---|---|---|
minimumMicrocredits | number | Smallest purchase the server accepts. |
maximumMicrocredits | number | Largest purchase the server accepts. |
presetsMicrocredits | number[] | The amounts the platform suggests, in order. |
minimumAutoRechargeThresholdMicrocredits | number | Smallest balance threshold accepted for automatic recharge. |
maximumAutoRechargeThresholdMicrocredits | number | Largest balance threshold accepted for automatic recharge. |
minimumAutoRechargeAmountMicrocredits | number | Smallest automatic recharge amount accepted. |
maximumAutoRechargeAmountMicrocredits | number | Largest automatic recharge amount accepted. |
BillingStatus
The account's billing state: money, grace, and how it refills.
| Field | Type | Description |
|---|---|---|
balanceMicrocredits | number | Credit remaining. Can be negative: the platform lets a balance go under zero rather than cutting a running workload dead. |
balanceUsd | number | Credit remaining, in US dollars. |
totalAddedMicrocredits | number | Everything ever added to the account. |
totalAddedUsd | number | Everything ever added, in US dollars. |
spentMicrocredits | number | Everything ever spent. |
spentUsd | number | Everything ever spent, in US dollars. |
lifecycle | BillingLifecycle | Where an unpaid account sits on the grace ladder. |
topUps | TopUp[] | Recent credit purchases. |
autoRecharge | AutoRecharge | Automatic refill settings. |
limits | BillingLimits | Bounds a checkout amount must fall inside. |
UsageEvent
One metered charge.
| Field | Type | Description |
|---|---|---|
id | string | Stable id. Opaque: pass it back, never parse it. |
keyId | string | The API key that incurred the charge. |
poolId | string | The credit pool it was charged against. |
resourceType | string | What was consumed, e.g. vm_cpu. |
quantity | number | How much of it, in units. |
unit | string | The unit quantity is counted in, e.g. vcpu-seconds. |
costMicrocredits | number | What it cost. |
costUsd | number | That cost in US dollars. |
resourceId | string | undefined | The machine, volume or snapshot charged for, when the charge names one. |
resourceName | string | undefined | That resource's name at the time of the charge. |
createdAt | number | When the charge was recorded (Unix epoch milliseconds). |
AccountActivity
One non-usage change to the account balance, currently a top-up.
| Field | Type | Description |
|---|---|---|
id | string | Stable id. Opaque: pass it back, never parse it. |
kind | string | What changed the balance, currently top_up. |
amountMicrocredits | number | Amount of credit involved. |
amountUsd | number | That amount in US dollars. |
status | string | One of pending, paid, failed, canceled. |
createdAt | number | When the activity was created (Unix epoch milliseconds). |
effectiveAt | number | undefined | When it affected the balance, if it has. |
ResourceSpend
Spend rolled up by what was consumed.
| Field | Type | Description |
|---|---|---|
resourceType | string | What was consumed. |
totalQuantity | number | Total consumption, in that resource's own unit. |
costMicrocredits | number | What it cost. |
costUsd | number | That cost in US dollars. |
InstanceSpend
Spend rolled up by the individual machine, volume or snapshot behind it.
| Field | Type | Description |
|---|---|---|
resourceType | string | What was consumed. |
resourceId | string | undefined | The resource charged, when the charge names one. |
resourceName | string | undefined | Its name at the time of the charge. |
totalQuantity | number | Total consumption, in that resource's own unit. |
costMicrocredits | number | What it cost. |
costUsd | number | That cost in US dollars. |
eventCount | number | How many metered charges rolled into this row. |
DailySpend
One calendar day of spend.
| Field | Type | Description |
|---|---|---|
day | string | The day, as the server labels it (YYYY-MM-DD, UTC). |
costMicrocredits | number | What that day cost. |
costUsd | number | That cost in US dollars. |
UsagePoint
One time bucket of one resource type, for a usage-over-time chart.
| Field | Type | Description |
|---|---|---|
bucketStart | number | Start of the bucket (Unix epoch milliseconds). |
resourceType | string | What was consumed in it. |
totalQuantity | number | Total consumption over the bucket, in that resource's own unit. |
costMicrocredits | number | What the bucket cost. |
costUsd | number | That cost in US dollars. |
UsageDimension
One billable dimension of a window, listed even when unused.
| Field | Type | Description |
|---|---|---|
id | string | cpu, memory, disk, snapshots, image_storage or egress. |
unit | string | The rate card's unit (vcpu_second, gib_second, tib_second, gb). |
quantity | number | Billed quantity in the window, in unit. |
unitPriceMicrocredits | number | Microcredits per unit; not a price while price_is_placeholder. |
priceIsPlaceholder | boolean | The price is a TODO-price placeholder: show it as such, never as free. |
costMicrocredits | number | What the window cost. |
heldBytes | number | undefined | Bytes held right now, for a stored-level dimension. |
note | string | undefined | What the row does not say on its own. |
UsageReport
Spend over a window, rolled up three ways.
| Field | Type | Description |
|---|---|---|
poolId | string | The credit pool this reports on. |
since | number | undefined | Start of the window, when one was asked for. |
until | number | undefined | End of the window, when one was asked for. |
totalCostMicrocredits | number | Everything the window cost. |
totalCostUsd | number | That total in US dollars. |
byResource | ResourceSpend[] | Rolled up by what was consumed. |
byInstance | InstanceSpend[] | Rolled up by which machine, volume or snapshot consumed it. |
byDay | DailySpend[] | Rolled up by day. |
series | UsagePoint[] | Bucketed series; empty unless bucket_seconds asked for one. |
recentEvents | UsageEvent[] | Most recent itemized charges within the query window. |
accountActivity | AccountActivity[] | Top-ups and other account-level balance changes within the window. |
creditBurns | CreditBurn[] | Credits burned within the window, newest first. |
dimensions | UsageDimension[] | Every billable dimension in order, zero rows included. |
unmeteredVms | number | Running machines with no disk reading: their disk is not metered. |
Checkout
A hosted payment page for buying credit.
| Field | Type | Description |
|---|---|---|
url | string | Send the customer here. The purchase happens on the payment provider's page, not through this API. |
sessionId | string | The provider's session id, for reconciling a webhook. |
topUpId | string | The pending top-up this session will settle. |
amountMicrocredits | number | What the session charges. |
amountUsd | number | That amount in US dollars. |
status | string | The session's state as the provider reports it. |
savePaymentMethod | boolean | Whether the payment method will be kept for future charges. |
MachineMonthSpend
What one machine cost this month.
| Field | Type | Description |
|---|---|---|
machineId | string | The machine's id. |
name | string | undefined | Its name at the time of the most recent charge. |
costMicrocredits | number | Month-to-date cost. |
costUsd | number | That cost in US dollars. |
MonthSpend
The current UTC month's spend, with a projection and per-machine cost.
| Field | Type | Description |
|---|---|---|
since | number | First instant of the month (Unix epoch milliseconds, UTC). |
until | number | The instant this was taken for. |
monthEnd | number | First instant of the next month. |
totalCostMicrocredits | number | Everything spent this month so far. |
totalCostUsd | number | That total in US dollars. |
projectedCostMicrocredits | number | undefined | The average pace so far, extended to month end. Absent in the first 24 hours of the month, where it would be noise. |
projectedCostUsd | number | undefined | The projection in US dollars. |
vcpuSeconds | number | Compute consumed, in vCPU-seconds. |
byMachine | MachineMonthSpend[] | Cost per machine, most expensive first. Charges that name no machine (volumes, snapshots, egress) count in the total only. |
byDay | DailySpend[] | Spend per UTC day. |
truncated | boolean | True when the server's row limit was hit, so by_machine may omit small machines. The total is still exact. |
GithubRunnerToken
A short-lived GitHub App installation token for one repository.
| Field | Type | Description |
|---|---|---|
token | string | The installation token. Scoped to repository with runner administration permissions and nothing else; GitHub expires it. |
expiresAt | string | GitHub's own expiry for token (RFC 3339), passed through verbatim: GitHub owns the lifetime. |
installationId | number | The GitHub App installation the token was minted under. Diagnostic: it names the installation in GitHub's own audit log. |
repository | string | owner/name: the only repository token works on. |
CreditBurn
One credits.burn, as the platform holds it.
| Field | Type | Description |
|---|---|---|
id | string | Stable id. Opaque: pass it back to Credits::unburn, never parse it. |
amountMicrocredits | number | Debited from the account, exactly. |
amountUsd | number | That amount in US dollars. |
keyId | string | undefined | The API key that burned, while its row exists. |
createdAt | number | When the burn was made. |
unburn | UnburnOutcome | undefined | How the burn ended. Absent until it is unburned. |
idempotencyKey | string | The idempotency key the burn was made under. |
UnburnOutcome
How a burn ended.
| Field | Type | Description |
|---|---|---|
spentMicrocredits | number | What the caller reported spent of the burn. |
spentUsd | number | That spend in US dollars. |
returnedMicrocredits | number | Credited back to the account. |
returnedUsd | number | That credit in US dollars. |
unburnedAt | number | When it was unburned. |
BurnReceipt
What a burn answers with.
| Field | Type | Description |
|---|---|---|
burnId | string | The burn's id. Opaque: pass it to Credits::unburn. |
amountMicrocredits | number | Debited from the account, exactly. |
balanceAfterMicrocredits | number | The account balance the burn left; for a deduplicated receipt, the balance the original burn left. |
deduplicated | boolean | True when the idempotency key named a burn the account had already made, and this is that burn's receipt rather than a new one. |
Group
A private network between machines.
| Field | Type | Description |
|---|---|---|
id | string | Stable id. Opaque: pass it back, never parse it. |
slug | string | The name every other verb here takes. |
ulaPrefix | string | The group's own IPv6 /64, in CIDR notation. Members get addresses inside it and nothing outside routes there. |
GroupMember
One machine's membership of a group.
| Field | Type | Description |
|---|---|---|
groupId | string | The group. |
machineId | string | The member machine. |
dnsName | string | Resolvable inside the group as <dns_name>.ix.internal. |
address | string | The address allocated to this member. |
AddedMember
The result of adding a member.
| Field | Type | Description |
|---|---|---|
member | GroupMember | The committed membership. |
attachesOnNextStart | boolean | The machine is running and booted without a NIC for this group, so the overlay attaches on its next start. Until then the membership is real and the interface is not -- which is why this is reported rather than left to be discovered as a peer that will not resolve. |
KeyBurn
One burn of a key, and the model gateway call it paid for.
| Field | Type | Description |
|---|---|---|
burn | CreditBurn | The burn. |
modelCall | ModelCall | undefined | The model gateway call this burn paid for. Absent for a burn made through Credits::burn. |
ModelCall
The model gateway call behind a burn.
| Field | Type | Description |
|---|---|---|
requestId | string | The call's request id. Its burn's idempotency key is model-gateway:<request_id>. |
model | string | The model the call named, as the gateway serves it. |
KeyBurnPage
One page of Keys::burns, newest first.
| Field | Type | Description |
|---|---|---|
burns | KeyBurn[] | The burns on this page. |
nextBefore | string | undefined | Pass back as before for the next page. Absent once the list is exhausted. |
Region
A region a machine can be placed in.
| Field | Type | Description |
|---|---|---|
id | string | Stable id. Opaque: pass it back, never parse it. |
slug | string | The slug used everywhere a region is named, e.g. us-west-1. This is what create's region argument takes. |
displayName | string | Human-readable name, for a picker. |
status | string | Whether the region is accepting work: active accepts placements, provisioning is coming up and not placing yet, draining keeps existing machines running while taking no new ones, and offline is not serving. |
ForkOptions
Options for machine.fork().
| Field | Type | Description |
|---|---|---|
name | string | undefined | The copy's name. The platform generates one when absent. |
lifetime | Lifetime | undefined | The copy's lifetime. A fork restores a snapshot and vm.restore has no lease slot, so anything but persistent is refused with InvalidArgument (before any snapshot is taken) rather than creating a persistent copy the caller believes expires. |
ttl | string | undefined | The copy's TTL; refused for the same reason as lifetime. |
CreateMachineOptions
Options for creating a machine.
| Field | Type | Description |
|---|---|---|
image | string | undefined | OCI image reference to boot: registry/repo:tag or registry/repo@sha256:..., such as ix/debian:12 or ghcr.io/owner/repo:1.2. The platform resolves it to a platform manifest digest once, at create; MachineInfo::image_digest reads the answer back. |
arch | Arch | undefined | The architecture to run on. Absent takes the architecture of the cheapest node with capacity, and MachineInfo::arch reads the answer back. An image with no manifest for it raises ImageNotAvailableForArch, listing the architectures it has. Refused when restoring a snapshot, which keeps the architecture it was captured on. |
registrySecret | string | undefined | Name of a stored secret (see secrets) holding the registry credentials for a private image: basic auth or a registry token. The platform reads it only to resolve and pull, never writes it to the machine, and a secret bound to another registry host raises ImageAuth. Refused when restoring a snapshot. |
entrypoint | string[] | undefined | Replace the image's ENTRYPOINT, as docker run --entrypoint does. Absent keeps the image's own; an empty list clears it. Refused when restoring a snapshot. |
command | string[] | undefined | Replace the image's CMD, as the trailing arguments of docker run do. Absent keeps the image's own; an empty list clears it. Refused when restoring a snapshot. |
snapshot | string | undefined | Snapshot id to restore into a new machine. |
lifetime | Lifetime | undefined | How long the machine lives. Absent is persistent: it lives until someone deletes it. |
ttl | string | undefined | The ephemeral deadline: an integer and one unit, s, m, h or d ("30m"), from one minute to seven days. Out of range or malformed is InvalidArgument, never clamped. A ttl alone makes the machine ephemeral; with lifetime: persistent it is refused. |
cpu | Cpu | undefined | Pin a host CPU class. Absent lets the scheduler pick any host of the architecture (a baseline machine). A class that contradicts arch is refused. A pinned machine sees its host's real CPU features and restores only on the same class; MachineInfo.cpu reads it back. |
name | string | undefined | Human-readable machine name. The platform generates one when absent. |
region | string | undefined | Region slug. When absent, IX_REGION applies, then the server's own default region -- the same ladder the CLI's --region flags resolve. |
env | std::collections::HashMap<String, String> | undefined | Plaintext environment variables for the image command. |
ipv4 | boolean | undefined | Whether to allocate a public IPv4 address. |
secretEnv | std::collections::HashMap<String, String> | undefined | Stored secret name to guest environment-variable name. |
secretFiles | std::collections::HashMap<String, String> | undefined | Stored secret name to guest file path. |
groups | string[] | undefined | East-west groups joined during creation. |
cpuCores | number | undefined | How many vCPUs the machine boots with. |
idempotencyKey | string | undefined | Name this create, so a retry finds its machine instead of booting a second one. |
readyWaitMs | number | undefined | How long to wait for the guest's own boot to finish, in milliseconds. Absent means five minutes. |
StopOptions
How machine.stop() stops the machine.
| Field | Type | Description |
|---|---|---|
force | boolean | undefined | Power the machine off without waiting for its guest to flush its filesystems. Writes the guest has not flushed are lost; the disk replays its journal on the next start. Absent or false refuses the stop with Conflict, and leaves the machine running, when the guest cannot flush. A guest that can never flush (unreachable, a frozen root filesystem) is stopped only this way, short of deleting it. |
RestartOptions
How machine.restart() stops the machine before starting it again.
| Field | Type | Description |
|---|---|---|
force | boolean | undefined | Hard-stop the running machine first, as StopOptions::force does. Writes the guest has not flushed are lost. |
MachineReadiness
How a create's readiness wait ended, with whichever detail the outcome carries.
| Field | Type | Description |
|---|---|---|
state | ReadinessState | Which of the three outcomes happened. Branch on this. |
readyAt | string | undefined | When the server observed the guest ready (RFC 3339). Ready only. Informational: it is a timestamp to log, never a signal to act on. |
waitedMs | number | undefined | How long the wait ran before giving up. NotReady only, and zero exactly when ready_wait_ms was 0 -- which is what tells a wait that was skipped apart from one that was exhausted. |
detail | string | undefined | The last thing the platform observed about the guest, verbatim, for humans. NotReady only, and not always set even there. |
MachineMetrics
A machine's resource usage, at a moment.
| Field | Type | Description |
|---|---|---|
machineId | string | The machine this is about. |
cpuPercent | number | CPU used, normalised to the machine's allocated cores: a fully pegged 8-core machine reads 100.0, not 800.0. |
memoryBytes | number | Guest memory in use. |
memoryLimitBytes | number | Guest memory allocated. |
memoryPercent | number | Memory in use as a percentage of the allocation. |
ioReadBytes | number | Bytes read from disk, cumulative since boot. |
ioWriteBytes | number | Bytes written to disk, cumulative since boot. |
networkRxBytes | number | Bytes received, cumulative since boot. |
networkTxBytes | number | Bytes sent, cumulative since boot. |
uptimeSecs | number | How long the machine has been up. |
collectedAt | number | When the sample was taken (Unix epoch milliseconds). |
MachineUsage
A machine's resource usage as a RATE, from the account-wide sample.
| Field | Type | Description |
|---|---|---|
machineId | string | The machine this is about. |
cpuPercent | number | CPU used, normalised to allocated cores. |
memoryBytes | number | Guest memory in use. |
memoryLimitBytes | number | Guest memory allocated. |
ioReadBytesPerSec | number | Disk read rate. |
ioWriteBytesPerSec | number | Disk write rate. |
netRxBytesPerSec | number | Inbound network rate. |
netTxBytesPerSec | number | Outbound network rate. |
collectedAt | number | When the sample was taken (Unix epoch milliseconds). |
LocalEndpoint
A machine address reachable directly from the caller's own network.
| Field | Type | Description |
|---|---|---|
machineId | string | The machine this address belongs to. |
ipv6 | string | The machine's IPv6 address, which is also its identity. |
ipv4 | string | undefined | Its IPv4 VIP, when one is allocated. |
ReloadedDaemons
Which in-guest daemons a reload restarted, and their new PIDs.
| Field | Type | Description |
|---|---|---|
ixVmGuestPid | number | undefined | New PID of the guest-side machine supervisor. |
ixConsolePid | number | undefined | New PID of the console bridge behind shell and the log streams. |
ixAgentPid | number | undefined | New PID of the in-guest agent behind exec, files, and forwards. |
StartupInfo
How long a machine's last start took, stage by stage.
| Field | Type | Description |
|---|---|---|
mode | string | How the machine came up: full_boot, golden_restore, or fork_restore. A full boot is the slow path; the two restores resume a captured image. |
totalMs | number | Wall time from the start request to a usable guest. |
rootfsPrepareMs | number | undefined | Materializing the root filesystem. |
bootMs | number | undefined | The guest kernel booting. |
goldenTemplateMs | number | undefined | Waiting on the golden template this machine restored from. |
createTapMs | number | undefined | Creating the host-side network tap. |
spawnVmmMs | number | undefined | Spawning the VMM process. |
vsockWaitMs | number | undefined | Waiting for the guest's vsock channel to answer. |
guestReadyMs | number | undefined | Waiting for the guest to report itself ready. |
GroupChanges
What an apply_groups reconcile actually changed.
| Field | Type | Description |
|---|---|---|
added | string[] | Slugs this call joined the machine to, sorted. |
removed | string[] | Slugs this call removed the machine from, sorted. |
DeleteResult
The outcome of deleting one machine in delete_many.
| Field | Type | Description |
|---|---|---|
id | string | The machine the delete was for. |
deleted | boolean | True once the platform accepted the delete. |
errorCode | string | undefined | The IxError variant name (NotFound, Conflict, ...) when the delete failed. |
errorMessage | string | undefined | The failure's message. |
StartedMigration
A migration that has just been started.
| Field | Type | Description |
|---|---|---|
id | string | Identifies this ATTEMPT, not the machine. This is what cancel takes. |
phase | string | The phase the coordinator recorded when the row was created. |
Migration
A machine migration in flight, or the last one attempted.
| Field | Type | Description |
|---|---|---|
id | string | Identifies this attempt, not the machine. This is what cancel takes. |
machineId | string | The machine being moved. |
sourceNodeId | string | The node it is moving off. |
targetNodeId | string | The node it is moving onto. |
phase | string | Where it has got to. completed, failed and cancelled are the terminal ones; everything else means still in flight. |
blackoutUs | number | undefined | How long the guest's vCPUs ran nowhere at all, in microseconds: from the source pausing them to the target resuming them, measured across the two hosts. This is the number that says whether the migration was live in practice, and the only one a caller should show a user as downtime. |
pauseUs | number | undefined | How long the SOURCE held the guest paused inside its capture call, in microseconds. |
bytesTransferred | number | undefined | Bytes moved to the target so far. |
failureReason | string | undefined | Why it failed, when it did. |
createdAt | number | When the migration was started (Unix epoch milliseconds). |
Attribute
One key/value on a span, an event, or a log line.
| Field | Type | Description |
|---|---|---|
key | string | The attribute name. |
value | string | Its value, rendered as text. |
TraceSummary
One trace, as a search result.
| Field | Type | Description |
|---|---|---|
traceId | string | The trace id, which is what trace(..) expands. |
rootSpanName | string | undefined | The name of the outermost span, when there is one. |
serviceNames | string[] | Every service the trace touched. |
startedAt | number | When the trace started (Unix epoch milliseconds). |
endedAt | number | When it finished. |
durationMs | number | How long it took. |
requestId | string | undefined | The API request it belongs to, if any. |
operationId | string | undefined | The long-running operation it belongs to, if any. |
spanCount | number | How many spans it contains. |
TraceSpan
One span in a trace.
| Field | Type | Description |
|---|---|---|
spanId | string | This span's id. |
parentSpanId | string | undefined | Its parent's id. Absent on a root span. |
depth | number | How deep it sits: 0 for a root, 1 for its children, and so on. |
name | string | The span's name. |
kind | string | Its kind, e.g. server, client, internal. |
serviceName | string | The service that emitted it. |
startedAt | number | When it started (Unix epoch milliseconds). |
durationNs | number | How long it took, in nanoseconds. Nanoseconds, not milliseconds: a span shorter than a millisecond is the common case in a trace and rounding it to zero would make the waterfall unreadable. |
statusCode | string | Its status, e.g. ok or error. |
statusMessage | string | undefined | Why it failed, when it did. |
requestId | string | undefined | The API request it belongs to, if any. |
operationId | string | undefined | The long-running operation it belongs to, if any. |
attributes | Attribute[] | Attributes set on the span itself. |
TraceEvent
One journald record correlated to a trace, in the flat fallback.
| Field | Type | Description |
|---|---|---|
timestamp | number | When it was written (Unix epoch milliseconds). |
unit | string | The systemd unit that wrote it. |
spanName | string | undefined | The span it was written inside, when it was. |
severity | string | undefined | Severity, derived from the journal priority. |
message | string | The line itself. |
fields | Attribute[] | Remaining structured fields. |
TraceWarning
A node whose journal could not be fully read, so a partial trace is visibly partial rather than silently short.
| Field | Type | Description |
|---|---|---|
hostname | string | The node. |
detail | string | What went wrong: a timeout, an RPC failure, truncation. |
TraceDetail
One trace, expanded.
| Field | Type | Description |
|---|---|---|
traceId | string | The trace this describes. |
source | string | clickhouse or journald; see above. |
spans | TraceSpan[] | The span tree, flattened pre-order. Empty on the journald path. |
events | TraceEvent[] | Flat journald records. Empty on the ClickHouse path. |
warnings | TraceWarning[] | Nodes the journald fan-out could not fully read. |
PlatformLog
One platform log line.
| Field | Type | Description |
|---|---|---|
timestamp | number | When it was emitted (Unix epoch milliseconds). |
traceId | string | undefined | The trace it belongs to, if any. |
spanId | string | undefined | The span it was emitted inside, if any. |
severity | string | undefined | Severity as the producer set it. |
serviceName | string | The service that emitted it. |
body | string | The line itself. |
eventName | string | undefined | The structured event name, when the line is one. |
requestId | string | undefined | The API request it belongs to, if any. |
operationId | string | undefined | The long-running operation it belongs to, if any. |
attributes | Attribute[] | Remaining structured fields. |
Preview
A disposable deployment, as the list reports it.
| Field | Type | Description |
|---|---|---|
id | string | Stable id. Opaque: pass it back, never parse it. |
imageTag | string | The image tag it was brought up from. |
status | string | The preview's own status. |
serviceCount | number | How many services it runs. |
healthyCount | number | How many of them are healthy. Equal to service_count when the preview is fully up. |
createdAt | number | When it was created (Unix epoch milliseconds). |
PreviewService
One service inside a preview.
| Field | Type | Description |
|---|---|---|
name | string | The service's name. |
status | string | Its status. |
PreviewDetail
A preview with a row per service: the diagnosis view, where the list's counts are the dashboard view.
| Field | Type | Description |
|---|---|---|
id | string | Stable id. Opaque: pass it back, never parse it. |
imageTag | string | The image tag it was brought up from. |
status | string | The preview's own status. |
createdAt | number | When it was created (Unix epoch milliseconds). |
services | PreviewService[] | Every service, and where each one got to. |
ExecOptions
Options for Machine::exec and Machine::shell.
| Field | Type | Description |
|---|---|---|
cwd | string | undefined | Guest directory to run in. Absent is the guest's default. |
stdin | boolean | undefined | Open the command's stdin, so process.stdin can write to it and close it. Without it the command reads /dev/null. |
check | boolean | undefined | Raise IxError::CommandFailed from the await when the command exits non-zero, instead of returning the exit code as a result. |
maxBuffer | number | undefined | How many bytes of each stream the awaited result keeps; 16 MiB when absent. Past it the result sets truncated. The live streams are never capped. |
OutputChunk
One chunk of a command's merged output.
| Field | Type | Description |
|---|---|---|
stream | OutputStream | Which stream wrote it. |
atMs | number | Milliseconds since the process started, measured by the client as the chunk arrived. Arrival order, not a guest clock: when one guest write carries both streams, stdout comes first. |
data | number[] | The bytes, exactly as written. A chunk boundary can fall inside a multi-byte character, so decode across chunks, or read text. |
MachineProgress
One step of a long-running machine operation, or its result.
| Field | Type | Description |
|---|---|---|
kind | string | Event name, e.g. PullingImage, StepStarted, or Finished / Failed on the terminal frame. |
message | string | Human-readable message. Empty when the phase carries none. |
finished | boolean | Whether this is the terminal frame. Prefer this to comparing kind: it is a boolean the compiler can check, where a string sentinel is one typo away from a loop that never ends. |
machine | MachineInfo | undefined | Set on the terminal frame only: the finished machine. |
error | string | undefined | Set on the terminal frame only, and only when the operation failed. Exactly one of machine and error is set there. |
deduplicated | boolean | undefined | Set on a successful CREATE's terminal frame: whether the create replayed an earlier one carrying the same idempotencyKey instead of booting a new machine. Absent on start and restore frames, which have no key to replay. |
readiness | MachineReadiness | undefined | Set on a successful CREATE's terminal frame: how its wait for the guest to boot ended. Absent on start and restore frames. |
stepId | number | undefined | The instrumented step this belongs to, for the Step* phases. Correlates a StepStarted with its later StepProgress and StepDone, which matters once steps interleave. |
machineId | string | undefined | The machine this phase is about, when it names one. Also set on the terminal frame, where it is machine.id. |
node | string | undefined | AllocatingVm: physical node the machine was placed on. |
region | string | undefined | AllocatingVm: public region slug, e.g. us-west-1. |
done | number | undefined | StepProgress: items completed so far. |
total | number | undefined | StepStarted / StepProgress: total items, so a determinate bar can render done out of total. |
elapsedMs | number | undefined | Wall time spent in the phase or substep. |
fileCount | number | undefined | RootfsConverted: files in the converted image. |
blockCount | number | undefined | RootfsConverted: blocks in the converted image. |
totalBytes | number | undefined | RootfsConverted: total bytes. |
fromCache | boolean | undefined | RootfsConverted: whether the conversion cache was reused. |
itemCount | number | undefined | Manifest file or chunk-reference count, by stage. |
cached | boolean | undefined | IndexingRootfsManifest: whether a cached manifest was found. |
cacheReason | string | undefined | IndexingRootfsManifest: why the cache did or did not hit. |
newChunks | number | undefined | RegisteredRootfsChunks: legacy per-chunk-ref count. |
committedAt | number | undefined | ServerVersion: when the serving build was committed (Unix epoch seconds). |
ShellInfo
One shell session running on a machine.
| Field | Type | Description |
|---|---|---|
id | number | Session number, as Machine::attach_shell takes it. |
command | string[] | The argv the session was started with. |
attached | boolean | Whether a client is attached right now. |
exited | boolean | Whether the process has exited. An exited session still lists until it is reaped, so its output can be read one last time. |
Scope
One permission grant on a key.
| Field | Type | Description |
|---|---|---|
resource | string | Resource family, e.g. vm. |
actions | string[] | Actions permitted on it. ["*"] is every action. |
ports | number[] | undefined | Guest ports a vm:port_forward grant reaches. Absent means every port, which is what every other grant carries. |
ApiKey
An API key, as the platform holds it.
| Field | Type | Description |
|---|---|---|
id | string | Stable id. Opaque: pass it back, never parse it. |
name | string | Caller-chosen label. Not unique, not an identifier. |
keyPrefix | string | undefined | Leading, non-secret slice of the key, for display. |
scopes | Scope[] | The permissions this key carries. |
limitMicrocredits | number | undefined | Spend cap, or absent for uncapped. |
limitUsd | number | undefined | Spend cap in US dollars, derived from the integer above. |
consumedMicrocredits | number | Spent against the cap so far. Lags real usage by seconds: metering is asynchronous, so a cap is an optimistic circuit breaker. |
consumedUsd | number | Spend so far in US dollars, derived from the integer above. |
remainingMicrocredits | number | undefined | Cap minus consumption, or absent when uncapped. |
remainingUsd | number | undefined | Headroom in US dollars, derived from the integer above. |
state | string | One of active, disabled, revoked. disabled is reversible and keeps the secret; revoked is permanent and cascades. |
createdAt | number | When the key was minted (Unix epoch milliseconds). |
expiresAt | number | undefined | When the key stops authenticating on its own, if ever. |
lastUsedAt | number | undefined | Last successful authentication, if any. |
parentId | string | undefined | The key this one was minted under, if it is a child. |
MachineInfo
A machine, as the platform holds it.
| Field | Type | Description |
|---|---|---|
id | string | Stable id. Opaque: pass it back, never parse it. |
name | string | Caller-chosen name, unique within the account. |
imageReference | string | The OCI reference the machine was created from, as the caller gave it (ix/debian:12). Empty for a machine created before images were resolved to digests. |
imageDigest | string | The sha256:<hex> digest of the per-architecture manifest the machine runs. Tags are for humans and this is what ran: re-creating from the same tag later can give a different digest. A restart, restore or fork keeps it. Empty for a machine created before images were resolved to digests. |
arch | Arch | undefined | The architecture the machine runs on, as recorded at create. Absent for a machine created before the platform recorded it; never an assumed value. |
cpu | Cpu | undefined | The host CPU class the machine is pinned to. Absent for a baseline machine (any host of its architecture), which is every machine created without cpu. |
status | MachineStatus | What the machine's lifecycle is doing. |
ipv6 | string | The machine's IPv6 address, which is also its identity on the network. |
ipv4 | string | undefined | IPv4 address, when one is allocated. |
memoryMib | number | Guest RAM. |
cpuCores | number | Guest vCPUs. |
region | string | undefined | Region slug, when the machine is placed in one. |
internetIngress | boolean | Whether the machine accepts inbound internet traffic. |
internetEgress | boolean | Whether the machine may send outbound internet traffic. |
failureReason | string | undefined | Why the machine failed, when it did. Absent on a healthy machine. |
createdAt | number | When the machine row was created (Unix epoch milliseconds). |
startedAt | number | undefined | When the machine last started, if it ever has. |
stoppedAt | number | undefined | When the machine last stopped, if it ever has. |
ExecResult
What a finished command produced: what awaiting a Process returns.
| Field | Type | Description |
|---|---|---|
exitCode | number | The process's exit status. Zero is success. |
stdout | string | The first maxBuffer bytes the process wrote to stdout, decoded as UTF-8 with invalid sequences replaced. Read process.stdout for the exact bytes. |
stderr | string | The first maxBuffer bytes the process wrote to stderr, decoded the same way. |
truncated | boolean | Whether either stream wrote more than maxBuffer (16 MiB each by default) and the rest was dropped from this result. The live streams are never capped. |
LogEntry
One line of machine output.
| Field | Type | Description |
|---|---|---|
timestamp | number | When the line was emitted (Unix epoch milliseconds). |
stream | LogStream | Which capture it came from. |
message | string | The line itself. |
DirEntry
One entry in a guest directory.
| Field | Type | Description |
|---|---|---|
name | string | Entry name, without its parent path. |
path | string | Full path inside the guest. |
isDir | boolean | Whether the entry is a directory. |
size | number | Size in bytes. Zero for directories. |
mode | number | POSIX mode bits. |
modifiedAt | number | Last modification (Unix epoch milliseconds). |
MachineStatusEvent
A machine's status, at a moment.
| Field | Type | Description |
|---|---|---|
machineId | string | The machine this is about. |
status | MachineStatus | What the machine's lifecycle is doing. |
timestamp | number | When the server observed it (Unix epoch milliseconds). |
Snapshot
A point-in-time capture of a machine.
| Field | Type | Description |
|---|---|---|
id | string | Stable id. This is what restore takes -- NOT the machine's id. |
machineId | string | The machine this was captured from. |
parentId | string | undefined | The snapshot this one was captured on top of, if any. |
status | SnapshotStatus | How far along the capture is. Only a SnapshotStatus::Ready snapshot can be restored. |
memoryMib | number | Guest RAM captured with it. |
createdAt | number | When the capture started (Unix epoch milliseconds). |
UsageSummary
The account's balance and lifetime totals.
| Field | Type | Description |
|---|---|---|
balanceMicrocredits | number | Credit remaining. Can be negative: the platform lets a balance go under zero rather than cutting a running workload dead. |
balanceUsd | number | Credit remaining, in US dollars. |
totalAddedMicrocredits | number | Everything ever added to the account. |
totalAddedUsd | number | Everything ever added, in US dollars. |
spentMicrocredits | number | Everything ever spent. |
spentUsd | number | Everything ever spent, in US dollars. |
CreatedKey
A freshly minted key and its secret.
| Field | Type | Description |
|---|---|---|
key | ApiKey | The key, exactly as list would later report it. |
secret | string | The raw secret to authenticate with. Store it now. |
Me
The authenticated account.
| Field | Type | Description |
|---|---|---|
id | string | Stable user id. |
username | string | Login handle. |
email | string | undefined | Contact address, if the account has one. |
SnapshotRef
A captured snapshot and the machine it was captured from.
| Field | Type | Description |
|---|---|---|
snapshotId | string | The snapshot's id. This is what snapshots.restore takes. |
machine | MachineInfo | The machine as it stood when the capture was taken. |
RuntimeStatus
What the platform can see of a machine's live runtime, from its host.
| Field | Type | Description |
|---|---|---|
present | boolean | Whether the platform is tracking this machine's runtime at all. When false every field below is absent and Self::absence_reason says why -- a stopped machine has no runtime, and that is not a fault. |
absenceReason | string | undefined | Why there is no runtime to report: not_tracked_by_node_agent or not_tracked_by_vmm. Absent when Self::present. |
state | string | undefined | The VMM's state machine position: running, paused, pause_requested, capture_requested, captured, shutdown_requested, shutdown, failed, running_and_capturing, or unknown. |
memoryMib | number | undefined | Guest RAM the VMM currently has plugged in. Moves under virtio-mem, so it is not necessarily the machine's configured size. |
guestRpcTransportReady | boolean | undefined | Whether the guest RPC transport has come up. This is the channel exec and the filesystem verbs ride, so false explains why they fail on a machine that is otherwise running. |
virtioMemTransportReady | boolean | undefined | Whether the virtio-mem transport has come up. |
health | string | undefined | The worker's overall verdict: healthy, degraded, or failed. Absent when the VMM reported no health block. |
issues | string[] | Every subsystem fault currently present, as subsystem.slot: diagnostic, e.g. control.guest_rpc_transport: ... or vcpu.3: .... Empty on a healthy machine. |
Secret
One stored account secret. Metadata only, never the value.
| Field | Type | Description |
|---|---|---|
name | string | The name the value is stored under, and the name a machine reads it by. |
createdAt | number | When it was first stored (Unix epoch milliseconds). |
updatedAt | number | When it was last overwritten. |
SecretRotation
How far a rotation propagated.
| Field | Type | Description |
|---|---|---|
machinesUpdated | number | machines whose stored copy was refreshed. |
filesRefreshed | number | File-injected secrets rewritten inside running guests. |
pendingNextBoot | number | Copies whose new value applies at the machine's next start: env-injected secrets, and anything on a stopped machine. |
failedMachines | string[] | machines the push could not reach. |
failedRegions | string[] | Regions whose machine enumeration failed, so machines there were not visited at all. |
SecretWrite
The result of storing an account secret.
| Field | Type | Description |
|---|---|---|
secret | Secret | The stored secret's metadata. |
rotation | SecretRotation | undefined | Present only when the write OVERWROTE an existing value. Absent on a first write, because there was nothing to propagate. |
MachineSecret
One secret materialized into a single machine. Metadata only.
| Field | Type | Description |
|---|---|---|
id | string | Stable id. Opaque: pass it back, never parse it. |
name | string | The name the guest reads it by. |
injectAs | string | How the guest receives it: env or file. |
createdAt | number | When it was materialized (Unix epoch milliseconds). |
updatedAt | number | When it was last refreshed. |
Volume
A persistent disk.
| Field | Type | Description |
|---|---|---|
id | string | Stable id. Opaque: pass it back, never parse it. |
name | string | Caller-chosen name. |
machineId | string | undefined | The machine it is attached to, if any. |
sizeBytes | number | Size on disk, in bytes. |
createdAt | number | When it was created (Unix epoch milliseconds). |
updatedAt | number | When it last changed. |
VolumeSnapshot
A point-in-time capture of a volume.
| Field | Type | Description |
|---|---|---|
id | string | Stable id. Opaque: pass it back, never parse it. |
volumeId | string | The volume this was captured from. |
name | string | Caller-chosen name. |
createdAt | number | When it was captured (Unix epoch milliseconds). |