# VMYard documentation

> VMYard runs isolated Linux machines for agents and developers. You create a machine from a plan, image, and region; run commands in it with streamed output; move files in and out of /work; expose ports as HTTPS URLs; reach it over SSH; and stop, start, or delete it. Every change is an idempotent operation you can follow to its observed result. Use the vy CLI, the TypeScript or Python SDK, or the HTTP API.

- All links point to Markdown versions of the pages; drop the `.md` suffix for HTML.
- API requests need `VMYARD_API_URL` (no default) and an API key sent as `Authorization: Bearer vmy_…`.
- VMYard does not wake machines on incoming requests; sleep is a stop and waking is a start.

## Get started

- [VMYard documentation](/docs/index.md): Isolated Linux machines you create, run commands in, and reach over HTTPS and SSH, from the CLI, the SDKs, or the HTTP API.
- [Quickstart](/docs/quickstart.md): Sign in, get an API key, and create, use, reach, stop, and delete your first machine with the CLI, TypeScript, or Python.

## Concepts

- [Machines](/docs/concepts/machines.md): What a VMYard machine is, how it is identified, what it is made of, and who may change it.
- [Operations and idempotency](/docs/concepts/operations.md): How VMYard accepts a change, carries it out, reports the truth about the result, and makes retries safe.
- [Lifecycle states](/docs/concepts/lifecycle.md): Desired and observed machine states, the actions that move between them, and how to read a machine that is in between.
- [Auto-stop](/docs/concepts/auto-stop.md): Stop machines automatically a fixed time after they start, so forgotten machines don't keep billing.
- [Idle sleep](/docs/concepts/idle-sleep.md): Put a running machine to sleep once it has done nothing for a while, how VMYard decides a machine is idle, and how idle sleep differs from auto-stop.
- [Sleep and wake](/docs/concepts/sleep-and-wake.md): What happens to a machine when it stops and starts, how idle sleep puts it to sleep, how long stops move down the snapshot tiers, and how to wake it.
- [Regions, plans, and images](/docs/concepts/catalog.md): The versioned catalog a machine is created from, how to read it, and how sizes are priced.

## Guides

- [API keys and presets](/docs/guides/api-keys.md): Create organization API keys, choose a preset that limits what each key can do, and rotate or revoke keys.
- [Sign-in methods](/docs/guides/sign-in.md): Sign in to the console with GitHub, Google, or an emailed code, and link or remove sign-in methods.
- [CLI device login](/docs/guides/cli-login.md): Sign the vy CLI in through the browser with the device authorization grant, or give it a key on stdin.
- [Running commands](/docs/guides/commands.md): Run a command in a machine, wait for its result or stream its output as it arrives, and handle exit codes, timeouts, and retries.
- [Background commands](/docs/guides/background-commands.md): Start long-running commands that outlive the request, page through their logs, and kill them.
- [Command history](/docs/guides/command-history.md): Search a machine's past commands, check how each one ended, and page through its stored stdout and stderr.
- [Web terminal](/docs/guides/web-terminal.md): Open an interactive login shell in a running machine from the console or any WebSocket client, and handle its messages, limits, and close reasons.
- [Desktop](/docs/guides/desktop.md): See and use a running machine's graphical desktop over VNC in the browser, with its security model, latency expectations, and close reasons.
- [Coding agents](/docs/guides/agents.md): Run Claude Code, Codex, or Pi inside a machine, follow what it does, steer or interrupt it, and pick up a conversation later.
- [Files](/docs/guides/files.md): Browse a machine's /work as a live tree, and write, read, upload, and download files up to 32 MiB.
- [Machine metrics](/docs/guides/machine-metrics.md): CPU, memory, disk, disk I/O, and network use for each machine, with one-minute history, live samples, and disk warnings.
- [Ports and private URLs](/docs/guides/ports.md): Expose a machine's ports as HTTPS URLs, keep them private with short-lived tokens, or make them public.
- [SSH](/docs/guides/ssh.md): Install your public key on a machine and connect through VMYard's SSH gateway.
- [Internet access and IPv6](/docs/guides/networking.md): Choose whether a machine can reach the internet, change it later, read its public IPv6 address, and know the limits and the operator's kill switch.
- [Setup scripts](/docs/guides/setup-scripts.md): Run a shell script once, right after a new machine first starts, and check whether it worked.
- [Environments](/docs/guides/environments.md): Store environment variables and secret files once, encrypted, and have VMYard install them in machines, with immutable versions and controlled upgrades.
- [Snapshots and tiers](/docs/guides/snapshots.md): Push a stopped machine to the snapshot store as a warm or cold snapshot, follow it to ready, list and delete snapshots one at a time or in bulk, and how long stops move down the tiers.
- [Automatic snapshots](/docs/guides/automatic-snapshots.md): How VMYard captures running KVM machines on an interval, how many automatic snapshots it keeps, and how to see and delete them.
- [Templates](/docs/guides/templates.md): Save a stopped machine as a named template and create machines from it with the same plan, image, region, and machine name, each with its own identity.
- [Fork and restore](/docs/guides/fork-and-restore.md): Copy a running machine at one instant, or restore one of a machine's snapshots, as a new machine with its own ID and identity.
- [Webhooks](/docs/guides/webhooks.md): Receive signed HTTPS events when machine lifecycle operations finish, verify their signatures, and handle retries.
- [Email alerts](/docs/guides/email-alerts.md): Choose which problems VMYard emails you about in each organization, and how the unsubscribe link in every alert works.
- [Usage, billing, and limits](/docs/guides/billing.md): How machine time is metered and paid for, what the trial and plans include, the limits that apply, and how to read usage.
- [Machine sizes and prices](/docs/guides/sizes-and-prices.md): The small, default, large, and xlarge sizes, their resources and hourly prices, how to read them from the plan catalog, and which sizes a trial can use.
- [Cancel a plan or end the trial](/docs/guides/plans-and-trial.md): Cancel a plan at the end of its period or keep it again, and end the free trial early, from the console or the API.
- [Automatic refill](/docs/guides/automatic-refill.md): Buy credit packs automatically when the balance runs low, with a monthly cap, and what happens when a charge fails.
- [Errors](/docs/guides/errors.md): The problem details format, every error code the API returns, and what to do about each one.

## SDKs and CLI

- [TypeScript SDK](/docs/sdk/typescript.md): Reference for @vmyard/sdk, the TypeScript client for Node.js 20+ with no runtime dependencies.
- [Python SDK](/docs/sdk/python.md): Reference for vmyard-sdk, the Python 3.9+ client built on the standard library alone.
- [CLI reference](/docs/cli.md): The common vy commands, their options, how vy finds your key and server, and its exit codes.

## API reference

- [API reference](/docs/api.md): Every route of the VMYard Product API: authentication, conventions, and endpoint groups.
- [Machines API](/docs/api/machines.md): Create, list, read, change, start, stop, restart, and delete machines. Every lifecycle change is an asynchronous operation.
- [Operations API](/docs/api/operations.md): Read an operation's status and result, or follow its persisted events as server-sent events.
- [Machine metrics API](/docs/api/machine-metrics.md): Read a machine's CPU, memory, disk, I/O, and network history at one-minute resolution, or the host's live samples.
- [Exec API](/docs/api/exec.md): Run a foreground command inside a machine, optionally streaming its output as NDJSON frames.
- [Background commands API](/docs/api/commands.md): Start detached commands, read their status and log, and kill them.
- [Terminal API](/docs/api/terminal.md): Open an interactive login shell in a running machine over a WebSocket. Browsers first mint a single-use ticket.
- [Desktop API](/docs/api/desktop.md): View a running machine's graphical desktop, or only its web browser, over a WebSocket carrying VNC. Browsers first mint a single-use ticket.
- [Agents API](/docs/api/agents.md): Run a coding agent (Claude Code, Codex, or Pi) inside a running machine: prompt it, follow its events, steer or interrupt a running turn, and resume conversations.
- [Command history API](/docs/api/command-history.md): Search a machine's past commands, read one entry, and page through its stored stdout and stderr.
- [Snapshots and templates API](/docs/api/snapshots.md): Push a stopped machine, save it as a named template, and copy a machine with fork or restore.
- [Files API](/docs/api/files.md): Write and read files inside a machine's /work directory.
- [File browser API](/docs/api/file-browser.md): List a running machine's folders under /work, /root, or /home as a live tree, and download a folder as a .tar.gz archive.
- [Ports and SSH API](/docs/api/ports-and-ssh.md): Expose guest ports as HTTPS URLs, issue access tokens for private ports, and install an SSH key.
- [Environments API](/docs/api/environments.md): Named, versioned sets of environment variables and secret files that VMYard applies to machines.
- [Catalog API](/docs/api/catalog.md): The plans, images, and regions a machine is created from, each selected by ID and exact version.
- [Billing and usage API](/docs/api/billing.md): Balances, limits, metered usage, invoice preview, and billing management.
- [Webhooks API](/docs/api/webhooks.md): Register HTTPS endpoints for signed lifecycle events and inspect their deliveries.
- [Email alerts API](/docs/api/notifications.md): Read and change your email alert preferences, and the unsubscribe link every alert email carries.
- [Organizations API](/docs/api/organizations.md): List, read, create, and rename the organizations the caller belongs to.
- [Waitlist and access API](/docs/api/waitlist.md): Invite-only access: the form service's sign-up hook, and for the people who run the service, the waitlist and access grants. Operator routes need the operator token.
- [Members and invitations API](/docs/api/members.md): List an organization's members, change roles, remove members, invite by email, accept invitations, transfer ownership, delete an organization, and choose the active organization. These routes need a browser session.
- [Capacity (operators) API](/docs/api/capacity.md): For the people who run the service: the capacity loop's decisions, the budget guard, and the server purchases waiting for approval. These routes need the operator token.
- [API keys API](/docs/api/api-keys.md): Create, list, rotate, and revoke organization API keys. These routes need a browser session.
- [Identity API](/docs/api/identity.md): The signed-in user or API key caller and their memberships.
- [Sign-in API](/docs/api/sign-in.md): Browser sign-in with a configured provider, and sign-out.
- [Email sign-in API](/docs/api/email-sign-in.md): Sign in with an emailed 6-digit code or magic link.
- [Sign-in methods API](/docs/api/sign-in-methods.md): Link another sign-in method to the signed-in user, or remove one.
- [Operator API](/docs/api/operator.md): For the people who run the service: suspend an organization or lift a suspension, and review the abuse guard's flags. These routes need the operator token.
- [Device authorization API](/docs/api/device-authorization.md): The RFC 8628 device grant that vy login uses to receive an API key.
- [Schemas](/docs/api/schemas.md): Every request and response body, with field types and constraints.

## Resources

- [Status page](/docs/status.md): Where to check whether VMYard is up, what each state means, recent check history, and the machine-readable status JSON.
- [FAQ](/docs/faq.md): Short answers to common questions about machines, billing, access, and what VMYard does not do.
- [Changelog](/docs/changelog.md): Notable changes to the VMYard API, CLI, SDKs, and console.

## Optional

- [Full documentation](/llms-full.txt): every page above in one Markdown file.