Quickstart

This guide takes you from a new account to a running machine and back. Each step shows the vy CLI, the TypeScript SDK, and the Python SDK; pick a tab once and every example on the page follows it. Port and SSH steps use the HTTP API so every client can follow them; the CLI also has vy ports and vy ssh.

1. Sign in

Open the VMYard console and sign in with one of the methods it offers, such as GitHub, Google, or a 6-digit code sent to your email. Your first sign-in creates your VMYard user. See Sign-in methods.

2. Install the tools

The CLI and SDKs are in private preview and are not published to npm or PyPI. Get access to the erphq/vmyard-sdk repository from your VMYard contact, then build from a checkout:

git clone https://github.com/erphq/vmyard-sdk.git
cd vmyard-sdk && npm ci && npm run build
npm install -g ./cli

The CLI needs Node.js 20 or newer, the TypeScript SDK Node.js 20 or newer, and the Python SDK Python 3.9 or newer. None of them has a default server: set VMYARD_API_URL to your API origin.

export VMYARD_API_URL=https://api.example.com   # your VMYard API origin

3. Get an API key

With the CLI, vy login opens the console, you approve the request, and the CLI stores a new API key. See CLI device login.

vy login
vy whoami

For the SDKs, create a key in the console under API keys with the Create and use preset and export it as VMYARD_API_KEY. The secret (vmy_…) is shown once. See API keys and presets.

4. Create a machine

Pick a plan from the catalog (vy plans), or let the client use the first one. --auto-stop 2 stops the machine two hours after it starts so a forgotten machine doesn't keep billing.

vy plans
vy new --plan small --name dev --auto-stop 2 --wait

Creating returns an operation; the CLI (with --wait) and the SDKs wait until it succeeds, which means VMYard observed the machine running. See Operations and idempotency.

5. Run a command

vy exec dev -- uname -a
vy exec dev -c 'cd /work && echo hello > hello.txt && ls -l'

The CLI streams output as it arrives and exits with the command's exit code. See Running commands.

6. Open a port

Start a web server as a background command, then expose its port. Private ports (the default) need a short-lived token.

await machine.commands.start("python3 -m http.server 8080");

MACHINE_ID=$(vy get dev --json | jq -r .id)   # or machine.data.id in the SDKs

curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ports" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"port": 8080}'

curl -X POST "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ports/8080/token" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"ttl_seconds": 900}'

Exposing a port is an operation: follow the returned operation_url until it succeeds. Open url_with_token from the token response in a browser. The example assumes the image has python3; use any server your image provides. See Ports and private URLs.

7. Connect over SSH

Install your public key; VMYard allocates an SSH gateway port and reports how to connect in the machine's ssh field.

curl -X PUT "$VMYARD_API_URL/v1/machines/$MACHINE_ID/ssh-key" \
  -H "Authorization: Bearer $VMYARD_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d "{\"public_key\": \"$(cat ~/.ssh/id_ed25519.pub)\"}"

# After the operation succeeds:
vy get dev --json | jq .ssh      # {"host": "...", "port": 2201, "user": "vmyard"}
ssh -p 2201 vmyard@<host>

See SSH.

8. Stop and start

Stopping ends metering. Files in /work are kept, and starting brings the same machine back.

vy stop dev --wait
vy start dev --wait

9. Delete the machine

vy rm dev --wait

Deleting is permanent. The delete operation succeeds once VMYard confirms the machine is gone from its host.

Next steps

• Check what you spent with vy usage and read Usage, billing, and limits.
• Get notified when machines become ready or fail with webhooks.
• Browse the CLI reference and the API reference.