AgentVM CLI

@wundercorp/agentvm manages AgentVM cloud servers and provides access to hyperscalars for virtual machines that agents run on.

Install

npm i -g @wundercorp/agentvm

Installing @wundercorp/agentvm also installs @stripe/link-cli, making the Stripe Link CLI and its MPP payment support available alongside AgentVM.

Equivalent commands:

agentvm help
avm help

Installed builds use commands directly, without npm argument forwarding:

avm login
avm new
avm launch

Machine-payment receipts

An MPP purchase response contains machine and session credentials, so save it with mode 0600. AgentVM can print a safe operational summary without exposing the bearer access token or MPP Session renewal token:

umask 077
tempo request \
  --max-spend 0.50 \
  -X POST \
  --json "$SESSION_REQUEST_JSON" \
  -o ./agentvm-mpp-response.json \
  'https://mpp.agentvm.sh/compute/sessions/hetzner-shell' && \
chmod 600 ./agentvm-mpp-response.json && \
agentvm mpp receipt ./agentvm-mpp-response.json

The summary includes state, capacity, SSH, endpoint, expiration, the payment boundary, and the private guest-dashboard URL. The URL supports a read-only accountless view and an explicit sign-in flow to add the machine and its MPP history to a dashboard. Claiming does not move the machine onto dashboard prepaid billing or increase its runtime/spend limits.

When working from this source repository, npm run dev:cli -- login uses npm's -- separator. To install the local build and test the production command shape, run npm run dev:cli:install once, then use avm login directly. The development installer removes broken or AgentVM-owned command links left by older installations, migrates retired AgentVM packages, verifies both aliases.

Sign in

avm login

Choose Google, Amazon, or Email. The CLI requests a one-time authorization grant, opens agentvm.sh/cli/login, and waits for approval. It then stores a revocable AgentVM API key in ~/.config/agentvm/config.json with mode 0600.

For a terminal that cannot open the authorization page automatically:

avm login --no-open

For automation, supply an existing key with avm login avm_... or AGENTVM_API_KEY.

Billing readiness

avm billing
avm subscribe

The compatibility subscribe command opens managed-usage payment setup. A payment method and enough prepaid balance for the VM's maximum estimate are required before launch.

Configure and launch a VM

The shortest workflow is:

avm new
avm launch
avm open

avm new reads the live catalog, defaults to Hetzner, prefers Ubuntu 22.04 LTS for server workloads, and saves a local draft without provisioning anything.

avm new --region fsn1 --plan <plan-id> --server --max-hours 2 --name development-server
avm launch

Use the same natural-language planner as the web application, then review and launch the saved draft:

avm plan "Create a small Ubuntu server in Falkenstein for two hours" --save
avm config get
avm launch

Direct creation remains available:

avm instance create \
  --provider hetzner \
  --region fsn1 \
  --plan <plan-id> \
  --image <image-id> \
  --image-architecture <architecture> \
  --server \
  --max-hours 2 \
  --name api-worker

The CLI generates a selected default key automatically unless --ssh-key points to an existing key. Key selection uses --ssh-key, then AGENTVM_SSH_KEY_PATH, then agentvm config set default-ssh-key <path>, and finally the ~/.ssh/agentvm_ed25519 fallback. The fallback filename is therefore not assumed by later commands. Creation output reports whether the key was generated or reused, the public IP, the SSH command, the HTTPS endpoint, and the one-time machine access token. The private-key path is remembered per VM so a later avm instance ssh current uses the same key without another flag.

When a provider publishes the same image identifier for more than one architecture, pass --image-architecture x86, --image-architecture arm, or the exact architecture value shown by avm plans --json. avm new stores the selected architecture so avm launch submits the same catalog pair.

agentvm config set default-ssh-key ~/.ssh/company_vm_ed25519

Optional GUI with RealVNC

AgentVM does not provision managed desktop VMs. Create a server first, then print the guided RealVNC Virtual Mode setup for that machine:

avm instance gui current

The guide keeps VNC behind an SSH tunnel instead of opening a public VNC port. RealVNC Virtual Mode requires an appropriate RealVNC subscription.

Catalog and inventory

avm providers
avm regions --provider hetzner
avm plans --provider hetzner --region fsn1
avm instances
avm instance info current --refresh

Catalog output uses AgentVM retail prices.

Connect to a VM

Open the machine in the dashboard:

avm open current

Request the same short-lived native OS-console session used by the web application:

avm instance console current

Connect over SSH or execute a remote command:

avm instance ssh current
avm instance ssh current uname -a

Telemetry and usage

avm instance metrics current --range 24h
avm instance metrics current --range 7d
avm instance usage current --refresh

Supported metric ranges are 1h, 6h, 24h, 7d, and 30d.

HTTPS agent access

New VMs start in private mode. Manage the authenticated HTTPS gateway with:

avm instance access current private
avm instance access current custom --origin https://example.com --origin https://app.example.com
avm instance access current custom --include-wundercorp --origin https://example.com
avm instance access current public

Custom access accepts exact HTTPS origins only. Paths, query strings, credentials, localhost origins, and more than 50 origins are rejected.

The VM access token returned at creation is stored in the mode-0600 CLI configuration. Show or rotate it with:

avm instance token current
avm instance token current --rotate

Send the token as Authorization: Bearer TOKEN or x-agentvm-access-token when calling the VM endpoint. Tokens are never accepted in URL query parameters. The create response includes an authenticated curl example for /__agentvm/connection, which verifies HTTPS reachability and the token before an agent service is called.

Power and lifecycle

avm instance poweroff current
avm instance poweron current
avm instance reboot current
avm instance destroy current --yes

Power actions wait for the settled provider state unless --no-wait is supplied. Powering off can leave storage or allocated capacity billable. Destroying releases the provider resource, finalizes remaining usage, and removes the locally stored machine access token and per-machine SSH key-path reference. The key file itself is preserved so other machines using it keep working.

JSON and automation

avm plans --provider hetzner --region fsn1 --json
avm instances --json
avm instance metrics current --range 1h --json

License and distribution

Apache-2.0.