stratumctl instances

Manage compute instances

stratumctl instances [flags]

Aliases: instance, vms, vm

Subcommands

stratumctl instances console-serial: Issue a serial-console session URL (single-use, 60s TTL)
stratumctl instances console-vnc: Issue a VNC graphical console URL (single-use, 60s TTL)
stratumctl instances create: Launch an instance (async; returns 202 + initial row)
stratumctl instances disable-agent: Disable the in-VM agent on an instance and uninstall it from the guest
stratumctl instances enable-agent: Enable the in-VM agent on an instance (prints an install command if the image needs one)
stratumctl instances get: Describe an instance
stratumctl instances list: List instances in a project
stratumctl instances port-forward: Forward a local TCP port to a port on an instance
stratumctl instances reboot: Reboot a running instance (async)
stratumctl instances refresh-agent: Upgrade the in-VM agent in place on instances (no relaunch)
stratumctl instances retry: Retry an error-state instance (re-runs the creation pipeline against the existing row)
stratumctl instances run-command: Run a command on instances and collect output
stratumctl instances sessions: Inspect Session Manager sessions for an instance
stratumctl instances ssh: Connect to an instance over SSH with a short-lived Stratum certificate
stratumctl instances start: Start a stopped instance (async)
stratumctl instances stop: Gracefully stop a running instance (async)
stratumctl instances terminate: Terminate an instance (async; soft-deleted for 7d)
stratumctl instances update: Update an instance’s mutable fields (display-name, description, tags, protection flags)

stratumctl instances console-serial

Issue a serial-console session URL (single-use, 60s TTL)

stratumctl instances console-serial <instance-id> [flags]

Examples

stratumctl instances console-serial i-uy3ureaklq

Flags

Flag	Type	Default	Description
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)

stratumctl instances console-vnc

Issue a VNC graphical console URL (single-use, 60s TTL)

stratumctl instances console-vnc <instance-id> [flags]

Examples

stratumctl instances console-vnc i-uy3ureaklq

Flags

Flag	Type	Default	Description
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)

stratumctl instances create

Launch an instance (async; returns 202 + initial row)

stratumctl instances create <name> [flags]

Examples

stratumctl instances create web-01 --image img-k3m9x2abqt --instance-type m1.small --subnet subnet-7q2x9k4m
stratumctl instances create web-02 --image img-k3m9x2abqt --instance-type m1.large --subnet subnet-7q2x9k4m \
  --security-group sg-3f8d2k9x --key-pair axel-laptop --user-data-file cloud.yaml --public-ip
stratumctl instances create big-01 --image img-k3m9x2abqt --vcpus 6 --memory-bytes 12884901888 --subnet subnet-7q2x9k4m

Flags

Flag	Type	Default	Description
`--autostart`	bool	`false`	Start the instance on every controlplane boot. Takes effect on the NEXT boot.
`--az`	string		Availability zone (defaults to install’s default AZ)
`--description`	string		Free-form description
`--display-name`	string		Human-friendly display name
`--floating-ip-pool`	string		Region tag (or ‘default’ for the instance’s region) — auto-allocates a FIP + associates it with the primary NIC..
`--image`	string		Image ID (img-…; required)
`--instance-type`	string		Catalog instance type name (e.g. m1.large). XOR’d with –vcpus + –memory-bytes for custom-shape launches.
`--key-pair`	string		Key pair name (optional; must belong to the project)
`--memory-bytes`	int64	`0`	custom-shape memory in bytes (minimum 1 MiB). Required when –instance-type is empty; ignored otherwise.
`--no-network`	bool	`false`	Launch with no network interface at all. Without it, no –subnet means the project’s default subnet, and a project with none refuses the launch.
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)
`--public-ip`	bool	`false`	Shorthand for –floating-ip-pool=default — assigns a public IP at launch from the install’s first pool in the instance’s region. AWS-shape `--associate-public-ip-address`.
`--root-storage-class`	string		Storage class for the auto-provisioned root volume (ignored if –root-volume is set)
`--root-volume`	string		Pre-provisioned root volume ID (vol-…). Optional — when omitted, the compute service auto-provisions one from the image.
`--root-volume-size-bytes`	int64	`0`	Size override for the auto-provisioned root volume (ignored if –root-volume is set)
`--security-group`	stringSlice		Security group(s) bound to the auto-provisioned primary NIC
`--stop-protection`	bool	`false`	Reject stop until disabled
`--subnet`	stringSlice		Subnet ID(s) to attach NICs to. The first becomes the primary NIC; v1 multi-NIC support is forward-compat.
`--termination-protection`	bool	`false`	Reject terminate until disabled
`--user-data`	string		cloud-init user-data (literal; 64 KiB cap)
`--user-data-file`	string		Path to a file containing cloud-init user-data
`--vcpus`	int	`0`	custom-shape vCPU count. Required when –instance-type is empty; ignored otherwise.

stratumctl instances disable-agent

Disable the in-VM agent on an instance and uninstall it from the guest

stratumctl instances disable-agent <instance-id> [flags]

Disable the in-VM agent on an existing instance. The agent loses access to the metadata service’s agent endpoints at once and a connected agent uninstalls itself; the result says whether the guest was reached. If the instance’s image ships the agent dormant (agentActivation: automatic), the agent stops within a minute instead and its package stays installed. The instance then reports health agent_disabled and no longer counts toward the instances-unhealthy alarm.

stratumctl instances disable-agent i-abc123

Examples

stratumctl instances disable-agent i-0a1b2c3d4e5f

Flags

Flag	Type	Default	Description
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)

stratumctl instances enable-agent

Enable the in-VM agent on an instance (prints an install command if the image needs one)

stratumctl instances enable-agent <instance-id> [flags]

Enable the in-VM agent on an existing instance.

If the instance’s image ships the agent dormant (agentActivation: automatic), the agent starts in the guest within a minute and there is nothing to run.

Otherwise nothing is installed until the printed command runs in the guest, as a user that can sudo: it enrolls with the instance metadata service and installs the agent the way a launch with the agent does. The command works once, only in this instance, for one hour. On an instance whose agent is already enabled this only issues a new command, to retry or repair an install; earlier unused commands stop working.

–force prints the install command even when the image ships the agent dormant: for a guest whose agent package was removed, where nothing is left to start. The instance then takes the install command for good (agentActivation: install-command): disable-agent uninstalls the agent, and images created from the instance no longer claim the dormant agent.

stratumctl instances enable-agent i-abc123
stratumctl instances enable-agent i-abc123 --force

Examples

stratumctl instances enable-agent i-0a1b2c3d4e5f
stratumctl instances enable-agent i-0a1b2c3d4e5f --output json
stratumctl instances enable-agent i-0a1b2c3d4e5f --force

Flags

Flag	Type	Default	Description
`--force`	bool	`false`	Print an install command even if the image ships the agent dormant (its package was removed in the guest)
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)

stratumctl instances get

Describe an instance

stratumctl instances get <instance-id> [flags]

Examples

stratumctl instances get i-uy3ureaklq
stratumctl instances get i-uy3ureaklq --output json

Flags

Flag	Type	Default	Description
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)

stratumctl instances list

List instances in a project

stratumctl instances list [flags]

Examples

stratumctl instances list
stratumctl instances list --project p-team-a --state running --output json

Flags

Flag	Type	Description
`--az`	string	Filter by availability zone
`--node`	string	Filter by hypervisor node ID
`--project`	string	Project ID (defaults to STRATUM_PROJECT or profile project_id)
`--state`	string	Filter by state (running \| stopped \| terminated \|…)

stratumctl instances port-forward

Forward a local TCP port to a port on an instance

stratumctl instances port-forward <instance-id> --local <port> --remote <port> [flags]

Aliases: forward

Forward a local TCP port to a port on an instance over the Session Manager rail — no floating IP, bastion, or inbound port needed. The in-VM agent dials the target port on the instance’s loopback; the control plane relays the raw TCP stream to a listener on your machine.

stratumctl instances port-forward i-abc123 --local 5432 --remote 5432
stratumctl instances port-forward i-abc123 --local 8080 --remote 80 --project p-team

Then point your client at localhost:<local>. Press Ctrl+C to stop.

Concurrency: one forwarded connection at a time per instance in v1 (the agent rail runs a single session per channel); a second simultaneous connection is rejected until the first closes. Multi-connection multiplexing is a follow-up.

Examples

stratumctl instances port-forward i-uy3ureaklq --local 5432 --remote 5432
stratumctl instances port-forward i-uy3ureaklq --remote 8080 --address 0.0.0.0

Flags

Flag	Type	Default	Description
`--address`	string	`127.0.0.1`	Local address to bind the listener to
`--local`	int	`0`	Local TCP port to listen on (0 = pick a free port)
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)
`--remote`	int	`0`	Target TCP port on the instance’s loopback (required)

stratumctl instances reboot

Reboot a running instance (async)

stratumctl instances reboot <instance-id> [flags]

Examples

stratumctl instances reboot i-uy3ureaklq

Flags

Flag	Type	Default	Description
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)

stratumctl instances refresh-agent

Upgrade the in-VM agent in place on instances (no relaunch)

stratumctl instances refresh-agent [flags]

Re-fetch the current agent binary and reinstall the systemd unit set on each target over its live Session Manager channel (no floating IP / relaunch). An instance launched before a unit existed (e.g. the inventory units) gains it. Requires a LIVE agent channel; an instance whose agent was never enabled at all has no rail to reach and still needs a relaunch — that is reported per-instance.

Each result names the method the refresh used. agent-root: the agent ran the refresh as root itself and checked the installed binary against the served checksum. sudo-fallback: the agent predates that, so the refresh ran as its login user through passwordless sudo, and fails with a clear error when that user has no sudo.

stratumctl instances refresh-agent --instances i-a,i-b

Examples

stratumctl instances refresh-agent --instances i-uy3ureaklq,i-5mq8x2ab4k

Flags

Flag	Type	Default	Description
`--instances`	stringSlice		Target instance ids (comma-separated, up to 100)
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)

stratumctl instances retry

Retry an error-state instance (re-runs the creation pipeline against the existing row)

stratumctl instances retry <instance-id> [flags]

Examples

stratumctl instances retry i-uy3ureaklq

Flags

Flag	Type	Default	Description
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)

stratumctl instances run-command

Run a command on instances and collect output

stratumctl instances run-command [flags]

Aliases: run, send-command

Run a non-interactive command on one or more instances over the Session Manager rail (no floating IP / inbound port needed) and collect each instance’s combined stdout+stderr (truncated to 64 KiB) + exit code.

stratumctl instances run-command --instances i-a,i-b --command "uptime; df -h /"

Examples

stratumctl instances run-command --instances i-uy3ureaklq --command "uptime"
stratumctl instances run-command --instances i-uy3ureaklq,i-5mq8x2ab4k --command "df -h /" --timeout 2m

Flags

Flag	Type	Default	Description
`--command`	string		Command line to run on each instance
`--instances`	stringSlice		Target instance ids (comma-separated, up to 100)
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)
`--timeout`	duration	`0s`	Per-command timeout (e.g. 30s, 2m; default 60s, max 10m)

stratumctl instances sessions

Inspect Session Manager sessions for an instance

stratumctl instances sessions [flags]

Aliases: session

Subcommands

stratumctl instances sessions describe: Describe one Session Manager session
stratumctl instances sessions list: List sessions opened into an instance (newest first)

stratumctl instances sessions describe

Describe one Session Manager session

stratumctl instances sessions describe <instance-id> <session-id> [flags]

Aliases: get

Examples

stratumctl instances sessions describe i-uy3ureaklq sess-4k8m2x7q

Flags

Flag	Type	Default	Description
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)

stratumctl instances sessions list

List sessions opened into an instance (newest first)

stratumctl instances sessions list <instance-id> [flags]

Examples

stratumctl instances sessions list i-uy3ureaklq
stratumctl instances sessions list i-uy3ureaklq --output json

Flags

Flag	Type	Default	Description
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)

stratumctl instances ssh

Connect to an instance over SSH with a short-lived Stratum certificate

stratumctl instances ssh <instance-id> [-- SSH_ARGS...] [flags]

Sign a short-lived SSH certificate for an instance and connect to it.

By default an ephemeral keypair is generated, signed (scoped to the instance), and discarded when the session ends — you manage no keys. The certificate principal defaults to the instance login user (stratum-ssh), which the blessed image trusts via the project CA.

Anything after a literal – is passed straight through to ssh.

Examples:

stratumctl instances ssh i-abc123 --project p-team
stratumctl instances ssh i-abc123 --project p-team -- -L 8080:localhost:80
stratumctl instances ssh i-abc123 --project p-team --identity-file ~/.ssh/id_ed25519

Examples

stratumctl instances ssh i-uy3ureaklq
stratumctl instances ssh i-uy3ureaklq --tunnel
stratumctl instances ssh i-uy3ureaklq --identity-file ~/.ssh/id_ed25519 -- -L 8080:localhost:80

Flags

Flag	Type	Default	Description
`--identity-file`	string		Use this private key instead of an ephemeral one (its.pub is signed)
`--print`	bool	`false`	Print the ssh command instead of running it
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)
`--tunnel`	bool	`false`	Force the Session Manager tunnel (no floating IP / inbound port needed) instead of direct SSH
`--user`	string	`stratum-ssh`	SSH login user
`--valid-for`	duration	`0s`	Requested certificate validity (e.g. 15m, 1h); clamped to the project ceiling

stratumctl instances start

Start a stopped instance (async)

stratumctl instances start <instance-id> [flags]

Examples

stratumctl instances start i-uy3ureaklq

Flags

Flag	Type	Default	Description
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)

stratumctl instances stop

Gracefully stop a running instance (async)

stratumctl instances stop <instance-id> [flags]

Examples

stratumctl instances stop i-uy3ureaklq
stratumctl instances stop i-uy3ureaklq --force

Flags

Flag	Type	Default	Description
`--force`	bool	`false`	Hard stop: destroy the domain at once instead of a graceful shutdown (unflushed guest data is lost)
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)

stratumctl instances terminate

Terminate an instance (async; soft-deleted for 7d)

stratumctl instances terminate <instance-id> [flags]

Examples

stratumctl instances terminate i-uy3ureaklq

Flags

Flag	Type	Default	Description
`--project`	string		Project ID (defaults to STRATUM_PROJECT or profile project_id)

stratumctl instances update

Update an instance’s mutable fields (display-name, description, tags, protection flags)

stratumctl instances update <instance-id> [flags]

Examples

stratumctl instances update i-uy3ureaklq --display-name "web 01"
stratumctl instances update i-uy3ureaklq --termination-protection --tag env=prod --tag team=a

Flags

Flag	Type	Default	Description
`--autostart`	bool	`false`	Toggle boot-time autostart. Takes effect on the NEXT controlplane boot, not retroactively.
`--description`	string		New description
`--display-name`	string		New human-readable display name
`--project`	string		Project ID (defaults to env STRATUM_PROJECT or profile)
`--stop-protection`	bool	`false`	Block accidental stop
`--tag`	stringSlice		Tag key=value (repeat for multiple; replaces the entire tags map)
`--termination-protection`	bool	`false`	Block accidental terminate