CLI Reference

Global Flags

These flags are available on every command.

The API key can also be stored in ~/.config/irons/config.yml:

api_key: your-api-key

Addressing Sandboxes

Every command that targets a specific sandbox accepts either the sandbox name or its VM ID (which starts with vm_). If the value doesn’t start with vm_, it is treated as a name and the first non-destroyed sandbox with that name is used.

# These are equivalent:
irons status my-sandbox
irons status vm_abc123

login

Authenticate and save an API key to the local config file.

irons login

Opens a browser-based device authorization flow. On completion the API key is written to ~/.config/irons/config.yml and used automatically by all subsequent commands.

onboard

Interactive first-run setup flow. Walks through account authentication, GitHub token configuration, agent provider selection, SSH key registration, and optionally creates a first agent. Safe to re-run — each step is idempotent.

irons onboard [flags]

create

Provision a new sandbox.

irons create <name> [flags]

If --key is not provided, the following key files are checked in order and the first one found is used:

1. ~/.ssh/id_ed25519.pub
2. ~/.ssh/id_ed25519_sk.pub
3. ~/.ssh/id_ecdsa.pub
4. ~/.ssh/id_ecdsa_sk.pub
5. ~/.ssh/id_rsa.pub

By default the command blocks until the sandbox reaches the ready state.

Examples

irons create my-sandbox
irons create my-sandbox --key ~/.ssh/agent.pub
irons create my-sandbox --snapshot snap_x9f2km4p
irons create my-sandbox --async

list

List all sandboxes on the account.

irons list

Displays a table of every sandbox with its name, ID, status, and creation date.

status

Show the current status and metadata of a sandbox.

irons status <name|id>

start

Start a sandbox that was previously stopped.

irons start <name|id> [flags]

By default the command blocks until the sandbox reaches the ready state.

stop

Stop a running sandbox. The sandbox can be restarted later with start.

irons stop <name|id> [flags]

By default the command blocks until the sandbox reaches the stopped state.

destroy

Permanently destroy a sandbox and clean up all associated resources.

irons destroy <name|id> [flags]

Examples

irons destroy my-sandbox
irons destroy my-sandbox --force

ssh

Open an interactive SSH session in a sandbox, or run a remote command.

Any arguments after the sandbox identifier are forwarded to the remote host as the command to execute, mimicking native ssh behavior.

irons ssh <name|id> [command...] [flags]

Examples

irons ssh my-sandbox
irons ssh my-sandbox ls -la
irons ssh -t my-sandbox tmux
irons ssh my-sandbox -- ls -la
irons ssh my-sandbox --command

scp

Copy files to or from a sandbox using SCP. Prefix a path with the sandbox name (or VM ID) and a colon to denote a remote path.

irons scp <src> <dst> [flags]

Exactly one of src or dst must be a remote path in name:path or vm_id:path form.

Examples

# Upload a local file to the sandbox
irons scp ./local-file.txt my-sandbox:/remote/path/
 
# Download a file from the sandbox
irons scp my-sandbox:/remote/file.txt ./local-dest/
 
# Recursively copy a directory
irons scp -r ./my-dir my-sandbox:/remote/path/

forward

Forward a port from a sandbox to your local machine via SSH tunneling.

irons forward <name|id> [flags]

Examples

irons forward my-sandbox --remote-port 3000
irons forward my-sandbox --remote-port 5432 --local-port 5433
irons forward my-sandbox --remote-port 3000 --command

egress

Manage outbound network rules for the account.

egress list

List all current egress rules.

irons egress list

egress add

Add an egress rule to allow outbound traffic to a host or CIDR range.

irons egress add [flags]

Exactly one of --host or --cidr is required.

Examples

irons egress add --host crates.io
irons egress add --cidr 10.0.0.0/8 --name "internal network" --comment "Allow internal traffic"
irons egress add --host api.example.com --name "example api"

egress remove

Remove an egress rule by its ID.

irons egress remove <rule_id>

egress mode

Get or set the egress enforcement mode for the account.

irons egress mode [enforce|warn]

Called with no argument, prints the current mode. Pass enforce or warn to change it.

Examples

irons egress mode
irons egress mode enforce
irons egress mode warn

audit

Inspect the history of outbound network connection attempts.

audit egress

Print the egress audit log — every outbound connection attempt, whether it was allowed or denied, and the mode that was active at the time.

irons audit egress [flags]

Each line of output contains the following space-separated fields:

TIMESTAMP  VERDICT  VM_ID  PROTOCOL  HOST  (mode: MODE)

Example output

2026-02-19T16:41:54-07:00  ALLOW  vm_abc123  tcp    changelogs.ubuntu.com  (mode: warn)
2026-02-19T16:42:00-07:00  ALLOW  vm_abc123  tcp    example.com            (mode: warn)
2026-02-19T16:42:26-07:00  DENY   vm_abc123  tcp    example2.com           (mode: enforce)

Examples

# Show the last hour of egress events across all sandboxes
irons audit egress
 
# Filter to a specific sandbox
irons audit egress --vm my-sandbox
 
# Only show blocked connections
irons audit egress --vm my-sandbox --verdict blocked
 
# Tail new events as they arrive
irons audit egress --vm my-sandbox --follow
 
# Events in a specific time window
irons audit egress --since 2026-01-01T00:00:00Z --until 2026-01-02T00:00:00Z

Tip: Run irons audit egress --vm my-sandbox --follow while your egress mode is set to warn to observe which domains your agent is reaching before switching to enforce. This makes it easy to build a precise allowlist without trial and error.

secrets

Manage secrets for your account. Secrets are credentials (e.g. API tokens) that are securely stored and made available to sandboxes as environment variables via proxy values. The egress proxy scans all outbound HTTP headers for known proxy values and replaces them with real secrets. The secret value is never displayed by any subcommand.

Commands that accept <name|id> resolve the argument as a secret ID if it starts with sec_, otherwise as a name.

secrets list

List all secrets on the account.

irons secrets list

Displays a table with columns: NAME, ENV_VAR, HOSTS, PROXY_VALUE, CREATED.

The HOSTS column displays * for unrestricted, or a comma-separated list for scoped secrets.

Never displays the secret value.

secrets add

Add a new secret.

irons secrets add [flags]

If --secret is not provided, the CLI prompts for the secret value with echo disabled, then prompts for confirmation. If stdin is piped, reads the secret from stdin.

Examples

# Simple — inject everywhere, prompt for secret
irons secrets add --name github-main --env-var GITHUB_TOKEN
 
# With secret on command line
irons secrets add --name github-main --env-var GITHUB_TOKEN --secret ghp_abc123
 
# Scoped to specific hosts
irons secrets add --name github-main --env-var GITHUB_TOKEN --host api.github.com --host "*.github.com"
 
# Piped
echo "ghp_abc123" | irons secrets add --name github-main --env-var GITHUB_TOKEN

secrets show

Show details of a single secret.

irons secrets show <name|id>

Displays the secret’s metadata: name, env var, hosts, proxy value, comment, and timestamps. Never displays the secret value.

secrets update

Update a secret.

irons secrets update <name|id> [flags]

Examples

irons secrets update github-main --secret ghp_newtoken789
irons secrets update github-main  # prompts for new secret value
irons secrets update github-main --host api.github.com --host "*.github.com"

secrets remove

Remove a secret by name or ID.

irons secrets remove <name|id>

Examples

irons secrets remove github-main
irons secrets remove sec_m4xk9wp2

snapshots

Manage VM snapshots. Snapshots capture a VM’s overlay at a point in time with zero downtime. Restoring a snapshot creates a new VM — the original is untouched. To create a VM from a snapshot, use create --snapshot.

snapshots create

Create a snapshot of the specified VM. The snapshot is taken with zero downtime. The VM is not affected if the upload fails.

irons snapshots create <name|id> [flags]

By default the command returns immediately after the API accepts the request. Use --wait to poll until the snapshot reaches ready or failed. While waiting, the CLI displays the current snapshot status (pending, generating, uploading) as it progresses.

Snapshot statuses: pending → generating → uploading → ready (or failed, deleted)

Examples

irons snapshots create my-dev-env
irons snapshots create my-dev-env --label pre-refactor
irons snapshots create vm_k3mf9xvw2p --wait
irons snapshots create my-dev-env --json

snapshots list

List snapshots. Without a VM argument, lists all snapshots across VMs (includes a VM column). With a VM argument, lists only snapshots for that VM.

irons snapshots list [<name|id>]

Examples

irons snapshots list
irons snapshots list my-dev-env
irons snapshots list vm_k3mf9xvw2p --json

snapshots get

Show detailed information about a snapshot, including ID, label, source VM, status, base image (if any), and creation time.

irons snapshots get <snapshot-id>

Examples

irons snapshots get snap_x9f2km4p
irons snapshots get snap_x9f2km4p --json

snapshots delete

Delete a snapshot. This cannot be undone. Prompts for confirmation unless --force is passed.

irons snapshots delete <snapshot-id>

Examples

irons snapshots delete snap_x9f2km4p
irons snapshots delete snap_x9f2km4p --force

fork

Fork a VM by creating a snapshot and then spinning up a new VM from it. This is a convenience command that combines snapshots create --wait and create --snapshot into a single step. The snapshot is taken with zero downtime — the source VM is not affected.

irons fork <name|id> [flags]

The command waits for both the snapshot and the new VM to be ready before returning.

Examples

irons fork my-dev-env
irons fork my-dev-env --fork-name my-dev-env-copy
irons fork my-dev-env --fork-name copy --key ~/.ssh/id_rsa.pub

agents

Manage agent sessions. An agent session boots a VM, clones a repository, and starts an AI coding agent inside a tmux session.

agents new

Create a new agent session.

irons agents new [flags] [-- agent-args...]

Everything after -- is passed directly to the agent harness.

Examples

irons agents new --repo acme/api
irons agents new --repo acme/api --prompt "fix the failing auth tests"
irons agents new --repo acme/api --no-attach
irons agents new --repo acme/api -- --allowedTools "Bash,Read,Write"

agents attach

Attach to an existing agent session via SSH.

irons agents attach [name|id]

If the argument is omitted and exactly one agent is active, attaches to it automatically.

Examples

irons agents attach fix-auth
irons agents attach agt_x9k2mf4p
irons agents attach

agents list

List all active agent sessions.

irons agents list

agents destroy

Destroy an agent session and its backing VM.

irons agents destroy <name|id>

Examples

irons agents destroy fix-auth
irons agents destroy agt_x9k2mf4p

agents ssh

SSH into an agent’s VM. Works like the top-level ssh command but targets the agent by name or ID.

irons agents ssh <name|id> [command...] [flags]

Examples

irons agents ssh fix-auth
irons agents ssh fix-auth ls -la
irons agents ssh -t fix-auth tmux attach

public-keys

Manage SSH public keys registered to your account.

public-keys list

List all registered public keys.

irons public-keys list

public-keys add

Register a new public key.

irons public-keys add [flags]

Examples

irons public-keys add --name laptop --public-key "ssh-ed25519 AAAA..."
cat ~/.ssh/id_ed25519.pub | irons public-keys add --name laptop

public-keys remove

Remove a public key by name or ID.

irons public-keys remove <name|id>

Examples

irons public-keys remove laptop
irons public-keys remove pub_x9f2km4p