Installing the `ice` executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install ice-tool

It will make the ice command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall ice-tool uninstalls.

Back to the crate overview.

Readme

ice

Minimal CLI for deploying and managing workloads on vast.ai, gcp, aws, and local.

Install

cargo install ice-tool

Installed command: ice

Quick start

ice login --cloud vast.ai
ice deploy test-crate
ice list --cloud vast.ai
ice logs --cloud vast.ai <instance> --follow
ice delete --cloud vast.ai <instance>

Clouds

Supported cloud identifiers:

vast.ai
gcp
aws
local

Commands

ice login [--cloud CLOUD] [--force]
ice config list
ice config get <KEY>
ice config set <KEY=VALUE>
ice config unset <KEY>
ice list [--cloud CLOUD]
ice logs [--cloud CLOUD] <INSTANCE> [--tail N] [--follow]
ice shell [--cloud CLOUD] <INSTANCE>
ice pull [--cloud CLOUD] <INSTANCE> <REMOTE_PATH> [LOCAL_PATH]
ice push [--cloud CLOUD] <INSTANCE> <LOCAL_PATH> [REMOTE_PATH]
ice stop [--cloud CLOUD] <INSTANCE>
ice start [--cloud CLOUD] <INSTANCE>
ice delete [--cloud CLOUD] <INSTANCE>
ice deploy [--cloud CLOUD] [--hours HOURS] [--machine MACHINE] [--custom] [--dry-run] [--ssh | --container IMAGE_REF | --unpack SOURCE | --arca [ARTIFACT] | TARGET]

<INSTANCE> accepts an instance id or label.

Config

Config file: ~/.ice/config.toml

Use:

ice config list to view supported keys and current values
ice config get <KEY> to read one key
ice config set <KEY=VALUE> to write one key
ice config unset <KEY> to clear one key

Auth values are redacted in config output.

Config keys

default.cloud: vast.ai|gcp|aws|local
default.runtime_hours
default.vast_ai.min_cpus|min_ram_gb|allowed_gpus|max_price_per_hr
default.gcp.min_cpus|min_ram_gb|allowed_gpus|max_price_per_hr
default.aws.min_cpus|min_ram_gb|allowed_gpus|max_price_per_hr
default.gcp.region|zone|image_family|image_project|boot_disk_gb
default.aws.region|ami|key_name|ssh_key_path|ssh_user|security_group_id|subnet_id|root_disk_gb
auth.vast_ai.api_key
auth.gcp.project|service_account_json
auth.aws.access_key_id|secret_access_key

`ice deploy`

ice deploy now takes exactly one deployment target mode explicitly, or defaults to local arca unpack deployment when none is given.

Target modes:

--ssh
--container IMAGE_REF
--unpack SOURCE
--arca [ARTIFACT]
bare TARGET

Behavior:

ice deploy test-crate means ice deploy --arca test-crate.
Bare ice deploy means ice deploy --arca, which selects the newest local arca artifact.
--arca NAME is shorthand for --unpack arca:NAME.
--container accepts a remote container image ref such as us-central1-docker.pkg.dev/my-project/arca/my-image:tag.
--container arca:... is rejected because local arca artifacts are an unpack-only flow.
--unpack accepts:
- arca:selector
- a local image name such as arca-local:my-crate-deadbeef
- a saved image.tar path
- a full remote container ref
--hours overrides runtime duration for the deploy. If omitted, ice uses default.runtime_hours and otherwise falls back to 1.0.
--custom prompts for search filters on marketplace-backed clouds.
--machine pins a specific marketplace machine type.
--dry-run reports the chosen machine and exits before provisioning.

Examples:

ice deploy test-crate
ice deploy --arca test-crate --hours 0.25
ice deploy --unpack arca:test-crate --cloud vast.ai
ice deploy --container us-central1-docker.pkg.dev/my-project/arca/my-image:tag --cloud vast.ai
ice deploy --ssh --cloud gcp --machine g2-standard-4

Workload behavior

container runs a real container image on the target machine.
unpack extracts the layer that introduced the image entrypoint plus all higher layers, uploads only that staged filesystem diff, and starts the image entrypoint detached with persisted logs.
local supports container and unpack. It does not support --ssh.
vast.ai container workloads use entrypoint mode, not SSH mode.
vast.ai, gcp, and aws unpack workloads boot a shell-capable machine, upload the unpack bundle over SSH, and run the workload detached from the SSH session.
Deploy flows print explicit stages for machine creation, SSH readiness, unpack upload, workload start, and log following.
If Vast offer acceptance fails, ice deploy can immediately retry the search interactively.

Logs and shell

ice logs shows stdout and stderr for managed workloads.
For unpack, logs come from the persisted detached stdio.log and --follow exits automatically after the workload finishes and the final output is drained.
For container on vast.ai, logs use Vast's provider API.
ice shell opens the workload shell when possible and otherwise falls back to the host shell.

Notes

--cloud can be omitted when default.cloud is configured.
ice list --cloud local reports both managed local containers and managed local unpack workloads.
Private GCP registry pulls use your configured GCP credentials or active gcloud authentication.
External commands used by some flows: ssh, rsync, gcloud, aws, docker, podman.

Installing the ice executable

Installing the `ice` executable