# Origin Cloud
> Virtual machines, block storage and private networks in European data centers, with prices you can read before you register.
Virtual machines, block storage and private networks in European data centers, with prices you can read before you register.
These documents describe the template. Public documentation contains no account or organization data. Authenticated tools apply the same organization permissions as the app.
## Public pages
- [Origin Cloud docs](https://origin.its-live.dev/docs): The seven Origin Cloud guides, from Platform to Pricing.
- [Overview](https://origin.its-live.dev/index.md): Services, published rates and how to register, from the home page.
- [Privacy policy](https://origin.its-live.dev/privacy.md): The template's privacy text and replacement notice.
- [Terms of service](https://origin.its-live.dev/terms.md): The template's terms and replacement notice.
- [Full documentation](https://origin.its-live.dev/llms-full.txt): Public pages, demo content and the agent connection guide.
## Origin Cloud docs
The documentation is available in English only. UI language does not translate these documents.
- [Create an image](https://origin.its-live.dev/docs/compute/images/create.md): Turn an instance's root disk into your own image - clear its machine-id, snapshot and protect the volume, create the image - and update or delete it later.
- [Image families](https://origin.its-live.dev/docs/compute/images/image-families.md): How an image family resolves to its current platform-provided image, what its metadata tells you about upstream support, and what happens when one is withdrawn.
- [Images](https://origin.its-live.dev/docs/compute/images.md): An image is what an instance boots from. Learn the difference between platform-provided and your own images, and what each image field means.
- [What is Origin Cloud Compute?](https://origin.its-live.dev/docs/compute.md): Compute runs virtual machines on Origin Cloud. Learn how instances, images, instance types and key pairs fit together and how to reach them.
- [Attach and detach volumes](https://origin.its-live.dev/docs/compute/instance-storage/attach-detach.md): Attach an available volume to a running or stopped instance, choose its guest device name, and detach it again to use elsewhere.
- [Instance storage](https://origin.its-live.dev/docs/compute/instance-storage.md): How an instance's durable root disk is created and sized at launch, and how extra volumes attach to a running or stopped instance.
- [Change an instance's type](https://origin.its-live.dev/docs/compute/instances/change-type.md): Change a stopped instance to a different instance type so it starts again with more or fewer vCPUs and memory, keeping its identity and volumes.
- [Guest environment](https://origin.its-live.dev/docs/compute/instances/guest-environment.md): What the platform sets up inside an instance at first boot - the login user and SSH key, time synchronization - and why each image needs its own machine-id.
- [Instance health checks](https://origin.its-live.dev/docs/compute/instances/health-checks.md): What each instance health check observes, how results combine into availability, and how the category tells you whether a problem is yours to fix.
- [When the machine under an instance fails](https://origin.its-live.dev/docs/compute/instances/host-failure.md): What happens to an instance when its physical machine fails or is taken out of service, what survives, and why restarting it is your decision.
- [Instances](https://origin.its-live.dev/docs/compute/instances.md): An instance is a virtual machine on Origin Cloud. Find its lifecycle, types, health checks, failure behavior and the tasks to launch and manage one.
- [Instance types](https://origin.its-live.dev/docs/compute/instances/instance-types.md): How instance types set an instance's vCPU and memory, how type names are built, and how to read the live catalog and its available flag.
- [Launch an instance](https://origin.its-live.dev/docs/compute/instances/launch.md): Launch a virtual machine with the CLI or the API - choose an image, instance type, key pair, network and root disk - and log in over SSH.
- [Instance lifecycle](https://origin.its-live.dev/docs/compute/instances/lifecycle.md): The eight statuses an instance moves through from launch to termination, what changes each one, what you're billed for, and what FAILED means.
- [Stop and start an instance](https://origin.its-live.dev/docs/compute/instances/stop-start.md): Stop an instance to release its vCPU and memory while keeping its disks and addresses, and start it again later, possibly on another machine.
- [Terminate an instance](https://origin.its-live.dev/docs/compute/instances/terminate.md): Terminate an instance permanently, and learn which of its volumes, network interfaces and addresses are deleted and which stay with you.
- [Create a key pair](https://origin.its-live.dev/docs/compute/key-pairs/create.md): Import the public half of an SSH key you already have, or have the platform generate a key pair and save its private key from the one response that carries it.
- [Key pairs](https://origin.its-live.dev/docs/compute/key-pairs.md): A key pair is the SSH key you log in to instances with. Learn how the platform uses it at launch and what happens when you delete one.
- [origin compute commands](https://origin.its-live.dev/docs/compute/reference/cli.md): Every origin compute command with its flags: instances, instance types, images, image families, key pairs and volume attachments.
- [Compute reference](https://origin.its-live.dev/docs/compute/reference.md): Complete reference material for Compute - every origin compute command and its options, and every reason an instance can report in statusReason.
- [Status reasons](https://origin.its-live.dev/docs/compute/reference/status-reasons.md): Every text an instance can report in statusReason when it is FAILED or was stopped by the platform, with what each means and what to do next.
- [Troubleshoot Compute](https://origin.its-live.dev/docs/compute/troubleshooting.md): Fix common Compute problems - failed instances, refused launches and starts, impaired or unknown health, unsynchronized clocks, SSH failures and broken pod networking.
- [Access model](https://origin.its-live.dev/docs/iam/access-model.md): How principals, roles, role assignments and permissions work together, how org-wide and project scopes differ, and how a request is authorized.
- [Assign and revoke roles](https://origin.its-live.dev/docs/iam/assign-roles.md): Grant a built-in role to a user or service account org-wide or for one project, and revoke it again at exactly the scope it was granted.
- [Audit log](https://origin.its-live.dev/docs/iam/audit-log.md): Which access changes the audit log records, the fields of each entry, who can read it, and how to page through it with the GraphQL API.
- [Check access](https://origin.its-live.dev/docs/iam/check-access.md): Look up who you are and which roles you hold, list the platform's permissions, and check whether a principal has a permission on a resource.
- [What is Origin Cloud IAM?](https://origin.its-live.dev/docs/iam.md): IAM controls who can do what in your Origin Cloud organization. Learn how principals, roles, role assignments and permissions fit together.
- [Manage organization members](https://origin.its-live.dev/docs/iam/manage-members.md): Invite people to your organization by email, list members and pending invites, remove a member's access, and cancel an invite before it applies.
- [origin iam commands](https://origin.its-live.dev/docs/iam/reference/cli.md): Every origin iam command with its flags: members, invites, service accounts, role assignments and permission checks.
- [IAM reference](https://origin.its-live.dev/docs/iam/reference.md): Where to find every origin iam command and built-in role, and a one-line summary of each IAM query and mutation in the GraphQL API.
- [Built-in roles](https://origin.its-live.dev/docs/iam/roles.md): Every built-in IAM role with its ID, URN, what it's for and the exact permissions it grants, including the billing roles that Owner doesn't include.
- [Use service accounts](https://origin.its-live.dev/docs/iam/service-accounts.md): Create a service account for CI and scripts, exchange its client ID and secret for an access token, grant it roles, and revoke it.
- [Origin Cloud Docs](https://origin.its-live.dev/docs.md): User documentation for Origin Cloud, for anyone calling the GraphQL API or the origin CLI.
- [DNS](https://origin.its-live.dev/docs/network/dns.md): Every instance gets an internal hostname that its VPC resolves, and DNS policies decide where other queries go. Learn how names are resolved in a VPC.
- [Manage DNS policies](https://origin.its-live.dev/docs/network/dns/manage-policies.md): Create DNS policies, change their upstream servers and relaying, attach a policy to a VPC, change a project's default policy, and delete a policy.
- [What is Origin Cloud Network?](https://origin.its-live.dev/docs/network.md): Network gives your instances private VPCs, subnets and network interfaces, controlled internet access, traffic filtering and DNS. Learn how the parts fit.
- [Floating IPs](https://origin.its-live.dev/docs/network/internet-access/floating-ips.md): A Floating IP is a public IPv4 address you hold and associate with a network interface. Learn how to use it, when it's released, and how it behaves inside its VPC.
- [Internet access](https://origin.its-live.dev/docs/network/internet-access.md): How traffic gets between your instances and the internet - Internet Gateways, route tables, NAT gateways and Floating IPs, and the two paths they form.
- [Attach and detach an Internet Gateway](https://origin.its-live.dev/docs/network/internet-access/internet-gateways.md): Attach an Internet Gateway to connect a whole VPC to the internet, check it, and detach it again to make the VPC private.
- [Give a private subnet internet access with a NAT gateway](https://origin.its-live.dev/docs/network/internet-access/nat-gateways.md): Create a NAT gateway so instances without a Floating IP can reach the internet over IPv4, route a private subnet through it, and delete it again.
- [Route tables](https://origin.its-live.dev/docs/network/internet-access/route-tables.md): How route tables decide where a subnet's internet traffic goes, how the main table differs from tables you create, and how to change routes and associations.
- [origin network commands](https://origin.its-live.dev/docs/network/reference/cli.md): Every origin network command with its flags: VPCs, subnets, gateways, route tables, Floating IPs, ACLs, security groups and DNS policies.
- [Network reference](https://origin.its-live.dev/docs/network/reference.md): Where to find every origin network CLI command and every GraphQL query and mutation in the network namespace of the API.
- [Traffic control](https://origin.its-live.dev/docs/network/traffic-control.md): Security groups filter each instance's traffic and network ACLs filter traffic crossing a subnet's boundary. Learn where each one applies.
- [Network ACLs](https://origin.its-live.dev/docs/network/traffic-control/network-acls.md): Network ACLs are stateless, ordered rule lists for a subnet. Learn how rules are evaluated, which traffic they apply to, and how to create and assign one.
- [Rule sets are replaced as a whole](https://origin.its-live.dev/docs/network/traffic-control/replace-rule-sets.md): ACL rules, security group rules and DNS upstream servers are replaced as a whole. Learn how each command makes you state the full new state, including an empty one.
- [Security groups](https://origin.its-live.dev/docs/network/traffic-control/security-groups.md): Security groups are stateful firewalls on each network interface. Learn how rules and group references work, what the default group allows, and how to change rules.
- [Troubleshoot Network](https://origin.its-live.dev/docs/network/troubleshooting.md): Fixes for common Network problems - no internet access, IPv6 errors, refused VPC, subnet and NAT gateway requests, and connections that hang.
- [VPC and subnet addressing](https://origin.its-live.dev/docs/network/vpcs/addressing.md): How a VPC's IPv4 and IPv6 ranges are chosen, how large its subnets are, which addresses are reserved, and what happens when address space runs out.
- [Create a VPC and subnets](https://origin.its-live.dev/docs/network/vpcs/create.md): Create a VPC with the CLI, add subnets to it, and choose whether instances launched into each subnet get a public IPv4 address automatically.
- [Default VPC](https://origin.its-live.dev/docs/network/vpcs/default-vpc.md): The platform creates a default VPC for a project the first time you launch an instance without a subnet. Learn what it contains and how auto-assigned public IPs work.
- [Delete a subnet or VPC](https://origin.its-live.dev/docs/network/vpcs/delete.md): Delete a subnet or a whole VPC, clear what blocks the deletion, and learn what is removed with it and what happens to its address ranges.
- [VPCs and subnets](https://origin.its-live.dev/docs/network/vpcs.md): A VPC is an isolated network with its own address space, divided into subnets. Learn what a VPC comes with and how instances connect to it.
- [Network interfaces](https://origin.its-live.dev/docs/network/vpcs/network-interfaces.md): A network interface holds an instance's private IPv4 and IPv6 addresses in a subnet and carries its security groups. Learn how interfaces are created and removed.
- [What is Origin Cloud Observability?](https://origin.its-live.dev/docs/observability.md): Observability lets you query CPU, network, and disk metrics that the platform collects for your instances, volumes, and network interfaces.
- [Query metrics](https://origin.its-live.dev/docs/observability/query-metrics.md): Query the CPU, network, or volume metrics of one resource over a time window with the GraphQL API, and choose the period and statistic.
- [Observability reference](https://origin.its-live.dev/docs/observability/reference.md): Reference pages for Observability, listing every metric with its unit and meaning, the metrics query arguments, limits, and errors.
- [Metrics reference](https://origin.its-live.dev/docs/observability/reference/metrics.md): Every metric Observability provides, with resource type, unit, and meaning, plus the metrics query arguments, response fields, limits, and errors.
- [Use the GraphQL API](https://origin.its-live.dev/docs/platform/access/api.md): Call the Origin Cloud GraphQL API with a bearer token, find operations by namespace, read resource URNs, and handle typed enums and errors.
- [Use the CLI](https://origin.its-live.dev/docs/platform/access/cli.md): Install the origin CLI, log in through your browser or with a device code, manage your session and profile, and read the CLI's JSON output and exit codes.
- [Ways to access Origin Cloud](https://origin.its-live.dev/docs/platform/access.md): Reach Origin Cloud through the console, the origin CLI or the GraphQL API. All three act as a signed-in user or service account with the same permissions.
- [Billing access](https://origin.its-live.dev/docs/platform/billing/billing-access.md): Billing is kept apart from the Owner role. Learn which billing roles reach a billing account, who holds one from the start, and what an Owner can do without one.
- [Billing](https://origin.its-live.dev/docs/platform/billing.md): Billing accounts hold your billing details and payment method, and every project is charged to one. Learn how billing accounts, payment methods, invoices and spend limits fit together.
- [Add a payment method](https://origin.its-live.dev/docs/platform/billing/payment-method.md): Add a card to a billing account on the payment provider's hosted page, confirm it, and check paymentMethodStatus so the account's projects can create billable resources.
- [Get started with Origin Cloud](https://origin.its-live.dev/docs/platform/getting-started.md): Register an organization, add a payment method, launch your first instance with the origin CLI, log in to it over SSH, and clean up afterwards.
- [What is Origin Cloud?](https://origin.its-live.dev/docs/platform.md): Origin Cloud runs virtual machines, block storage and private networks in European data centers. Learn how organizations, projects and resources fit together.
- [Create an organization](https://origin.its-live.dev/docs/platform/organizations/create.md): Register an organization with its billing details in one step, or create it from its name alone and add the billing details to its default billing account later.
- [Organizations and projects](https://origin.its-live.dev/docs/platform/organizations.md): An organization is your company's Origin Cloud account and holds your projects, members and billing accounts. Learn how they relate and what you can manage.
- [Manage projects](https://origin.its-live.dev/docs/platform/organizations/projects.md): Create, list, rename and delete the projects in your organization, find a project's URN, change the billing account a project is charged to, and delete an organization.
- [Organization review status](https://origin.its-live.dev/docs/platform/organizations/review-status.md): A new organization is activated at once or reviewed first, depending on platform capacity. Learn what each status allows, which emails you get, and how to check it.
- [Platform CLI commands](https://origin.its-live.dev/docs/platform/reference/cli.md): Every origin id, origin admin and origin config command with its flags: log in, manage organizations and projects, and set CLI profile values.
- [Error codes](https://origin.its-live.dev/docs/platform/reference/errors.md): Every error code the Origin Cloud API returns, with what it means, what commonly causes it, and what to do. Branch on the code, never on the message.
- [Platform reference](https://origin.its-live.dev/docs/platform/reference.md): Look up the platform CLI commands, every error code the API returns with what to do about it, and the quotas and hard limits that apply to your organization.
- [Limits](https://origin.its-live.dev/docs/platform/reference/limits.md): The quotas on what your organization and its projects can hold, how to read current usage against them, how to set project budgets, and the platform's hard limits.
- [What is Origin Cloud Pricing?](https://origin.its-live.dev/docs/pricing.md): The public price list gives the current list price of every billable product, in euro, over HTTP without an account or token.
- [Read the price list](https://origin.its-live.dev/docs/pricing/read-price-list.md): Fetch the public price list with curl, revalidate it with a conditional request, and turn a price into an hourly or monthly cost.
- [Pricing reference](https://origin.its-live.dev/docs/pricing/reference.md): Reference pages for Pricing, covering the public price list endpoint, its response fields, product families, headers, and status codes.
- [Price list API](https://origin.its-live.dev/docs/pricing/reference/price-list-api.md): Reference for GET /v1/pricing, the public price list endpoint, with every response field, product family, header, and status code.
- [What is Origin Cloud Storage?](https://origin.its-live.dev/docs/storage.md): Storage gives your instances durable block volumes and point-in-time snapshots. Learn the parts, how they relate to images, and how to access them.
- [origin storage commands](https://origin.its-live.dev/docs/storage/reference/cli.md): Every origin storage command with its flags: volumes, storage classes, imports and snapshots.
- [Storage reference](https://origin.its-live.dev/docs/storage/reference.md): Look up every origin storage CLI command and every GraphQL query and mutation in the pvs namespace for volumes, snapshots, and storage classes.
- [Create and protect a snapshot](https://origin.its-live.dev/docs/storage/snapshots/create-and-protect.md): Take a crash-consistent snapshot of an available or attached volume, wait for it to complete, and protect it so it can be used as a clone source.
- [Delete a snapshot](https://origin.its-live.dev/docs/storage/snapshots/delete.md): Unprotect a snapshot if needed, delete it, and confirm that it reports DELETED so it no longer blocks deleting its volume.
- [Snapshots](https://origin.its-live.dev/docs/storage/snapshots.md): A snapshot is a point-in-time copy of a volume. Learn how snapshots connect volumes to new volumes and images, and find the snapshot tasks.
- [Snapshot states](https://origin.its-live.dev/docs/storage/snapshots/snapshot-states.md): The status and protection status values a snapshot reports, what FAILED protection means, and when a snapshot can be used as a clone source.
- [Troubleshoot storage](https://origin.its-live.dev/docs/storage/troubleshooting.md): Fix common volume and snapshot problems, from volumes in ERROR and failed resizes to refused deletes, failed imports, and refused requests.
- [Create a volume](https://origin.its-live.dev/docs/storage/volumes/create.md): Create an empty volume or a volume from a protected snapshot with the origin CLI or the GraphQL API, and check that it becomes AVAILABLE.
- [Delete a volume](https://origin.its-live.dev/docs/storage/volumes/delete.md): Delete a volume you no longer need, after detaching it and deleting its snapshots, and confirm that it reports DELETED and frees its quota.
- [Find the instance a volume is attached to](https://origin.its-live.dev/docs/storage/volumes/find-instance.md): Follow an INUSE volume's claimRef to its volume attachment and from there to the instance that holds it, with one CLI command or API query.
- [Import a disk image as a volume](https://origin.its-live.dev/docs/storage/volumes/import.md): Create a volume whose initial content is a disk image downloaded from an HTTP(S) URL, size it correctly, and check that the import succeeded.
- [Volumes](https://origin.its-live.dev/docs/storage/volumes.md): A volume is a durable block disk for your instances. Learn the key concepts and find the tasks for creating, resizing, and deleting volumes.
- [Resize a volume](https://origin.its-live.dev/docs/storage/volumes/resize.md): Grow a volume, including one attached to a running instance, then extend the partition and filesystem inside the guest to use the new space.
- [Storage classes](https://origin.its-live.dev/docs/storage/volumes/storage-classes.md): A storage class is a volume's performance tier. Learn which classes exist, which one you can select today, and how to read the catalog.
- [Volume states](https://origin.its-live.dev/docs/storage/volumes/volume-states.md): The status and modification status values a volume reports, how asynchronous operations and failures show up in them, and which states are billed.
## Agent connection
- [MCP endpoint](https://origin.its-live.dev/api/mcp): OAuth 2.1 authenticated MCP; start with tools/list to discover available tools.
- [OAuth protected resource](https://origin.its-live.dev/.well-known/oauth-protected-resource): Resource metadata for MCP authorization.
- [OAuth authorization server](https://origin.its-live.dev/.well-known/oauth-authorization-server): Authorization and token endpoints.
- [API reference](https://origin.its-live.dev/api/rpc/api-reference): Session-authenticated oRPC API documentation.
- [OpenAPI specification](https://origin.its-live.dev/api/rpc/api-reference/spec.json): Session-authenticated API schema.
- [Sitemap](https://origin.its-live.dev/sitemap.xml): Public URLs only.
Markdown pages support ?lang=en, ?lang=de and ?lang=fr. This index and the full document are in English.
# European cloud infrastructure. Independent by design.
Virtual machines, block storage and private networks in European data centers, with prices you can read before you register.
No card to register · New organizations are activated at once or reviewed first, depending on capacity
[Register](/signup) · [Pricing](/pricing) · [Docs](/docs)
## Five services. Provision them today.
Compute, Persistent Volume Storage, VPC, IAM and Observability are live. Cost Management is coming soon.
- [Compute](/services/compute): Virtual machines in the gp1 series, priced per hour at published rates.
- [Persistent Volume Storage](/services/storage): Durable block volumes on general-purpose SSD, with point-in-time snapshots.
- [VPC](/services/network): Isolated virtual networks: subnets, security groups, floating IPs and internet gateways.
- [IAM](/services/iam): Organization members, invitations, built-in roles, service accounts and an audit log.
- [Observability](/services/observability): Platform metrics for instances, volumes and network interfaces, queryable from the API.
- [Cost Management](/services/cost-management) (Coming soon): Usage and cost reports, spend limits and billing accounts. In the API today; the service is coming soon.
## No quotes. No sales calls. Plain APIs.
### Real pricing, no quotes
Every instance type and rate is in a public price list. No sales call is needed to find out what something costs.
### Refusals you can act on
When a request is refused, you get an error code such as INSUFFICIENT_CAPACITY and a correlation ID to quote when you ask for help.
### Open by design
A GraphQL API and a CLI with 117 commands cover every resource type, so Origin Cloud fits the tools you already use.
## Register online. No sales call, no procurement dance.
New organizations are activated at once or reviewed first, depending on platform capacity. If yours is reviewed, you get an email when it is approved.
# Privacy Policy
Last updated October 12, 2026
> Template text: This page ships with the template. Replace the bracketed placeholders, adapt it to what your app really does and have it reviewed before launch. It is not legal advice.
This policy explains what [Company name] collects when you use this app, why we collect it and the choices you have.
## Who is responsible
[Company name], [Postal address], is responsible for your personal data. Contact us at [privacy@your-domain.example].
## What we collect
Account data such as your name, email address, password hash, passkeys and two-factor settings. Content you create, such as organizations, todos and uploaded files. Technical data such as IP address, browser, sessions and security events in the audit log.
## Why we use it
To provide and secure the service, to send account emails such as verification, password reset and invitations, to prevent abuse and to meet legal obligations. We do not sell personal data.
## Cookies and local storage
Essential cookies keep you signed in and remember your language. Your theme and cookie choices are stored in your browser. Analytics or marketing tools, if enabled, load only after you consent in the cookie banner, and you can change that choice at any time.
## Service providers
We use processors that act on our instructions: Cloudflare for hosting, email and file storage, Neon for the database, and any payment or notification provider we enable.
## AI agents you connect
If you connect an AI agent over MCP, it can read your data and propose drafts only within the scopes you approve. You can revoke its access at any time under Integrations.
## How long we keep data
We keep account data while your account exists. When you delete your account in Settings, we delete your personal data within [30] days unless the law requires us to keep it. Security logs are kept for [90] days.
## Your rights
Depending on where you live, you can access, correct, export or delete your data, object to its processing and complain to a data protection authority. Write to [privacy@your-domain.example] and we will answer within one month.
## Changes to this policy
We post changes on this page and update the date at the top. For material changes we also notify you by email or in the app.
# Terms of Service
Last updated October 12, 2026
> Template text: This page ships with the template. Replace the bracketed placeholders, adapt it to what your app really does and have it reviewed before launch. It is not legal advice.
These terms govern your use of the app operated by [Company name]. By creating an account you agree to them.
## Your account
Give accurate information, keep your password and passkeys safe, and tell us at [privacy@your-domain.example] if you think your account was compromised. You are responsible for activity under your account.
## Acceptable use
Do not break the law, infringe the rights of others, upload malware, probe or overload the service, or try to access data you are not allowed to see.
## Your content
You keep ownership of what you upload. You give us the permission we need to store, process and display it in order to provide the service. Organization admins can manage content shared in their organization.
## Paid features
If paid plans are offered, prices, billing periods and cancellation terms are shown before you buy and become part of these terms.
## Availability and changes
We work to keep the service available but cannot guarantee it will be uninterrupted. We may change or discontinue features and will give notice of material changes.
## Ending your use
You can delete your account at any time in Settings. We may suspend or close accounts that break these terms.
## Liability
The service is provided as is. To the extent the law allows, [Company name] is not liable for indirect or consequential damages. Nothing in these terms limits liability that the law does not allow us to limit.
## Governing law
These terms are governed by the laws of [Country or state].
## Contact
Questions about these terms go to [privacy@your-domain.example].
# Public demo posts
## Hello from the edge
https://origin.its-live.dev/posts/hello-edge
Ada Lovelace, 2026-06-01
Why we built this template on Cloudflare Workers.
This is a demo post used to showcase dynamic OG images.
## End-to-end type-safe RPC
https://origin.its-live.dev/posts/type-safe-rpc
Alan Turing, 2026-06-10
oRPC ties the API and the client together.
Another demo post for the template.
# Public demo profiles
## Ada Lovelace
https://origin.its-live.dev/u/ada
Building on the edge.
## Alan Turing
https://origin.its-live.dev/u/alan
Type-safety enthusiast.
# Create an image
Turn an instance's root disk into your own image - clear its machine-id, snapshot and protect the volume, create the image - and update or delete it later.
Create your own image to launch more instances with the same software and configuration as one you’ve already set up. You snapshot the instance’s root disk, protect the snapshot, and create an image from it.
## Before you begin [#before-you-begin]
- An instance whose root disk holds what you want in the image.
- The `origin` CLI, signed in. See [CLI access](/docs/platform/access/cli).
## Prepare the instance [#prepare-the-instance]
1. Log in to the instance and clear its machine-id, so every instance launched from the image generates its own:
```sh
sudo truncate -s 0 /etc/machine-id
sudo rm -f /var/lib/dbus/machine-id
```
If you skip this, every instance from the image shares one machine-id, which breaks VXLAN networking between them. See [Guest environment](/docs/compute/instances/guest-environment).
1. Stop the instance, so the snapshot captures a cleanly shut-down file system. See [Stop and start an instance](/docs/compute/instances/stop-start).
## Snapshot the root disk [#snapshot-the-root-disk]
1. Find the root disk’s volume URN. In `volumeAttachments`, it’s the entry with `isRootDevice` set to `true`:
```sh
origin compute get-instance --instance-urn
```
1. Create a snapshot of that volume:
```sh
origin storage create-snapshot --volume-urn
```
1. Run `get-snapshot` until `status` reads `COMPLETED`. Note its `volumeSizeInGib`:
```sh
origin storage get-snapshot --snapshot-urn
```
1. Protect the snapshot. Only a protected snapshot can back an image:
```sh
origin storage protect-snapshot --snapshot-urn
```
1. Run `get-snapshot` until `protectionStatus` reads `PROTECTED`.
For more about snapshot states, see [Create and protect a snapshot](/docs/storage/snapshots/create-and-protect).
## Create the image [#create-the-image]
```sh
origin compute create-image \
--project-urn \
--root-device-snapshot-urn \
--root-device-size \
--description "Web server base"
```
- The snapshot must be in the project you create the image in. A snapshot of another project is refused as not found.
- `--root-device-size` must be at least the snapshot’s `volumeSizeInGib`. It defaults to 8 GiB, so set it when the volume was larger. Instances launched from the image get a root disk of at least this size.
- `--default-user` sets the account instances log in as. Omitted, it’s `cloud`. See [Guest environment](/docs/compute/instances/guest-environment).
- `--root-device-name` sets the guest device name of the root disk. It defaults to `vda`. Names run from `vda` to `vdz`, without `/dev/`, and `vdc` is reserved. Any other value is refused, naming the field.
Then check the result:
1. Verify the image. It reads `status: AVAILABLE`:
```sh
origin compute get-image --image-urn
```
1. Launch an instance from it to test it. See [Launch an instance](/docs/compute/instances/launch).
With the API, `createImage` takes the root device as one of a list of `blockDeviceSpecs`, each with a `deviceName`, `snapshotUrn` and `sizeInGib`. `rootDeviceName` must name one of them.
## What keeping an image costs [#what-keeping-an-image-costs]
An image keeps two billed resources alive for as long as you use it:
- **The snapshot behind it.** Completed snapshots are billed for the size of the volume they were taken from, and the snapshot must stay protected for the image’s whole life. Once you unprotect or delete it, launches from the image are refused, although the image still reads `AVAILABLE`.
- **The source volume.** A volume can’t be deleted while any of its snapshots exists, so the root disk you snapshotted stays billed too.
To remove everything, work in this order: delete the image, unprotect and delete the snapshot, then delete the volume. See [Pricing](/docs/pricing) for the rates.
## Update or delete an image [#update-or-delete-an-image]
The description is the only field you can change:
```sh
origin compute update-image \
--image-urn \
--description "Web server base, hardened"
```
To delete an image:
```sh
origin compute delete-image --image-urn
```
Deleting an image doesn’t affect instances already launched from it, because each has its own copy on its root disk. The snapshot behind the image isn’t deleted. Unprotect and delete it separately when you no longer need it. See [Delete a snapshot](/docs/storage/snapshots/delete).
You can update and delete only your own images, not platform-provided ones.
## Related [#related]
- [`create-image` reference](/docs/compute/reference/cli#create-image)
- [Images](/docs/compute/images)
- [Snapshots](/docs/storage/snapshots)
# Image families
How an image family resolves to its current platform-provided image, what its metadata tells you about upstream support, and what happens when one is withdrawn.
An image family is a stable name for a line of platform-provided images, such as `ubuntu-22-04-minimal`. A launch that names a family gets whichever image the platform has designated as current for it. A launch that names an image URN gets exactly that image until you change it.
Launch by family to pick up rebuilt images automatically. Launch by image URN to pin the image you tested against.
## Launching by family [#launching-by-family]
The `launchInstance` mutation accepts `imageFamily` in place of `imageUrn`. Set exactly one of the two. The `origin compute launch-instance` command has no family option and takes `--image-urn` only. To find a family’s current image for the CLI, query images through the API and pick the platform-provided image whose `family` matches and whose `isFamilyCurrent` is `true`, then launch by its URN.
You can make the same pick from the output of `origin compute list-images`, which includes `family` and `isFamilyCurrent` for platform-provided images. For example, with `jq`:
```sh
origin compute list-images --project-urn \
| jq -r '.. | objects
| select(.family? == "" and .isFamilyCurrent? == true)
| .urn'
```
Pass the printed URN to `launch-instance` as `--image-urn`. The CLI help for `list-image-families` mentions an `--image-family` option, but `launch-instance` doesn’t accept one.
A family resolves separately per CPU architecture. With `X86_64` as the only architecture, a family resolves to one image.
A new image is published into a family first and designated current afterward, so a family can briefly have a newer image that isn’t current yet. A family that has no current image refuses launches with “no image is currently published for this family”.
## Family metadata [#family-metadata]
Read the families with the `imageFamilies` query or `origin compute list-image-families`. No permission is needed.
| Field | Meaning |
| --- | --- |
| `slug` | The name to pass as `imageFamily`, for example `ubuntu-22-04-minimal`. |
| `vendor` | Who publishes the upstream release, for example `Canonical`. |
| `os` | The operating system the family tracks, for example `ubuntu`. |
| `osVersion` | The release, for example `22.04`. |
| `description` | A human-readable description. |
| `supportEndsAt` | When the upstream vendor stops supporting this release, if a date is known. |
`supportEndsAt` is advisory. No launch is refused on it, and running instances aren’t affected. Treat it as notice to move to a newer family.
## Stable names and withdrawn families [#stable-names-and-withdrawn-families]
A family is never renamed, and a name is never reused for a different line. A name in your scripts keeps meaning what it meant.
A family can be withdrawn when a newer line supersedes it. A withdrawn family:
- Drops out of `imageFamilies` and `list-image-families`.
- Refuses launches by its name, with `image family '' is retired and launches nothing`.
- Doesn’t affect anything you’re already running. The images published under it stay listed and can still be launched by URN.
## Related [#related]
- [Images](/docs/compute/images)
- [Launch an instance](/docs/compute/instances/launch)
- [`list-image-families` reference](/docs/compute/reference/cli#list-image-families)
# Images
An image is what an instance boots from. Learn the difference between platform-provided and your own images, and what each image field means.
An image is the template an instance boots from: the operating system and whatever else was built into it. You choose one at launch. The launch copies the image onto the new instance’s root disk, and from then on the instance doesn’t depend on the image.
The following table shows where images come from and how they’re used.
| From | Step | To |
| --- | --- | --- |
| Image family | resolves to | Platform-provided image |
| Volume | snapshot | Protected snapshot |
| Protected snapshot | `create-image` | Your image |
| Platform-provided image | launch | Instance |
| Your image | launch | Instance |
## Key concepts [#key-concepts]
| Concept | Meaning |
| --- | --- |
| Platform-provided image | An image the platform publishes, such as a Debian or Ubuntu base image. Any project can launch from one. It lists alongside your own images in `list-images`. |
| Your own image | An image you create from a protected snapshot of one of your volumes. It belongs to the project you create it in. See [Create an image](/docs/compute/images/create). |
| Image family | A stable name for a line of platform-provided images that resolves to the current one. See [Image families](/docs/compute/images/image-families). |
| Default user | The account an instance launched from the image logs in as. Every image has a `defaultUser`. The platform-provided images use `cloud`. See [Guest environment](/docs/compute/instances/guest-environment). |
Your own image depends on the snapshot it was built from for its whole life. The platform doesn’t check whether an image uses the snapshot. Once you unprotect or delete that snapshot, launching instances from the image is refused, although the image still reads `AVAILABLE`. See [Delete a snapshot](/docs/storage/snapshots/delete).
## Image fields [#image-fields]
Three image fields are typed enums in the API. Each has exactly one value. Handle the value you get, and let a value your client doesn’t recognize surface rather than defaulting it away.
| Field | Value | Meaning |
| --- | --- | --- |
| `status` | `AVAILABLE` | The image can be launched from. An image becomes visible only once its contents are in place, and there is no other status. An image that couldn’t be created never appears. |
| `architecture` | `X86_64` | The CPU architecture the image’s contents are built for. An instance launched from it runs on a machine of that architecture. |
| `platform` | `LINUX_UNIX` | The operating-system family. It covers every Linux and UNIX-like distribution. |
Platform-provided images also carry `family`, the family they belong to, and `isFamilyCurrent`, whether the family currently resolves to that image.
## What you can do [#what-you-can-do]
- [Create an image](/docs/compute/images/create) from one of your volumes
- List images with [`origin compute list-images`](/docs/compute/reference/cli#list-images) and read one with [`origin compute get-image`](/docs/compute/reference/cli#get-image)
- [Launch an instance](/docs/compute/instances/launch) from an image
## Related [#related]
- [Image families](/docs/compute/images/image-families)
- [Snapshots](/docs/storage/snapshots)
- [origin compute commands](/docs/compute/reference/cli)
# What is Origin Cloud Compute?
Compute runs virtual machines on Origin Cloud. Learn how instances, images, instance types and key pairs fit together and how to reach them.
Compute runs virtual machines, called instances, without you owning or operating the hardware underneath. You pick an image to boot from, an instance type for its size and a key pair to log in with. The platform creates the instance's root disk and network interface, places it on a machine and starts it. You can stop an instance, start it again later, change its size while it's stopped, or terminate it for good.
The image provides the operating system. The instance type sets vCPU and memory. The key pair's public key is installed for the login user. Volumes hold the instance's data and live in the [Storage guide](/docs/storage). The network interface and its security groups belong to the [Network guide](/docs/network).
## Features [#features]
- **Instances**: Virtual machines with a lifecycle you control, health checks that report what the platform observes, and defined behavior when a machine fails. See [Instances](/docs/compute/instances).
- **Instance storage**: Every instance boots from a durable root disk you can size at launch. You can attach and detach more volumes while the instance runs. See [Instance storage](/docs/compute/instance-storage).
- **Images**: Platform-provided images and image families, plus your own images made from a snapshot of a volume. See [Images](/docs/compute/images).
- **Key pairs**: SSH key pairs you import or have the platform generate. The public half goes into every instance you launch with it. See [Key pairs](/docs/compute/key-pairs).
## Ways to access Compute [#ways-to-access-compute]
- **CLI**: The `origin compute` command group. See [CLI access](/docs/platform/access/cli) to install and sign in, and [origin compute commands](/docs/compute/reference/cli) for every command.
- **GraphQL API**: Instances, images, image families, instance types and key pairs live under the `compute` namespace of the API, for both queries and mutations. See [API access](/docs/platform/access/api).
- **Origin Cloud console**: The web interface at [console.origincloud.eu](https://console.origincloud.eu), for working with your instances in a browser. These docs cover the CLI and the API.
## When to use Compute [#when-to-use-compute]
Use Compute when you need a general-purpose Linux machine you administer yourself: a web server, a build agent, a database you operate, or the nodes of your own Kubernetes cluster. You get full root access through `sudo`, a durable root disk and a private network.
Compute doesn't restart an instance for you after a machine failure. If a workload must keep serving through the loss of one machine, run more than one instance. For more information, see [When the machine under an instance fails](/docs/compute/instances/host-failure).
## Related services [#related-services]
- [Storage](/docs/storage): volumes and snapshots that hold instance data
- [Network](/docs/network): VPCs, subnets, security groups and floating IPs that connect instances
- [Platform](/docs/platform): organizations, projects, billing and access
## Pricing [#pricing]
An instance's compute usage is billed while it is `RUNNING`. Its volumes are billed while they exist, including while the instance is stopped. For prices, see [Pricing](/docs/pricing).
## Next steps [#next-steps]
- [Get started with Origin Cloud](/docs/platform/getting-started)
- [Launch an instance](/docs/compute/instances/launch)
- [Compute reference](/docs/compute/reference): every command and status reason
- [Troubleshoot Compute](/docs/compute/troubleshooting)
# Attach and detach volumes
Attach an available volume to a running or stopped instance, choose its guest device name, and detach it again to use elsewhere.
Attach a volume to give an instance another disk. Detach it to move the disk and its data to another instance. The instance can be running or stopped.
## Before you begin [#before-you-begin]
- An instance in `RUNNING` or `STOPPED`.
- A volume in `AVAILABLE` status, in the same project and availability zone as the instance. See [Create a volume](/docs/storage/volumes/create).
- The `origin` CLI, signed in. See [CLI access](/docs/platform/access/cli).
## Attach a volume [#attach-a-volume]
1. Attach the volume:
```sh
origin compute attach-volume \
--instance-urn \
--volume-urn
```
To choose the guest device name, add `--device-name`, for example `--device-name vdb`. Names run from `vda` to `vdz`, and `vdc` is reserved by the platform. Omitted, the platform assigns the first free name.
1. Check the attachment in the instance’s `volumeAttachments`:
```sh
origin compute get-instance --instance-urn
```
- On a stopped instance, the attachment reads `ATTACHED` right away and the disk appears in the guest at the next start.
- On a running instance, the disk is added live. The attachment reads `ATTACHING`, then `ATTACHED` once the guest sees the device. If the device can’t be added, it reads `FAILED` and the volume is released.
1. Verify inside the guest that the disk is there, under the attachment’s `deviceName`:
```sh
lsblk
```
A new volume has no file system. Create one before you mount it.
## Detach a volume [#detach-a-volume]
1. Unmount the file system inside the guest if the instance is running.
1. Detach the volume:
```sh
origin compute detach-volume \
--instance-urn \
--volume-urn
```
On a running instance the attachment reads `DETACHING` until the guest releases the device. If the guest doesn’t release it, the attachment returns to `ATTACHED` and the volume stays attached.
1. Verify that the volume reads `AVAILABLE`:
```sh
origin storage get-volume --volume-urn
```
The attachment stays in the instance’s `volumeAttachments` history as `DETACHED`, with its volume reference cleared.
You can’t detach an instance’s root disk.
## Using the API [#using-the-api]
The `attachVolume` and `detachVolume` mutations return the attachment:
```graphql
mutation {
compute {
attachVolume(input: {
instanceUrn: ""
volumeUrn: ""
deviceName: "vdb"
}) {
urn
deviceName
status
}
}
}
```
## If this fails [#if-this-fails]
An attach is refused when the instance is neither running nor stopped, when the volume isn’t `AVAILABLE`, or when the device name you asked for is already taken. To find which instance holds a volume that reads `INUSE`, see [Find the instance that holds a volume](/docs/storage/volumes/find-instance).
## Related [#related]
- [`attach-volume` reference](/docs/compute/reference/cli#attach-volume)
- [`detach-volume` reference](/docs/compute/reference/cli#detach-volume)
- [Instance storage](/docs/compute/instance-storage)
# Instance storage
How an instance's durable root disk is created and sized at launch, and how extra volumes attach to a running or stopped instance.
Every instance boots from a root disk that the launch creates from the image. On top of that, you can attach volumes you created yourself. All of an instance’s volumes are durable network storage that isn’t tied to any machine, so an instance can stop, start and move between machines without losing data.
The following table shows where an instance’s disks come from.
| From | Step | To |
| --- | --- | --- |
| Image | launch copies | Root disk of the instance |
| Volume you created | attach | Instance |
| Instance | detach | Volume you created |
## Key concepts [#key-concepts]
| Concept | Meaning |
| --- | --- |
| Root disk | The volume the instance boots from. The launch creates it by copying the image onto it. It can’t be detached, and it’s deleted when the instance terminates. |
| Attached volume | A volume you created and attached. It outlives the instance: termination releases it rather than deleting it. See [Attach and detach volumes](/docs/compute/instance-storage/attach-detach). |
| Storage backend | Instance volumes use the `pvs` backend: durable, network-attached storage. A launch that asks for `host_local` is refused immediately, naming the field, and creates nothing. |
## Sizing the root disk [#sizing-the-root-disk]
By default the root disk is exactly as large as the image, which for a platform-provided image is enough for the operating system and little else. Ask for more at launch with `bootVolume` on `launchInstance`, or `--boot-volume-size-gib` and `--boot-volume-storage-class` on `origin compute launch-instance`. Size and storage class are independent, and both are optional.
- **The image’s size is the minimum.** A smaller size is refused rather than raised. The error names the field and the smallest size that works.
- **You get and pay for exactly the size you ask for.** Most images grow their root file system to fill the disk on first boot. That behavior belongs to the image, so check inside the guest if it matters.
- **The storage class is checked against the live catalog.** Read it with `origin storage list-storage-classes` or the `pvs.storageClasses` query, and pick one whose `available` is `true`. A class that doesn’t exist is refused as invalid input. One that exists but isn’t on sale is refused with `PRODUCT_UNAVAILABLE`. See [Storage classes](/docs/storage/volumes/storage-classes).
- **It counts against your storage quota at launch.** A launch that would take the organization or project past its volume storage limit is refused up front, naming the quota. See [Limits](/docs/platform/reference/limits).
You can’t change the root disk’s storage class after launch. To grow it later, resize the volume, which only grows. See [Resize a volume](/docs/storage/volumes/resize). Both are reasons to ask for what you need at launch.
## What you can do [#what-you-can-do]
- [Attach and detach volumes](/docs/compute/instance-storage/attach-detach)
- [Launch an instance](/docs/compute/instances/launch) with a larger root disk
- [Find which instance holds a volume](/docs/storage/volumes/find-instance)
## Limits and quotas [#limits-and-quotas]
See [Limits](/docs/platform/reference/limits).
## Related [#related]
- [Volumes](/docs/storage/volumes)
- [Snapshots](/docs/storage/snapshots)
- [Images](/docs/compute/images)
# Change an instance's type
Change a stopped instance to a different instance type so it starts again with more or fewer vCPUs and memory, keeping its identity and volumes.
Change an instance’s type to resize it, or to move it off a type that is no longer offered. Only the size changes. The instance keeps its URN, its addresses and its volumes.
## Before you begin [#before-you-begin]
- An instance that you stopped and that reads `STOPPED`. A `FAILED` instance still holds capacity on its machine, so you can’t change its type. Start and stop it cleanly first, or terminate it.
- Free vCPU quota if the new type is larger. Growing is checked against the same vCPU quota as a launch. Shrinking never is. See [Limits](/docs/platform/reference/limits).
## Change the type [#change-the-type]
1. Stop the instance if it’s running. See [Stop and start an instance](/docs/compute/instances/stop-start).
1. Pick a type whose `available` is `true`:
```sh
origin compute list-instance-types
```
1. Change the type:
```sh
origin compute change-instance-type \
--instance-urn \
--instance-type gp1.core.4
```
1. Verify the change. `instanceType` on the instance now reads the new type:
```sh
origin compute get-instance --instance-urn
```
1. Start the instance:
```sh
origin compute start-instance --instance-urn
```
## Using the API [#using-the-api]
```graphql
mutation {
compute {
changeInstanceType(input: {
instanceUrn: ""
instanceType: "gp1.core.4"
}) {
accepted
message
}
}
}
```
## If this fails [#if-this-fails]
- [`PRODUCT_UNAVAILABLE`](/docs/platform/reference/errors#product_unavailable): the type you named is no longer offered. Pick one whose `available` is `true`. See [Instance types](/docs/compute/instances/instance-types).
- Quota exceeded: the larger type would take the organization or project past its vCPU limit. Choose a smaller type or request a higher limit.
- The instance isn’t stopped: stop it first and wait for `STOPPED`.
## Related [#related]
- [`change-instance-type` reference](/docs/compute/reference/cli#change-instance-type)
- [Instance types](/docs/compute/instances/instance-types)
# Guest environment
What the platform sets up inside an instance at first boot - the login user and SSH key, time synchronization - and why each image needs its own machine-id.
At first boot, the platform hands the guest a short configuration through cloud-init. It creates the login user with your SSH key and points the guest’s clock at the platform’s time service. Everything else inside the guest comes from the image.
You can’t pass your own user data (a cloud-init configuration or script) at launch, and instances can’t be given names or labels. To start instances with your own configuration, build it into an image. See [Create an image](/docs/compute/images/create). To tell instances apart, keep your own record of which URN is which.
## Login user [#login-user]
Every instance has a login user: a non-root account with passwordless sudo and no password of its own. The public key of the instance’s key pair is its only credential, so the login is `ssh @`.
The name comes from one of two places:
- **The image’s `defaultUser`.** Every image carries one. The platform-provided images use `cloud`. When you create your own image you can set a different one. See [Images](/docs/compute/images).
- **A `loginUser` override at launch.** Set `loginUser` on `launchInstance`, or `--login-user` on `origin compute launch-instance`, to use a different name for one instance without publishing an image for it.
A login user name is a POSIX user name: lowercase letters, digits, underscores and hyphens, at most 32 characters, starting with a letter or underscore, and not `root`.
Whichever applies, the instance reports it as `loginUser`. Read the name from the instance rather than from the image. It’s fixed for the instance’s life, even if the image is later deleted or its family moves on.
## Time synchronization [#time-synchronization]
Instances keep their clocks synchronized without anything to install or open up. The platform serves time on the same address inside your subnet that answers DNS, and configures the guest’s `systemd-timesyncd` to use it at first boot. An instance with no floating IP and no route to the internet still keeps accurate time.
A drifting clock surfaces late and looks unrelated: TLS certificates that seem expired or not yet valid, tokens rejected as stale, clustered software disagreeing about order, and logs that don’t line up across instances. To confirm synchronization inside a running instance, run:
```sh
timedatectl
```
Expect `NTP service: active` and `System clock synchronized: yes`.
You can point the guest at your own time source instead, like on any Linux machine. Reaching a time server outside your VPC needs internet access, so an instance without a floating IP or a NAT gateway can only use the platform’s. See [Internet access](/docs/network/internet-access).
### Host clock trust [#host-clock-trust]
The time an instance receives comes from the physical machine it runs on. If that machine’s own clock isn’t synchronized, the platform tells the guest so instead of passing bad time off as good. The guest then declines to sync and reports `System clock synchronized: no`.
That’s the safe direction, but it means an unsynchronized clock can be a platform problem rather than yours. If `System clock synchronized: no` persists on an instance that uses the platform’s time service, contact Origin Cloud support.
## Machine identity [#machine-identity]
A Linux instance’s machine-id (`/etc/machine-id`) comes from its image. The platform-provided images ship it empty, so each instance generates its own on first boot.
An image you create from a volume contains the machine-id of the instance that volume belonged to. Every instance launched from that image starts with the same machine-id. Clear it before you snapshot the volume. For the steps, see [Create an image](/docs/compute/images/create).
Two instances that share a machine-id break in a way you’re likely to hit. systemd derives the MAC address of virtual network devices from the machine-id, so same-named VXLAN devices on both instances get the same MAC address and can’t exchange packets. That’s what Kubernetes pod networking with VXLAN or Geneve encapsulation looks like when it fails this way. Run `cat /etc/machine-id` on both instances first.
## Related [#related]
- [Key pairs](/docs/compute/key-pairs)
- [Images](/docs/compute/images)
- [Launch an instance](/docs/compute/instances/launch)
- [Troubleshoot Compute](/docs/compute/troubleshooting)
# Instance health checks
What each instance health check observes, how results combine into availability, and how the category tells you whether a problem is yours to fix.
`status` tells you what was asked for. Health checks tell you what the platform can observe right now. You need both: an instance whose machine has become unreachable is still `RUNNING`, because nothing stopped it. Read `healthChecks` on an instance for a result per check and an availability summary.
| What you see | What it means | What to do |
| --- | --- | --- |
| `availability` is `AVAILABLE` | The platform observes nothing wrong with the guest. | Nothing. It doesn’t prove your application is up; monitor that yourself. |
| A `SYSTEM` check is `IMPAIRED`, or checks read `INSUFFICIENT_DATA` | The platform underneath your instance has a problem, or has lost sight of the machine. | Nothing to fix inside the instance. If it persists, contact Origin Cloud support. |
| An `INSTANCE` check is `IMPAIRED` | Your instance’s own operating system or network configuration has a problem. | Fix it inside the instance. Waiting won’t fix it. If it’s `GUEST_PRESENT`, stop and start the instance. |
The sections below explain each check and how the summary is built.
```graphql
query {
compute {
instance(instanceUrn: "") {
status
healthChecks {
availability
checks { kind category status since }
}
}
}
}
```
`since` is when the check entered its current result. It’s `null` while nothing has observed the check.
## Checks [#checks]
Every check is always present in `checks`. A check with nothing to report says so rather than being left out.
| `kind` | `category` | What it observes |
| --- | --- | --- |
| `HOST_REACHABLE` | `SYSTEM` | Whether the platform can reach the machine carrying the instance. |
| `DOMAIN_STATE` | `INSTANCE` | What the machine reports about the virtual machine. `OK` only when it reports the virtual machine running. Paused or crashed reads `IMPAIRED`. |
| `NETWORK_REACHABLE` | `INSTANCE` | Whether the guest’s network stack answers. See [Network reachability](#network-reachability). |
| `GUEST_AGENT` | `INSTANCE` | A report from an agent inside the guest. Always `NOT_APPLICABLE`, because the platform’s images ship no such agent. |
| `GUEST_PRESENT` | `INSTANCE` | Whether the machine carrying the instance still has it. See [When `GUEST_PRESENT` is `IMPAIRED`](#when-guest_present-is-impaired). |
New kinds can appear in the enum. Ignore a kind your client doesn’t recognize rather than failing on it.
## Results [#results]
Each check reports one of four results:
| Result | Meaning |
| --- | --- |
| `OK` | The check ran and the instance passed. |
| `IMPAIRED` | The check ran and the instance failed it. |
| `INSUFFICIENT_DATA` | The platform could not tell, most often because the machine carrying the instance has stopped reporting. Treat it as unknown, not as healthy. |
| `NOT_APPLICABLE` | The check doesn’t apply. Every check reads `NOT_APPLICABLE` while the instance is `STOPPING`, `STOPPED`, `SHUTTING_DOWN` or `TERMINATED`, because there is no guest to observe. |
A result that isn’t refreshed for 120 seconds goes back to `INSUFFICIENT_DATA`. The platform doesn’t keep showing a value it can no longer confirm.
## Availability [#availability]
`availability` combines the checks into one value for a listing:
| `availability` | When |
| --- | --- |
| `IMPAIRED` | At least one check is `IMPAIRED`. |
| `UNKNOWN` | No check is `IMPAIRED`, and at least one is `INSUFFICIENT_DATA`. |
| `NOT_APPLICABLE` | Every check is `NOT_APPLICABLE`. |
| `AVAILABLE` | Every other case: no check is `IMPAIRED` or `INSUFFICIENT_DATA`, and at least one is `OK`. |
`NOT_APPLICABLE` doesn’t hold the summary down, so a healthy running instance reads `AVAILABLE` even though `GUEST_AGENT` is `NOT_APPLICABLE`. `INSUFFICIENT_DATA` does, so the summary never rounds an unknown up to `AVAILABLE`.
## Categories [#categories]
The `category` on each check tells you who has to act:
| Category | Who has to act |
| --- | --- |
| `SYSTEM` | The platform underneath your instance. There is nothing to fix inside the instance. If it persists, contact Origin Cloud support. |
| `INSTANCE` | Your instance’s own operating system and network configuration. Waiting won’t fix it. |
If you only read `availability`, you lose this distinction. Read the checks when the summary isn’t `AVAILABLE`.
## Network reachability [#network-reachability]
`NETWORK_REACHABLE` never reports an instance unhealthy only because it’s quiet. Traffic the guest sends counts as proof it’s alive. When the guest has sent nothing, the platform asks it directly with an IPv6 neighbor solicitation, which the guest’s kernel answers without any agent. The check reads `IMPAIRED` only after three consecutive probes go unanswered, about 90 seconds of silence.
The check tells you the guest’s operating system and network stack are up. It doesn’t tell you your application is. A crashed service inside a healthy guest doesn’t show up here. Use your own monitoring for that.
## When the machine stops reporting [#when-the-machine-stops-reporting]
When the platform loses contact with the machine carrying your instance, `HOST_REACHABLE` reads `IMPAIRED`. The instance-level checks stop being refreshed and read `INSUFFICIENT_DATA` within 120 seconds. Once the reachability result itself ages out, every check reads `INSUFFICIENT_DATA` and `availability` reads `UNKNOWN`.
Read that as “the platform has lost sight of this instance”, not “this instance has stopped”. The platform can’t tell which, and it doesn’t claim either. The instance’s `status` stays `RUNNING`. For what happens if the machine has failed, see [When the machine under an instance fails](/docs/compute/instances/host-failure).
## When GUEST_PRESENT is IMPAIRED [#when-guest_present-is-impaired]
`GUEST_PRESENT` reading `IMPAIRED` means the machine carrying your instance is up and reporting, and your instance is no longer running on it. That differs from an `IMPAIRED` `DOMAIN_STATE`, which describes a virtual machine that still exists but isn’t running properly.
The platform reports it only after the machine has given a complete account of what it runs and left your instance out for 60 seconds. A machine that’s merely unreachable never produces it. In the same state, `HOST_REACHABLE` reads `OK`.
This is the one check that asks you to act. The instance’s `status` stays `RUNNING`, because nobody asked for anything else. Stop the instance and start it again. The stop completes quickly, since there is nothing left to shut down. The start can place the instance on any machine, with its volumes, network interface and addresses unchanged. To automate this, poll `healthChecks` and act on `GUEST_PRESENT: IMPAIRED`.
## Related [#related]
- [Instance lifecycle](/docs/compute/instances/lifecycle)
- [When the machine under an instance fails](/docs/compute/instances/host-failure)
- [Stop and start an instance](/docs/compute/instances/stop-start)
- [Troubleshoot Compute](/docs/compute/troubleshooting)
# When the machine under an instance fails
What happens to an instance when its physical machine fails or is taken out of service, what survives, and why restarting it is your decision.
The machines your instances run on can fail, for example through a component fault or a loss of power. When the machine carrying your instance goes down, your instance goes down with it. The platform records that once it can prove it, and leaves restarting the instance to you.
The following diagram shows how an instance’s status and health change after its machine fails.
| From | Event | To |
| --- | --- | --- |
| `RUNNING` | Machine stops answering | `RUNNING`, `HOST_REACHABLE` impaired |
| `RUNNING`, `HOST_REACHABLE` impaired | Machine restart proven | `STOPPED` |
| `RUNNING`, `HOST_REACHABLE` impaired | Machine taken out of service | `STOPPED` |
| `RUNNING` | Machine restart proven | `STOPPED` |
| `STOPPED` | You start it | `PENDING` |
## While the machine is unreachable [#while-the-machine-is-unreachable]
A machine the platform can’t reach proves nothing about what runs on it. So the instance stays `RUNNING`, `HOST_REACHABLE` reads `IMPAIRED`, and the other checks fall back to `INSUFFICIENT_DATA`. For how to read that, see [Instance health checks](/docs/compute/instances/health-checks).
## When the platform records the failure [#when-the-platform-records-the-failure]
The platform moves the instance from `RUNNING` straight to `STOPPED`, without `STOPPING`, in two cases:
- The machine restarted. The machine comes back and the platform can prove it restarted. A virtual machine doesn’t survive that. `statusReason` reads: `the machine this instance was running on failed, and the instance went down with it; start it again to bring it back`.
- The machine is taken out of service. The machine doesn’t come back, and the platform takes it out of service after confirming it’s powered off. `statusReason` reads: `the machine this instance was running on failed and has been taken out of service; the instance went down with it, and starting it again will place it on another machine`.
From that moment the instance uses no compute capacity and accrues no compute usage, exactly as if you had stopped it. Its network interface stays reserved and its volumes stay attached.
## Starting it again is up to you [#starting-it-again-is-up-to-you]
The platform doesn’t start the instance again for you. Whether a workload should come back on its own after a failure, or needs checking first, depends on the workload.
Starting it is an ordinary start. Its volumes, network interface, addresses and security groups are as they were, and it can come up on a different machine. If your workload should come back on its own, watch for `STOPPED` with a non-null `statusReason` and start the instance. For the steps, see [Stop and start an instance](/docs/compute/instances/stop-start).
The status reason says “start it again to bring it back”, and a start usually does. After a start, check that the guest really answers, not only that the instance reads `RUNNING` and `AVAILABLE`: connect to it, or query its CPU metric. If it stays unreachable, see [Running and available after a machine failure, but unreachable](/docs/compute/troubleshooting#running-and-available-after-a-machine-failure-but-unreachable).
## What survives [#what-survives]
| Outcome | What |
| --- | --- |
| Survives | Everything on the instance’s volumes. Volumes aren’t tied to a machine, so they come back attached to the same instance with the same contents. Nothing is rebuilt from the image. The instance URN, network interface, private and public addresses, and security groups also stay the same. |
| Doesn’t survive | Anything only in memory, and anything on a temporary file system. Treat a machine failure the way you’d treat a sudden power loss. |
## Planned moves [#planned-moves]
When a machine needs maintenance, the platform can move the instances on it to another machine. Moving an instance means stopping it and starting it again elsewhere. From inside the guest, that looks like a reboot you didn’t ask for. In the API, the instance passes through `STOPPING`, `STOPPED` and `PENDING` back to `RUNNING`, with the same volumes, interface and addresses.
If your workload can’t tolerate an unannounced restart, run more than one instance and spread the load across them. A move affects the instances on one machine, so an instance on another machine keeps serving.
## Related [#related]
- [Instance health checks](/docs/compute/instances/health-checks)
- [Instance lifecycle](/docs/compute/instances/lifecycle)
- [Status reasons](/docs/compute/reference/status-reasons)
# Instances
An instance is a virtual machine on Origin Cloud. Find its lifecycle, types, health checks, failure behavior and the tasks to launch and manage one.
An instance is a virtual machine. It boots from an image, runs with the vCPU and memory of its instance type, and keeps its identity, addresses and volumes for its whole life, across stops and starts. You decide when it runs. The platform reports both what you asked for (`status`) and what it can observe (`healthChecks`).
The following diagram shows the main path through an instance’s life.
The full set of eight statuses, including `FAILED`, is on [Instance lifecycle](/docs/compute/instances/lifecycle).
## Key concepts [#key-concepts]
| Concept | Meaning |
| --- | --- |
| Lifecycle | The eight statuses an instance moves through, which ones resolve on their own, and which ones you’re billed for. See [Instance lifecycle](/docs/compute/instances/lifecycle). |
| Instance type | The size of an instance: its vCPU count and memory, from a catalog of types. See [Instance types](/docs/compute/instances/instance-types). |
| Health checks | What the platform observes about a running instance, separate from its status, and whether a problem is the platform’s or yours. See [Instance health checks](/docs/compute/instances/health-checks). |
| Machine failure | What happens to an instance when the physical machine under it fails or is taken out of service. See [When the machine under an instance fails](/docs/compute/instances/host-failure). |
| Guest environment | What the platform sets up inside the guest: the login user, time synchronization and machine identity. See [Guest environment](/docs/compute/instances/guest-environment). |
## What you can do [#what-you-can-do]
- [Launch an instance](/docs/compute/instances/launch)
- [Stop and start an instance](/docs/compute/instances/stop-start)
- [Change an instance’s type](/docs/compute/instances/change-type)
- [Terminate an instance](/docs/compute/instances/terminate)
## Limits and quotas [#limits-and-quotas]
Launching an instance counts against your instance-count and vCPU quotas, at both the organization and the project level. See [Limits](/docs/platform/reference/limits).
## Related [#related]
- [Instance storage](/docs/compute/instance-storage) – the root disk and extra volumes
- [Images](/docs/compute/images) – what an instance boots from
- [Key pairs](/docs/compute/key-pairs) – how you log in
- [Security groups](/docs/network/traffic-control/security-groups) – what traffic reaches an instance
- [origin compute commands](/docs/compute/reference/cli)
# Instance types
How instance types set an instance's vCPU and memory, how type names are built, and how to read the live catalog and its available flag.
An instance type sets an instance’s vCPU count and memory. You choose one at launch, and you can change it later while the instance is stopped. A running instance keeps the size it has.
## Type names [#type-names]
A type name has three parts, for example `gp1.core.2`:
| Part | Meaning |
| --- | --- |
| Kind | The first part, such as `gp1`. A kind is a hardware family. Instances of one kind only run on machines built for that kind. |
| Profile | The middle part, such as `core`. It describes the type’s memory and network profile. |
| Size | The last part, the vCPU count. |
Don’t derive vCPU or memory from the name. Each type in the catalog states both.
## Types on sale [#types-on-sale]
On 13 October 2026, these types were on sale, at these list prices (EUR excluding VAT). The catalog and the [price list](/docs/pricing) are the live source: check `available` and each type’s `vcpu` and `memoryMib` there before you launch.
| Instance type | List price per hour | About per month (730 hours) |
| --- | --- | --- |
| `gp1.core.2` | €0.0551 | €40.22 |
| `gp1.core.4` | €0.1103 | €80.52 |
| `gp1.core.8` | €0.2205 | €160.97 |
| `gp1.core.16` | €0.4410 | €321.93 |
| `gp1.core.32` | €0.8821 | €643.93 |
`gp1.core.2`, with 2 vCPUs and 8 GiB of memory, is the smallest. Each price is the price list entry `compute.gp1.core.`; see [Read the price list](/docs/pricing/read-price-list).
## The catalog [#the-catalog]
The catalog lists every instance type the platform has. Read it with the `instanceTypes` query or with `origin compute list-instance-types`. No permission is needed, and the catalog is the same for every organization.
Each entry carries these fields:
| Field | Meaning |
| --- | --- |
| `instanceType` | The name to pass at launch, for example `gp1.core.2`. |
| `kind` | The hardware family, for example `gp1`. |
| `cpuAllocationMode` | The middle part of the name, for example `core`. |
| `vcpu` | Number of vCPUs. |
| `memoryMib` | Memory in MiB. |
| `available` | Whether you can launch or change to this type right now. |
## Available and withdrawn types [#available-and-withdrawn-types]
The catalog also lists types that are no longer offered, with `available: false`. They stay listed because an instance running as one still reports that type, and you need to be able to look it up. Filter on `available` before you pick a type.
A withdrawn type affects instances like this:
- Launch or change to it. Refused with `PRODUCT_UNAVAILABLE`. A type name that never existed is refused as invalid input instead.
- A running instance of that type. Unaffected. It keeps its vCPU and memory.
- A stopped instance of that type. Starting it is refused with `PRODUCT_UNAVAILABLE`, naming the type. The platform doesn’t start it at a different size on its own. Change it to an available type first. See [Change an instance’s type](/docs/compute/instances/change-type).
## Capacity [#capacity]
A type in the catalog with `available: true` can still be refused at launch when no machine has room for it. The launch fails with `INSUFFICIENT_CAPACITY`, naming the type and what was short. Nothing is created.
## Related [#related]
- [Launch an instance](/docs/compute/instances/launch)
- [Change an instance’s type](/docs/compute/instances/change-type)
- [Limits](/docs/platform/reference/limits)
- [Pricing](/docs/pricing)
The machine series page on origincloud.eu describes the families and the workloads each is built for.
# Launch an instance
Launch a virtual machine with the CLI or the API - choose an image, instance type, key pair, network and root disk - and log in over SSH.
Launch an instance to get a running Linux machine you can log in to over SSH. You choose what it boots from, its size, its key pair and where it sits on the network.
## Before you begin [#before-you-begin]
- An organization that is approved and has a valid payment method, and a project to launch into. See [Organizations](/docs/platform/organizations) and [Add a payment method](/docs/platform/billing/payment-method). The project’s URN is `urn:origin:cloud:admin::::`; see [Resource URNs](/docs/platform/access/api#resource-urns).
- The `origin` CLI, signed in. See [CLI access](/docs/platform/access/cli).
- A key pair in the project, and its URN from the `urn` field that `import-key-pair` or `generate-key-pair` printed. `origin compute list-key-pairs --project-urn ` lists it again. See [Create a key pair](/docs/compute/key-pairs/create).
- Free quota for one more instance and its vCPUs, and for its root disk. See [Limits](/docs/platform/reference/limits).
## Launch the instance [#launch-the-instance]
1. Choose an instance type whose `available` is `true`:
```sh
origin compute list-instance-types
```
For what the fields mean, see [Instance types](/docs/compute/instances/instance-types).
1. Choose an image. List the platform-provided images and your own:
```sh
origin compute list-images --project-urn
```
To launch the current build of an image family instead, see [Using the API](#using-the-api). The CLI only launches by image URN.
1. Launch the instance:
```sh
origin compute launch-instance \
--project-urn \
--image-urn \
--instance-type gp1.core.2 \
--key-pair-urn
```
With no `--subnet-urn`, the instance goes into your project’s default subnet. That subnet is created on first use, in a VPC with an internet gateway, and the instance’s network interface gets a public address automatically. See [Default VPC](/docs/network/vpcs/default-vpc).
1. Add the options you need. Each is optional:
| Option | Use it to |
| --- | --- |
| `--subnet-urn ` | Place the instance in a subnet of your own VPC. |
| `--security-group-urn ` | Attach security groups to the network interface. Repeat it for several groups. Omitted, the VPC’s default security group applies. You can’t change the interface’s groups after launch, only the rules inside them. See [Security groups](/docs/network/traffic-control/security-groups). |
| `--boot-volume-size-gib ` | Make the root disk bigger than the image. See [Instance storage](/docs/compute/instance-storage). |
| `--boot-volume-storage-class ` | Pick the root disk’s storage class. See [Storage classes](/docs/storage/volumes/storage-classes). |
| `--login-user ` | Override the image’s default user. See [Guest environment](/docs/compute/instances/guest-environment). |
`--volume-backend` accepts only `pvs`, which is the default. Leave it out.
A launch takes no user data (cloud-init configuration of your own), and instances, volumes and network resources can’t be given names or labels. Build the configuration you need into your own image, see [Create an image](/docs/compute/images/create), and keep your own record of which URN is which.
1. Note the instance’s `urn` and `loginUser` in the response. The following steps use them.
1. Wait for the instance to reach `RUNNING`. Run `get-instance` until status stops changing:
```sh
origin compute get-instance --instance-urn
```
It passes through `INITIALIZING` and `PENDING` first. If it ends up `FAILED`, read its `statusReason` and see [Status reasons](/docs/compute/reference/status-reasons). If the host never confirms the start, the instance can stay `PENDING` for about 30 minutes before it becomes `FAILED`. To poll every 10 seconds until the status stops changing, with `jq`:
```sh
while :; do
status="$(origin compute get-instance --instance-urn \
| jq -r '[.. | .status? | strings] | first')"
echo "$status"
case "$status" in RUNNING | STOPPED | FAILED | TERMINATED) break ;; esac
sleep 10
done
```
1. Find the instance’s public address. List the project’s floating IPs and their private addresses:
```sh
origin network list-floating-ips --project-urn
```
To match a floating IP to the instance, list the network interfaces with `origin network list-network-interfaces --project-urn `. The interface whose `attachedToUrn` is your instance’s URN carries its private addresses. See [Network interfaces](/docs/network/vpcs/network-interfaces).
To print the instance’s public address in one go, with `jq`:
```sh
nic="$(origin compute get-instance --instance-urn \
| jq -r '[.. | .networkInterfaceAttachments? // empty | .[].networkInterfaceUrn] | first')"
origin network list-floating-ips --project-urn \
| jq -r --arg nic "$nic" '.. | objects | select(.networkInterfaceUrn? == $nic) | .address'
```
1. Verify that you can log in, as the instance’s `loginUser`, with the private key of the key pair:
```sh
ssh -i @
```
The VPC’s default security group allows SSH from anywhere. If you attached other security groups, one of them must allow inbound TCP port 22 from your address.
## Using the API [#using-the-api]
The `launchInstance` mutation takes the same inputs. It also accepts `imageFamily` in place of `imageUrn`, which launches the image currently designated for that family. Set exactly one of the two. See [Image families](/docs/compute/images/image-families).
```graphql
mutation {
compute {
launchInstance(input: {
projectUrn: ""
imageFamily: ""
instanceType: "gp1.core.2"
keyPairUrn: ""
bootVolume: { sizeInGib: 40 }
}) {
urn
status
loginUser
}
}
}
```
## If the launch is refused [#if-the-launch-is-refused]
A refused launch creates nothing and costs nothing.
- The message names the type and what was short. See [`INSUFFICIENT_CAPACITY`](/docs/platform/reference/errors#insufficient_capacity).
- `PRODUCT_UNAVAILABLE`: the instance type or storage class isn’t offered. Pick one whose `available` is `true`. See [`PRODUCT_UNAVAILABLE`](/docs/platform/reference/errors#product_unavailable).
- Quota: the launch would take the organization or project past an instance, vCPU or storage limit. The error names the quota. See [Limits](/docs/platform/reference/limits).
- Root disk too small: `--boot-volume-size-gib` is smaller than the image. The error names the smallest size that works.
For other problems, see [Troubleshoot Compute](/docs/compute/troubleshooting).
## Next steps [#next-steps]
- [Attach a volume](/docs/compute/instance-storage/attach-detach)
- [Associate a floating IP](/docs/network/internet-access/floating-ips#use-a-floating-ip), for an instance in a subnet that doesn’t assign public addresses automatically
- [Stop and start an instance](/docs/compute/instances/stop-start)
## Related [#related]
- [`launch-instance` reference](/docs/compute/reference/cli#launch-instance)
- [Instance lifecycle](/docs/compute/instances/lifecycle)
# Instance lifecycle
The eight statuses an instance moves through from launch to termination, what changes each one, what you're billed for, and what FAILED means.
An instance’s status is always one of eight values. Four of them are transitional and resolve on their own. `RUNNING`, `STOPPED` and `FAILED` change only when something asks for a change, and `TERMINATED` is final. Every lifecycle operation is asynchronous: the call returns once the platform accepts the request, and `status` tells you what happened.
The following diagram shows every transition you can observe.
You can also terminate an instance that is `INITIALIZING`, `PENDING` or `STOPPING`. The diagram leaves those edges out to stay readable.
## Statuses [#statuses]
`status` is a typed enum in the API. A client generated from the schema gets the full set, so compare against the enum rather than against strings you’ve seen in a response.
| `status` | What it means | Compute billed |
| --- | --- | --- |
| | Just launched. Its root disk and network interface are being created. Not running, not reachable. Moves on by itself. | No |
| | Everything it needs is ready and the platform has asked its host to start it. Moves on by itself. | No |
| | The host confirmed the instance started. | Yes |
| | A stop was requested. The guest may still be running until it shuts down. Moves on by itself. | No |
| | Not running, but still yours. Its network interface stays reserved and its volumes stay attached. You can start it again. | No |
| | A termination was requested. The guest is being shut down if it was running, and the instance’s resources are being released. Moves on by itself. | No |
| | Permanently gone, and the resources it held are released. Nothing leaves this status. | No |
| | The host didn’t do what it was asked, or something the instance needs could not be created. Always carries a `statusReason`. | No |
Compute usage stops being metered as soon as the instance leaves `RUNNING`. Volumes are billed separately for as long as they exist, so a `STOPPED` instance’s root disk is still billed. For storage billing, see [Volumes](/docs/storage/volumes).
## Changes nobody asked the platform for [#changes-nobody-asked-the-platform-for]
Two transitions happen without a stop request:
- Guest power-off. When you shut the operating system down from inside the guest (`poweroff`, `shutdown -h`), the instance goes from `RUNNING` straight to `STOPPED`, without `STOPPING`. Its `statusReason` stays `null`. Start it again the usual way.
- Machine failure. When the platform can prove the machine under a running instance failed, it records the instance as `STOPPED` with a `statusReason` that says so. For details, see [When the machine under an instance fails](/docs/compute/instances/host-failure).
## Polling [#polling]
Poll through the transitional statuses: `INITIALIZING`, `PENDING`, `STOPPING` and `SHUTTING_DOWN`. Stop polling when the instance reaches `RUNNING`, `STOPPED`, `FAILED` or `TERMINATED`.
`RUNNING` means the host confirmed the start. It doesn’t prove the guest’s operating system and network are up. To know that, read the instance’s health checks. For more information, see [Instance health checks](/docs/compute/instances/health-checks).
## When a lifecycle operation fails [#when-a-lifecycle-operation-fails]
If the host can’t carry out a start or a stop, the instance ends up `FAILED`. It never stays in a transitional status waiting for something that isn’t coming. `FAILED` means one thing: the platform can’t confirm the instance is where you asked it to be. It doesn’t promise that the guest is stopped or gone.
The common cases:
- A launch or start that failed. The host refused the start, or a volume or network interface the instance needs could not be created or attached. `statusReason` says which.
- A stop that failed. The guest may still be running.
- An operation the host never confirmed. If the instance’s host is reachable but doesn’t confirm a start or a stop, the platform sends the request again, three times in total, about 10 minutes apart. An instance can therefore sit in `PENDING`, `STOPPING` or `SHUTTING_DOWN` for about 30 minutes before it becomes `FAILED`, with a `statusReason` saying the host did not confirm.
A `FAILED` instance keeps its network interface and volumes, stays listed, and never retries on its own. You have two ways forward:
- Start it. `start-instance` moves it to `PENDING` and back into the normal lifecycle. There is no separate “retry the stop”: start it, then stop it again.
- Terminate it. Terminating a `FAILED` instance doesn’t wait for its host to confirm the guest is gone, because the host may not answer at all. The platform releases the instance’s resources, stops billing and reports `TERMINATED`.
A `FAILED` instance can still hold capacity on its host, and you can’t change its type. Don’t leave one sitting indefinitely. Every possible `statusReason` is listed in [Status reasons](/docs/compute/reference/status-reasons).
## Terminated instances [#terminated-instances]
A terminated instance stays in `list-instances` for 2 hours after it terminates, then drops out of the default list. You can still read it by its URN with `get-instance`, however long ago it terminated.
## Related [#related]
- [Stop and start an instance](/docs/compute/instances/stop-start)
- [Terminate an instance](/docs/compute/instances/terminate)
- [Status reasons](/docs/compute/reference/status-reasons)
- [Troubleshoot Compute](/docs/compute/troubleshooting)
# Stop and start an instance
Stop an instance to release its vCPU and memory while keeping its disks and addresses, and start it again later, possibly on another machine.
Stop an instance when you don’t need it running. A stopped instance accrues no compute usage, and it keeps its volumes, network interface and addresses. Start it again when you need it, the same instance, possibly on a different machine.
## Before you begin [#before-you-begin]
- To stop: an instance in `RUNNING`.
- To start: an instance in `STOPPED` or `FAILED`.
- The `origin` CLI, signed in. See [CLI access](/docs/platform/access/cli).
A stopped instance’s volumes are still billed. Terminating the instance stops billing for it and deletes the volumes its launch created, except a volume that has a snapshot: that one stays and is still billed. See [Terminate an instance](/docs/compute/instances/terminate).
## Stop the instance [#stop-the-instance]
1. Request the stop:
```sh
origin compute stop-instance --instance-urn
```
The platform asks the guest operating system to shut down cleanly. A guest that hasn’t shut down after 5 minutes is powered off.
1. Run `get-instance` until `status` reads `STOPPED`:
```sh
origin compute get-instance --instance-urn
```
The instance passes through `STOPPING` first.
You can also shut the guest down from inside, with `sudo poweroff`. The instance then goes from `RUNNING` straight to `STOPPED`.
## Start the instance [#start-the-instance]
1. Request the start:
```sh
origin compute start-instance --instance-urn
```
1. Run `get-instance` until `status` reads `RUNNING`. The instance passes through `PENDING` first.
1. Verify that the guest is up. Its `healthChecks.availability` reads `AVAILABLE` once the platform has seen its network stack answer. See [Instance health checks](/docs/compute/instances/health-checks).
Starting an instance that is already `RUNNING` reports success and changes nothing. Starting one that is still `PENDING` re-sends the start it is waiting for, without disturbing a guest that is coming up. A start is refused while the instance is `INITIALIZING`, because it starts on its own once its resources are ready, and while it is `STOPPING` or `SHUTTING_DOWN`.
## Using the API [#using-the-api]
The `startInstance` and `stopInstance` mutations take the instance URN:
```graphql
mutation {
compute {
stopInstance(input: { instanceUrn: "" }) {
accepted
message
}
}
}
```
## If this fails [#if-this-fails]
- The start is refused with `PRODUCT_UNAVAILABLE`. The instance’s type is no longer offered. Change it to an available type, then start it. See [Change an instance’s type](/docs/compute/instances/change-type).
- The start is refused with `INSUFFICIENT_CAPACITY`. A stopped instance is placed afresh when it starts. To try a larger type, change the instance’s type first. See [Change an instance’s type](/docs/compute/instances/change-type).
- The instance ends up `FAILED`. Read its `statusReason`. See [When a lifecycle operation fails](/docs/compute/instances/lifecycle#when-a-lifecycle-operation-fails).
## Related [#related]
- [`stop-instance` reference](/docs/compute/reference/cli#stop-instance)
- [`start-instance` reference](/docs/compute/reference/cli#start-instance)
- [Instance lifecycle](/docs/compute/instances/lifecycle)
# Terminate an instance
Terminate an instance permanently, and learn which of its volumes, network interfaces and addresses are deleted and which stay with you.
Terminate an instance when you no longer need it. Termination is permanent and stops billing for the instance. The volumes its launch created are deleted with it, unless a volume has a snapshot: then it stays, and it’s still billed. See [What happens to the instance’s resources](#what-happens-to-the-instances-resources).
## Before you begin [#before-you-begin]
- Copy off any data you need from the instance’s root disk. The root disk and every other volume the launch created are deleted with the instance, and there is no option to keep them.
- Detach any volume you want to keep using elsewhere, or let termination release it. Volumes you attached yourself are never deleted. See [Attach and detach volumes](/docs/compute/instance-storage/attach-detach).
Termination can’t be undone. The instance, its root disk and its launch-created network interface are gone for good.
## Terminate the instance [#terminate-the-instance]
1. Request the termination:
```sh
origin compute terminate-instance --instance-urn
```
You can terminate an instance in any status. A `FAILED` instance is terminated without waiting for its machine to confirm the guest is gone.
1. Run `get-instance` until `status` reads `TERMINATED`:
```sh
origin compute get-instance --instance-urn
```
The instance passes through `SHUTTING_DOWN` while its resources are released, normally for a few seconds.
Terminating is safe to repeat. If you aren’t sure an earlier attempt went through, call it again. Terminating an instance that is already `TERMINATED` reports success and changes nothing.
## What happens to the instance’s resources [#what-happens-to-the-instances-resources]
| Resource | On termination |
| --- | --- |
| Root disk and other launch-created volumes | Deleted. |
| Volumes you attached yourself | Detached and `AVAILABLE` again. Not deleted. |
| Launch-created network interface | Deleted, with any public address the platform assigned to it automatically. |
| Floating IP you allocated yourself | Disassociated. It stays allocated to you until you release it. See [Floating IPs](/docs/network/internet-access/floating-ips). |
A launch-created volume that has a snapshot can’t be deleted, so it stays `AVAILABLE` and billed after the instance terminates. Its `retentionNote` says why. Delete the snapshots, then the volume. See [Delete a volume](/docs/storage/volumes/delete).
If something else can’t be released, the instance still reaches `TERMINATED` and stops costing you anything. The attachment for that resource keeps naming it and says it could not be released.
A terminated instance stays in `list-instances` for 2 hours, then drops out of the default list. You can still read it with `get-instance` at any time.
## Using the API [#using-the-api]
```graphql
mutation {
compute {
terminateInstance(input: { instanceUrn: "" }) {
accepted
message
}
}
}
```
## Related [#related]
- [`terminate-instance` reference](/docs/compute/reference/cli#terminate-instance)
- [Instance lifecycle](/docs/compute/instances/lifecycle)
# Create a key pair
Import the public half of an SSH key you already have, or have the platform generate a key pair and save its private key from the one response that carries it.
Create a key pair before you launch an instance. Import a key you already have, or have the platform generate one. Importing is the safer default, because the private key never leaves your computer.
## Before you begin [#before-you-begin]
- A project to create the key pair in. Key pairs belong to one project.
- The `origin` CLI, signed in. See [CLI access](/docs/platform/access/cli).
## Import an existing key [#import-an-existing-key]
1. If you don’t have a key yet, create one locally:
```sh
ssh-keygen -t ed25519 -f ~/.ssh/origin-cloud
```
1. Import its public half. Pass the full OpenSSH public key line:
```sh
origin compute import-key-pair \
--project-urn \
--name my-key \
--public-key "$(cat ~/.ssh/origin-cloud.pub)"
```
A key with an unsupported type, or more than one line, is refused.
1. Verify that the key pair is listed:
```sh
origin compute list-key-pairs --project-urn
```
## Generate a key pair [#generate-a-key-pair]
1. Generate the key pair:
```sh
origin compute generate-key-pair \
--project-urn \
--name my-key
```
The response contains `privateKey`, an `ssh-ed25519` private key in OpenSSH format.
1. Save `privateKey` to a file right away, and restrict its permissions. To do both in one go, generate the key pair and write `privateKey` straight to a file with `jq`, instead of running the command above on its own:
```sh
origin compute generate-key-pair \
--project-urn \
--name my-key \
| jq -r '.. | .privateKey? // empty' > ~/.ssh/origin-cloud
chmod 600 ~/.ssh/origin-cloud
```
The private key is returned only in this response. The platform doesn’t store it and can’t show it again. If you lose it, delete the key pair and create a new one.
1. Verify that the key pair is listed:
```sh
origin compute list-key-pairs --project-urn
```
## Using the API [#using-the-api]
The `importKeyPair` and `generateKeyPair` mutations take the same inputs. Request `privateKey` in the `generateKeyPair` selection, or you can’t get it later:
```graphql
mutation {
compute {
generateKeyPair(input: { projectUrn: "", name: "my-key" }) {
urn
publicKey
privateKey
}
}
}
```
## Next steps [#next-steps]
- [Launch an instance](/docs/compute/instances/launch) with the key pair
## Related [#related]
- [`import-key-pair` reference](/docs/compute/reference/cli#import-key-pair)
- [`generate-key-pair` reference](/docs/compute/reference/cli#generate-key-pair)
- [Key pairs](/docs/compute/key-pairs)
# Key pairs
A key pair is the SSH key you log in to instances with. Learn how the platform uses it at launch and what happens when you delete one.
A key pair is an SSH key registered in a project. Every launch names one, and the platform installs its public half for the instance’s login user. You log in with the matching private key. There is no password login and no shared fallback key: a launch without a key pair is refused.
The following table shows how a key pair gets into an instance.
| From | Step | To |
| --- | --- | --- |
| Imported public key or generated key pair | becomes | Key pair |
| Key pair | named at launch | Instance login user |
| You with the private key | SSH | Instance login user |
## Key concepts [#key-concepts]
| Concept | Meaning |
| --- | --- |
| Imported key pair | You upload the public half of a key you already have. The private key never leaves your machine. Accepted key types are `ssh-ed25519`, `ssh-rsa`, `ssh-dss` and `ecdsa-sha2-nistp256`, `-nistp384` and `-nistp521`. |
| Generated key pair | The platform generates an `ssh-ed25519` key pair and returns the private key in the response, once. The platform stores only the public half, so the private key can never be retrieved again. |
| Login user | The account the public key is installed for. See [Guest environment](/docs/compute/instances/guest-environment). |
## What you can do [#what-you-can-do]
- [Create a key pair](/docs/compute/key-pairs/create), by importing or generating it
- List key pairs with `origin compute list-key-pairs` and read one with `origin compute get-key-pair`
- Delete a key pair with `origin compute delete-key-pair`
Deleting a key pair doesn’t change instances already launched with it. Their login user keeps the public key, and the matching private key still logs in. You can no longer launch new instances with it.
## Related [#related]
- [Launch an instance](/docs/compute/instances/launch)
- [origin compute commands](/docs/compute/reference/cli)
# origin compute commands
Every origin compute command with its flags: instances, instance types, images, image families, key pairs and volume attachments.
This page lists every `origin compute` command. For the options every `origin` command accepts, see [Global options](/docs/platform/reference/cli#global-options).
## launch-instance [#launch-instance]
Launch a new instance.
```sh
origin compute launch-instance [OPTIONS] --project-urn --image-urn --key-pair-urn --instance-type
```
| Option | Required | Description |
| --- | --- | --- |
| `--project-urn ` | yes | URN of the project. |
| `--image-urn ` | yes | Image to use. |
| `--subnet-urn ` | no | Subnet the Instance will belong to. Omit to use the project’s default subnet - lazily created, on first use, in a VPC with an Internet Gateway already attached and a public IP auto-assigned to the instance’s interface. |
| `--key-pair-urn ` | yes | SSH key pair to inject into the guest’s default user. |
| `--instance-type ` | yes | Instance type to launch, e.g. “`gp1.core.2`” - see [`list-instance-types`](#list-instance-types) for the full live catalog. |
| `--volume-backend ` | no | Storage backend for the instance’s volumes. Only `pvs`, the default, is accepted; omit this option. |
| `--boot-volume-size-gib ` | no | Size of the instance’s root disk, in GiB. Omitted takes the image’s own size, which is also the smallest value accepted - a smaller one is refused rather than raised. |
| `--boot-volume-storage-class ` | no | Performance tier for the instance’s root disk, e.g. “`gp1`” - see [`origin storage list-storage-classes`](/docs/storage/reference/cli#list-storage-classes) for the tiers currently on offer. Omitted takes the default. |
| `--security-group-urn ` | no | Security groups to attach to the primary network interface. Repeatable. Omitted defaults to the VPC’s default security group. |
| `--login-user ` | no | The account to create on the guest and inject the key pair into, overriding the image’s default user for this instance. A POSIX username other than `root`. Omitted takes the image’s default; either way the instance reports the result as `loginUser` |
## list-instance-types [#list-instance-types]
List the live catalog of launchable instance types.
```sh
origin compute list-instance-types
```
This command takes no options.
## list-image-families [#list-image-families]
List every image family on offer. A family is a stable name that resolves to the image currently designated for it. `supportEndsAt`, when set, is when upstream support for that release ends; it is advisory and nothing is refused on it. The CLI launches by image URN only; to launch by family, use the `imageFamily` field of the `launchInstance` GraphQL mutation.
```sh
origin compute list-image-families
```
This command takes no options.
## import-key-pair [#import-key-pair]
Import the public half of an SSH key pair you already have, for use when launching instances.
```sh
origin compute import-key-pair --project-urn --name --public-key
```
| Option | Required | Description |
| --- | --- | --- |
| `--project-urn ` | yes | URN of the project. |
| `--name ` | yes | Name for the key pair. |
| `--public-key ` | yes | Full OpenSSH public key line, e.g. `ssh-ed25519 AAAA... comment` |
## generate-key-pair [#generate-key-pair]
Generate an SSH key pair on the platform. The private key is in the response and is never retrievable again - save it immediately.
```sh
origin compute generate-key-pair --project-urn --name
```
| Option | Required | Description |
| --- | --- | --- |
| `--project-urn ` | yes | URN of the project. |
| `--name ` | yes | Name for the key pair. |
## list-key-pairs [#list-key-pairs]
List the key pairs of a project.
```sh
origin compute list-key-pairs --project-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--project-urn ` | yes | URN of the project. |
## get-key-pair [#get-key-pair]
Get a single key pair.
```sh
origin compute get-key-pair --key-pair-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--key-pair-urn ` | yes | URN of the key pair. |
## delete-key-pair [#delete-key-pair]
Delete a key pair.
```sh
origin compute delete-key-pair --key-pair-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--key-pair-urn ` | yes | URN of the key pair. |
## list-instances [#list-instances]
List the instances of a project.
```sh
origin compute list-instances --project-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--project-urn ` | yes | URN of the project. |
## get-instance [#get-instance]
Get one instance, including its volume attachments.
```sh
origin compute get-instance --instance-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--instance-urn ` | yes | URN of the Instance. |
## list-volume-attachments [#list-volume-attachments]
List the attachments that reference a Volume, each naming its Instance. Use it to find which Instance holds a volume that is `INUSE`: the entry whose `id` equals the volume’s `claimRef` (see [`origin storage get-volume`](/docs/storage/reference/cli#get-volume)) is the one holding it, and its `instanceUrn` is the Instance. Normally there is exactly one entry, with status `ATTACHED`; detached attachments are not listed. A volume from another project returns an empty list.
```sh
origin compute list-volume-attachments --project-urn --volume-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--project-urn ` | yes | URN of the project the volume belongs to. |
| `--volume-urn ` | yes | URN of the Volume. |
## start-instance [#start-instance]
Start a stopped Instance.
```sh
origin compute start-instance --instance-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--instance-urn ` | yes | URN of the Instance. |
## stop-instance [#stop-instance]
Stop a running instance. Its network interface and volumes stay with it.
```sh
origin compute stop-instance --instance-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--instance-urn ` | yes | URN of the Instance. |
## change-instance-type [#change-instance-type]
Change a stopped Instance’s type, so it starts again at a different size. The Instance must be stopped. It keeps its identity, its address and its volumes; only the size changes. Growing is checked against the same vCPU quota a launch is. [`list-instance-types`](#list-instance-types) shows what you can change to.
```sh
origin compute change-instance-type --instance-urn --instance-type
```
| Option | Required | Description |
| --- | --- | --- |
| `--instance-urn ` | yes | URN of the Instance. |
| `--instance-type ` | yes | The type to change to, e.g. “`gp1.core.4`”. |
## terminate-instance [#terminate-instance]
Terminate an instance. Its network interface and the volumes its launch created are deleted; volumes you attached yourself are detached and kept.
```sh
origin compute terminate-instance --instance-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--instance-urn ` | yes | URN of the Instance. |
## attach-volume [#attach-volume]
Attach an available volume to an instance, running or stopped. On a running instance the disk is hot-plugged: the attachment reports `ATTACHING` and settles to `ATTACHED` once the guest sees the device. On a stopped instance it appears at the next start.
```sh
origin compute attach-volume [OPTIONS] --instance-urn --volume-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--instance-urn ` | yes | URN of the Instance. |
| `--volume-urn ` | yes | URN of the Volume. |
| `--device-name ` | no | Guest device name (`vda`..`vdz`). Assigned by the platform when omitted. |
## detach-volume [#detach-volume]
Detach a volume from an instance, running or stopped, making it available again. On a running instance the attachment reports `DETACHING` until the guest releases the device; the volume becomes available only after that.
```sh
origin compute detach-volume --instance-urn --volume-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--instance-urn ` | yes | URN of the Instance. |
| `--volume-urn ` | yes | URN of the Volume. |
## create-image [#create-image]
Create an image from a protected snapshot.
```sh
origin compute create-image [OPTIONS] --project-urn --root-device-snapshot-urn --description
```
| Option | Required | Description |
| --- | --- | --- |
| `--project-urn ` | yes | URN of the project. |
| `--root-device-name ` | no | Root device name: a bare virtio target, `vda`.. `vdz` (`vdc` is reserved) - not a `/dev/` path [default: `vda`]. |
| `--root-device-size ` | no | Root device size in GiB [default: 8]. |
| `--root-device-snapshot-urn ` | yes | Root device backing Snapshot. |
| `--default-user ` | no | The account instances launched from this image log in as - the non-root user created at first boot, holding the launch’s SSH key. A POSIX username other than `root`; defaults to `cloud` |
| `--description ` | yes | Description of the Image. |
## list-images [#list-images]
List the images available to a project, your own and platform-provided.
```sh
origin compute list-images --project-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--project-urn ` | yes | URN of the project. |
## get-image [#get-image]
Get one image.
```sh
origin compute get-image --image-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--image-urn ` | yes | URN of the Image. |
## update-image [#update-image]
Update a customer-owned Image’s description - the only mutable field.
```sh
origin compute update-image --image-urn --description
```
| Option | Required | Description |
| --- | --- | --- |
| `--image-urn ` | yes | URN of the Image. |
| `--description ` | yes | New description. |
## delete-image [#delete-image]
Delete a customer-owned Image.
```sh
origin compute delete-image --image-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--image-urn ` | yes | URN of the Image. |
# Compute reference
Complete reference material for Compute - every origin compute command and its options, and every reason an instance can report in statusReason.
These pages list everything of one kind. For explanations, follow the links back to the concept pages.
## Pages [#pages]
- [origin compute commands](/docs/compute/reference/cli): every `origin compute` command with its options.
- [Status reasons](/docs/compute/reference/status-reasons): every text an instance can report in `statusReason`, what it means and what to do.
## Shared reference [#shared-reference]
- [Error codes](/docs/platform/reference/errors) – the error codes every API call can return
- [Limits](/docs/platform/reference/limits) – Compute quotas
- [Global CLI options](/docs/platform/reference/cli#global-options)
# Status reasons
Every text an instance can report in statusReason when it is FAILED or was stopped by the platform, with what each means and what to do next.
An instance’s `statusReason` says why it is in its current status. `get-instance` and `list-instances` return it next to `status`.
It’s set in two cases:
- Every `FAILED` instance carries one.
- A `STOPPED` instance carries one when the platform stopped it because its machine failed. A `STOPPED` instance you stopped yourself, or that shut itself down, carries none.
For every other status it’s `null`, and starting the instance clears it. A reason starts with one of the fixed texts below. Some texts are followed by a colon and a detail, such as a quota refusal you can act on. A reason never contains raw host errors, file paths or machine names. If the reason isn’t enough to act on, contact Origin Cloud support and quote the instance URN.
The texts are listed in the order an instance can meet them: launch, start, stop, and machine failure.
## A volume could not be created [#a-volume-could-not-be-created]
**Text:** `a volume this instance needs could not be created`, optionally followed by `: `
**Status:** `FAILED`
**Meaning:** A volume the launch creates, such as the root disk, could not be created. A detail you can act on is appended, for example `a volume this instance needs could not be created: invalid input on field quota: volume storage quota exceeded`.
**What to do:** For a quota detail, free volume storage or request a higher limit. Then terminate the instance and launch again.
## A volume could not be attached [#a-volume-could-not-be-attached]
**Text:** `a volume this instance needs could not be attached`, optionally followed by `: `
**Status:** `FAILED`
**Meaning:** A volume exists but couldn’t be handed to the instance, for example `a volume this instance needs could not be attached: volume is not available`.
**What to do:** Act on the detail, then start the instance or terminate it.
## The network interface could not be created [#the-network-interface-could-not-be-created]
**Text:** `the network interface this instance needs could not be created`, optionally followed by `: `
**Status:** `FAILED`
**Meaning:** The launch couldn’t create the instance’s network interface. The most common detail is a subnet with no free addresses. The launch call returns the same error.
**What to do:** Terminate the instance. Launch again into a subnet with free addresses. See [VPC addressing](/docs/network/vpcs/addressing).
## The instance could not be placed [#the-instance-could-not-be-placed]
**Text:** `this instance could not be placed on a machine to start on`, optionally followed by `: `
**Status:** `FAILED`
**Meaning:** The instance finished preparing its resources but had no machine to start on, and none could be found. The detail usually names the capacity shortfall, for example `no host has capacity for an instance of this type`.
**What to do:** Start the instance again later, or terminate it and launch again.
## The instance could not be started on its host [#the-instance-could-not-be-started-on-its-host]
**Text:** `the instance could not be started on its host`
**Status:** `FAILED`
**Meaning:** The machine the instance was placed on refused to start it.
**What to do:** Start the instance again, or terminate it.
## The start operation failed [#the-start-operation-failed]
**Text:** `the operation failed (ERR_INSTANCE_START)`
**Status:** `FAILED`
**Meaning:** The host reported an error while carrying out the start.
**What to do:** Start the instance again, or terminate it.
## The stop operation failed [#the-stop-operation-failed]
**Text:** `the operation failed (ERR_INSTANCE_STOP)`
**Status:** `FAILED`
**Meaning:** The host reported an error while carrying out a stop or a termination’s shutdown. The guest may still be running.
**What to do:** Start the instance to return it to the normal lifecycle and stop it again, or terminate it.
## The operation failed [#the-operation-failed]
**Text:** `the operation failed`
**Status:** `FAILED`
**Meaning:** The host reported an error without a classification.
**What to do:** Start the instance again, or terminate it.
## The host did not confirm the start [#the-host-did-not-confirm-the-start]
**Text:** `the instance's host did not confirm that it started`
**Status:** `FAILED`
**Meaning:** The instance’s machine is reachable but didn’t confirm a start, after the platform sent it three times over about 30 minutes. The guest may be running.
**What to do:** Start the instance again, or terminate it.
## The host did not confirm the stop [#the-host-did-not-confirm-the-stop]
**Text:** `the instance's host did not confirm that it stopped`
**Status:** `FAILED`
**Meaning:** The instance’s machine is reachable but didn’t confirm a stop or a termination’s shutdown, after the platform sent it three times over about 30 minutes. The guest may still be running.
**What to do:** Start the instance to return it to the normal lifecycle and stop it again, or terminate it.
## The machine failed [#the-machine-failed]
**Text:** `the machine this instance was running on failed, and the instance went down with it; start it again to bring it back`
**Status:** `STOPPED`
**Meaning:** The machine under the running instance restarted, and the platform proved it. The guest didn’t survive. See [When the machine under an instance fails](/docs/compute/instances/host-failure).
**What to do:** Start the instance when you want it back. A start usually brings it back; check that the guest answers afterwards. If it reads `RUNNING` and `AVAILABLE` but stays unreachable, see [Troubleshoot Compute](/docs/compute/troubleshooting#running-and-available-after-a-machine-failure-but-unreachable).
## The machine was taken out of service [#the-machine-was-taken-out-of-service]
**Text:** `the machine this instance was running on failed and has been taken out of service; the instance went down with it, and starting it again will place it on another machine`
**Status:** `STOPPED`
**Meaning:** The machine under the instance failed and didn’t come back, and the platform took it out of service. See [When the machine under an instance fails](/docs/compute/instances/host-failure).
**What to do:** Start the instance when you want it back. It starts on another machine with its volumes and addresses unchanged.
# Troubleshoot Compute
Fix common Compute problems - failed instances, refused launches and starts, impaired or unknown health, unsynchronized clocks, SSH failures and broken pod networking.
Each section starts from what you see. For the meaning of every `statusReason`, see [Status reasons](/docs/compute/reference/status-reasons).
## Find your symptom [#find-your-symptom]
Entries marked describe what we ran into while testing on 12 October 2026. They are not on docs.origincloud.eu yet.
## Instance status is FAILED [#instance-status-is-failed]
`get-instance` shows `status: FAILED` and a `statusReason`.
The host refused or never confirmed a start or a stop, or a volume, network interface or placement the instance needed failed. `FAILED` doesn’t mean the guest is stopped.
- Read `statusReason` and look it up in [Status reasons](/docs/compute/reference/status-reasons).
- Fix anything the reason names, such as a quota or a full subnet.
- Start the instance with `origin compute start-instance`, or terminate it with `origin compute terminate-instance`. Don’t leave a `FAILED` instance sitting, because it can still hold capacity.
## Launch refused with INSUFFICIENT_CAPACITY [#launch-refused-with-insufficient_capacity]
The launch or start fails with `INSUFFICIENT_CAPACITY` and a message such as `insufficient capacity for instance type gp1.core.16: no host has 16 vCPU and 65536 MiB memory free right now; retry later, …`.
No machine has room for that instance type right now, or no machine serves its kind. This is a refusal, not a fault. Nothing was created.
- Retry the same request in a few minutes.
- Or choose a larger type whose `available` is `true`, or a type of another kind. See [Instance types](/docs/compute/instances/instance-types).
The API message goes on to suggest a smaller type. For `gp1.core.2` there is none.
## Start or change-type refused with PRODUCT_UNAVAILABLE [#start-or-change-type-refused-with-product_unavailable]
`start-instance`, `change-instance-type` or `launch-instance` fails with `PRODUCT_UNAVAILABLE`, naming an instance type or storage class.
The type or class is no longer offered, or isn’t on sale. A stopped instance whose type was withdrawn can’t start as that type.
1. List the types and pick one whose `available` is `true`:
```sh
origin compute list-instance-types
```
1. For a stopped instance, change its type, then start it. See [Change an instance’s type](/docs/compute/instances/change-type).
## GUEST_PRESENT is IMPAIRED [#guest_present-is-impaired]
The instance is `RUNNING`, but `healthChecks` shows `GUEST_PRESENT` as `IMPAIRED` and `availability` as `IMPAIRED`.
The machine carrying the instance is reachable and no longer runs it. Waiting won’t bring it back.
- Stop the instance and wait for `STOPPED`.
- Start it again. It can start on any machine, with its volumes and addresses unchanged.
See [Instance health checks](/docs/compute/instances/health-checks).
## Health checks show INSUFFICIENT_DATA [#health-checks-show-insufficient_data]
Checks read `INSUFFICIENT_DATA` and `availability` reads `UNKNOWN`, often with `HOST_REACHABLE` as `IMPAIRED` first.
The platform has lost contact with the machine carrying the instance, so it can’t observe the instance. It doesn’t know whether the instance is still running. Right after launch, checks also read `INSUFFICIENT_DATA` until the first observation arrives.
- Wait a few minutes. If the machine comes back, the checks return to OK.
- If the machine failed, the platform records the instance as `STOPPED` with a `statusReason`. Start it again. See [When the machine under an instance fails](/docs/compute/instances/host-failure).
- If `HOST_REACHABLE` stays `IMPAIRED`, or the checks stay `INSUFFICIENT_DATA` on a running instance, contact Origin Cloud support. The `SYSTEM` category means there is nothing to fix inside the instance.
## System clock synchronized: no [#system-clock-synchronized-no]
`timedatectl` inside the instance shows `System clock synchronized: no`.
Either the guest isn’t using the platform’s time service, or the physical machine’s own clock isn’t synchronized and the platform is telling the guest not to trust it.
- Check that `NTP service: active` is shown. If it isn’t, enable the guest’s time service with `sudo timedatectl set-ntp true`.
- If you pointed the guest at an external time server, check that the instance has internet access.
- If the guest uses the platform’s time service and the clock stays unsynchronized, contact Origin Cloud support.
See [Guest environment](/docs/compute/instances/guest-environment).
## Can’t connect over SSH [#cant-connect-over-ssh]
`ssh` times out, or fails with `Permission denied (publickey)`.
The wrong user name or key, a security group that doesn’t allow port 22, or an instance with no public address.
- Check the user name. Use the instance’s `loginUser` from `get-instance`, not `root`.
- Check the key. Use the private key of the key pair the instance was launched with.
- Check that a security group on the instance’s network interface allows inbound TCP port 22 from your address. The VPC’s default group does, unless its rules were changed. See [Security groups](/docs/network/traffic-control/security-groups).
- Check that the instance has a public address, either assigned at launch in the default subnet or a floating IP you associated. See [Floating IPs](/docs/network/internet-access/floating-ips).
- Check that the instance is `RUNNING` and its `availability` is `AVAILABLE`.
- If every check passes and you still can’t connect, stop the instance, wait for `STOPPED`, and start it again. If that doesn’t help, contact Origin Cloud support with the instance URN and the time you last connected. The API and the CLI have no reboot operation and no console log to read.
## Running and available after a machine failure, but unreachable [#running-and-available-after-a-machine-failure-but-unreachable]
The instance was `STOPPED` with a machine-failure `statusReason`. You started it, and it now reads `RUNNING` with `availability` `AVAILABLE`, but SSH and every other port time out.
The guest didn’t come back up after the start, although the instance’s status and health checks don’t show it. Moving the instance’s Floating IP off and back doesn’t help.
Query the instance’s CPU use for the last 15 minutes with the `RATE` of `oc_compute_instance_cpu_seconds_total`. See [Query metrics](/docs/observability/query-metrics). A guest that is up uses some CPU; values of `0` throughout mean it isn’t running anything.
1. Stop the instance and wait for `STOPPED`.
1. Start it again and wait for `RUNNING`. Then connect over SSH, or check the CPU metric again.
1. If it’s still unreachable, contact Origin Cloud support. Quote the instance URN, the time of the machine failure, and the time of each start.
## Pod networking broken between cloned instances [#pod-networking-broken-between-cloned-instances]
Instances launched from your own image can’t reach each other over VXLAN. Kubernetes pod networking with VXLAN or Geneve encapsulation fails between nodes, while the nodes reach each other directly.
The instances share one machine-id, inherited from the image. Their VXLAN devices then get the same MAC address and can’t exchange packets.
1. Run `cat /etc/machine-id` on two affected instances. Identical output confirms the cause.
1. On each affected instance, generate a new machine-id and reboot:
```sh
sudo rm -f /etc/machine-id /var/lib/dbus/machine-id
sudo systemd-machine-id-setup
sudo reboot
```
1. Fix the image so new instances don’t inherit it. Clear the machine-id before you snapshot. See [Create an image](/docs/compute/images/create).
## Related [#related]
- [Status reasons](/docs/compute/reference/status-reasons)
- [Error codes](/docs/platform/reference/errors)
- [Troubleshoot storage](/docs/storage/troubleshooting)
- [Troubleshoot networking](/docs/network/troubleshooting)
# Access model
How principals, roles, role assignments and permissions work together, how org-wide and project scopes differ, and how a request is authorized.
Access in Origin Cloud is granted by role assignments. A role assignment gives one principal one built-in role, either across the whole organization or for a single project. Every request is allowed only if one of the caller’s assignments covers the resource and carries the permission the request needs.
## Principals [#principals]
A principal is whoever or whatever is granted access. You refer to a principal by a typed identifier, in the same form whether you assign a role, revoke one, or check a permission.
| Principal | Format | Where to find the ID |
| --- | --- | --- |
| User | `user:` | `userId` in `origin iam current-user`, or the `principal` column of `list-members` |
| Service account | `service_account:` | The `principal` field returned when you create a service account or list them |
Both IDs are UUIDs. A user ID belongs to the person’s account and is the same in every organization they’re a member of.
## Roles [#roles]
A role is a named, fixed set of permissions. Every role is built in: you can assign and revoke them, but you can’t create, change or delete a role. Each role has a short ID such as `roles/owner` and a URN, which is what you pass to role commands, for example `urn:origin:cloud:iam::::tc/role/roles/owner`. The `list-roles` command shows every role with its URN and permissions. For the full catalog, see [Built-in roles](/docs/iam/roles).
## Permissions [#permissions]
A permission allows one action on one kind of resource. Its key has three dotted parts: the service, the resource type and the action, for example `network.vpc.list` or `iam.member.create`. Each API operation requires exactly one permission. When a request is refused, the error names the permission it needed:
```text
Insufficient permissions. This operation requires permission `iam.member.create` on `org/`
```
The `permissions` command lists every permission the platform defines.
## Role assignments and scopes [#role-assignments-and-scopes]
A role assignment links a principal, a role and a scope. The scope is either the whole organization or one project in it.
| Scope | Where the role applies |
| --- | --- |
| Org-wide | The role applies to the organization itself and to every resource in every project of the organization, including projects created later. |
| Project scope | The role applies only to resources inside that one project. It doesn’t apply to the organization itself. |
All IAM operations, such as inviting members, assigning roles and creating service accounts, act on the organization. A project-scoped assignment therefore never allows them, even for `roles/owner`. To let someone manage access, assign the role org-wide. The billing roles must always be assigned org-wide; see [Billing access](/docs/platform/billing/billing-access).
Whoever creates an organization receives `roles/owner` and `roles/billing/administrator` org-wide. Anyone else holds only the roles you assign to them.
## Who can assign a role [#who-can-assign-a-role]
Assigning and revoking roles needs `iam.role.assign` or `iam.role.revoke` on the organization. On top of that, you can only assign or revoke a role whose permissions you hold yourself at the scope of the grant. For an org-wide grant, your org-wide assignments count. For a project-scoped grant, your org-wide assignments and your assignments in that project count. Nobody can use role management to gain access they don’t already have.
This applies to every path that changes a grant:
- [Assigning and revoking a role](/docs/iam/assign-roles).
- [Inviting a member](/docs/iam/manage-members#invite-a-member): you can only invite with a role you could assign. A pending invite is checked again when it’s applied. If the person who sent it can no longer assign the role by then, the invite is dropped.
- [Removing a member](/docs/iam/manage-members#remove-a-member): you must be able to revoke every role the member holds.
A request that would go beyond your own permissions is refused with `FORBIDDEN`. The error names the role and some of the permissions you lack. For example, Owner holds no billing permission, so an Owner can assign a billing role only if it also holds `roles/billing/administrator`. An IAM Editor can’t assign Owner.
## How a request is authorized [#how-a-request-is-authorized]
The following steps show how the platform decides whether to allow a request.
1. The request needs a permission on a resource.
1. The platform finds the principal’s role assignments in the resource’s organization.
1. For each assignment: if it’s org-wide or in the resource’s project, and its role contains the permission, the request is allowed. Otherwise the platform skips the assignment and checks the next one.
1. When no assignments are left, the request is refused with `FORBIDDEN`.
Permissions only add up. There are no deny rules, so holding a role never takes access away. The check runs on every request, so assigning or revoking a role takes effect on the principal’s next request. A refused request fails with the `FORBIDDEN` error.
## Repeated assignments and revocations [#repeated-assignments-and-revocations]
Assigning and revoking are idempotent. Assigning a role that the principal already holds at the same scope, with the same role URN, succeeds and changes nothing. Revoking a role that the principal doesn’t hold at that scope also succeeds and changes nothing.
A revocation matches the role URN and the scope exactly. An org-wide grant needs an org-wide revoke, and a project-scoped grant needs the same project. Use the role URN as it appears in the principal’s grants, because a grant created together with the organization carries the organization ID inside its URN. Don’t assemble that URN yourself: list the principal’s grants with `origin iam principal-grants --org-id --principal ` and copy the role URN of the grant you want to revoke. For the steps, see [Assign and revoke roles](/docs/iam/assign-roles).
## The last owner is protected [#the-last-owner-is-protected]
An organization always keeps at least one principal with an org-wide `roles/owner` assignment. The platform refuses with `CONFLICT` any revocation or member removal that would take the last org-wide owner away, including your own. A project-scoped owner doesn’t count. To hand over ownership, assign `roles/owner` org-wide to the new owner first, then revoke the old grant.
## Related [#related]
- [Built-in roles](/docs/iam/roles)
- [Assign and revoke roles](/docs/iam/assign-roles)
- [Check access](/docs/iam/check-access)
- [Organizations and projects](/docs/platform/organizations)
# Assign and revoke roles
Grant a built-in role to a user or service account org-wide or for one project, and revoke it again at exactly the scope it was granted.
Assign a role to give a user or service account access, and revoke it to take that access away. A change takes effect on the principal’s next request. To give a person access by email instead of by user ID, [invite them](/docs/iam/manage-members#invite-a-member).
## Before you begin [#before-you-begin]
- An org-wide `roles/owner` or `roles/iam/editor` assignment, and every permission of the role you assign or revoke at the scope of the grant. For example, an Owner needs `roles/billing/administrator` as well to assign a billing role. See [Who can assign a role](/docs/iam/access-model#who-can-assign-a-role).
- Your organization ID (``) and, for a project-scoped grant, the project ID (``).
- The principal, in the form `user:` or `service_account:`. `list-members` shows the principal of everyone who already has access. See [Principals](/docs/iam/access-model#principals).
## Assign a role [#assign-a-role]
1. Find the URN of the role you want to assign.
```sh
origin iam list-roles --org-id
```
For the permissions of each role, see [Built-in roles](/docs/iam/roles).
1. Assign the role. Omit `--project-id` for an org-wide grant.
```sh
origin iam assign-role --org-id \
--principal user: \
--role-urn urn:origin:cloud:iam::::tc/role/roles/viewer
```
To limit the grant to one project, add `--project-id `. A project-scoped grant applies only to resources in that project; it never allows IAM operations. See [Role assignments and scopes](/docs/iam/access-model#role-assignments-and-scopes).
1. Verify the grant. The output lists every principal with its role URNs.
```sh
origin iam list-members --org-id
```
Assigning a role the principal already holds at the same scope succeeds and changes nothing. A role URN that isn’t in the built-in catalog is refused with `BAD_REQUEST`. A role with permissions you don’t hold yourself at that scope is refused with `FORBIDDEN`, and so is revoking one.
## Revoke a role [#revoke-a-role]
1. Find the role URN of the grant in the `roleUrns` of the principal in `list-members`. It’s the same URN that `list-roles` shows for the role, for example `urn:origin:cloud:iam::::tc/role/roles/owner`, except for a grant created together with the organization, which carries the organization ID inside its URN. Copy the URN from `list-members` or from `origin iam principal-grants --org-id --principal ` rather than typing it.
```sh
origin iam list-members --org-id
```
1. Revoke the role at the same scope it was assigned with. Omit `--project-id` for an org-wide grant, or pass the same project for a project-scoped one.
```sh
origin iam revoke-role --org-id \
--principal user: \
--role-urn urn:origin:cloud:iam::::tc/role/roles/viewer
```
1. Optionally, run `list-members` again to check that the role URN is gone from the principal.
If the principal holds no grant of that role at that scope, the platform refuses with `NOT_FOUND` and changes nothing. Check the scope: an org-wide grant isn’t revoked by a request that names a project, and the reverse.
If revoking would leave the organization without an org-wide owner, the platform refuses with `CONFLICT`. Assign `roles/owner` org-wide to someone else first. See [The last owner is protected](/docs/iam/access-model#the-last-owner-is-protected).
To take away every role a principal holds in the organization at once, [remove the member](/docs/iam/manage-members#remove-a-member) instead.
## Using the API [#using-the-api]
The `assignRole` and `revokeRole` mutations take the same input. Omit `projectId` for an org-wide grant.
```graphql
mutation {
iam {
assignRole(input: {
orgId: ""
principal: "user:"
roleUrn: "urn:origin:cloud:iam::::tc/role/roles/viewer"
})
}
}
```
## Related [#related]
- [Access model](/docs/iam/access-model)
- [Built-in roles](/docs/iam/roles)
- [`assign-role`](/docs/iam/reference/cli#assign-role) and [`revoke-role`](/docs/iam/reference/cli#revoke-role) commands
- [Audit log](/docs/iam/audit-log) – every assignment and revocation is recorded
# Audit log
Which access changes the audit log records, the fields of each entry, who can read it, and how to page through it with the GraphQL API.
The audit log records changes to access in your organization: who did what, to whom, and when. Entries can’t be changed or deleted through the API. You read the log with the `auditLogEntries` GraphQL query; the CLI has no command for it.
## What’s recorded [#whats-recorded]
The audit log records these seven actions. Each one is recorded when the change succeeds.
| Action | Recorded when | Target |
| --- | --- | --- |
| `iam.role.assign` | A role is assigned, including when an invite grants a role to an existing account | The principal |
| `iam.role.revoke` | A role is revoked | The principal |
| `iam.member.remove` | A member is removed | The principal |
| `iam.org_invite.create` | A pending invite is stored for an email address without an account | The email address |
| `iam.org_invite.revoke` | A pending invite is canceled | The invite ID |
| `iam.service_account.create` | A service account is created | The service account’s principal |
| `iam.service_account.revoke` | A service account is revoked | The service account’s principal |
The audit log doesn’t record organization or project lifecycle changes, resource changes such as launching an instance, or refused requests. Writing an entry never blocks the change itself: if an entry can’t be written, the change still takes effect, so in rare cases an action is missing from the log.
## Entry fields [#entry-fields]
Each entry has these fields.
| Field | Description |
| --- | --- |
| `id` | Unique ID of the entry. |
| `orgId` | The organization the action happened in. |
| `projectId` | The project, for a project-scoped role assignment or revocation. Otherwise `null`. |
| `actor` | The principal that performed the action. |
| `action` | The action key from the table above. |
| `target` | What the action was applied to, as listed in the table above. |
| `outcome` | `SUCCESS` for every recorded action. |
| `occurredAt` | When the action happened, as an RFC 3339 timestamp. |
| `details` | Action-specific context as a JSON string, for example the role URN that was assigned. |
## Who can read it [#who-can-read-it]
Reading the audit log requires the `iam.audit_log.list` permission on the organization. Both `roles/owner` and `roles/viewer` include it, assigned org-wide. See [Built-in roles](/docs/iam/roles).
## Paging through the log [#paging-through-the-log]
`auditLogEntries` returns one page of entries, newest first, with a stable order for entries recorded at the same moment. You can read the whole organization’s log, or narrow it to the entries of one project with `projectId`. Only project-scoped role assignments and revocations carry a project, so a narrowed query leaves out every other action.
The page tells you where you are:
- `entries` – the entries on this page.
- `total` – how many entries match your query across all pages.
- `offset` and `limit` – the window you were actually served.
- `hasMore` – `true` while entries remain beyond this page. When it’s `false`, you’ve read to the end.
`limit` defaults to 100 and is capped at 500. If you ask for more than 500, you get 500, and the `limit` in the response says so. The cap applies to one page only; every entry is reachable by paging. To get the next page, add the served `limit` to `offset` and repeat while `hasMore` is `true`.
The following steps show the paging loop.
1. Request the page with `offset` 0.
1. Process its entries, de-duplicating on `id`.
1. If `hasMore` is `true`, set `offset` to `offset` + `limit`, request the next page and repeat from step 2. If it’s `false`, you’ve read the whole log.
The log is written while you read it. If new entries are recorded while you page through, they’re added at the front and shift older entries back, so an entry can appear on two consecutive pages. No entry is skipped. De-duplicate on `id` if you need each entry exactly once.
```graphql
query {
iam {
auditLogEntries(input: { orgId: "", offset: 0, limit: 100 }) {
entries {
id
actor
action
target
outcome
occurredAt
details
}
total
offset
limit
hasMore
}
}
}
```
## Related [#related]
- [Assign and revoke roles](/docs/iam/assign-roles)
- [Manage organization members](/docs/iam/manage-members)
- [Use service accounts](/docs/iam/service-accounts)
- [API access](/docs/platform/access/api)
# Check access
Look up who you are and which roles you hold, list the platform's permissions, and check whether a principal has a permission on a resource.
You can check access before you act instead of handling a permission error afterward. This is useful in automation that needs to know whether a call will succeed, and when you investigate why a request was refused.
## Before you begin [#before-you-begin]
- To see your own identity, grants and the list of permissions: any signed-in user or service account.
- To list another principal’s roles: an org-wide `roles/owner` or `roles/viewer` assignment.
- To check a permission with `has-permission`: `roles/owner` that covers the resource you check.
## Check who you are [#check-who-you-are]
Show the signed-in user. The `userId` is what others use in `user:` to grant you a role.
```sh
origin iam current-user
```
Example output (illustrative):
```json
{
"iam": {
"currentUser": {
"userId": "3f6e1c2a-8b4d-4e5f-9a1b-2c3d4e5f6a7b",
"firstName": "Jane",
"lastName": "Doe",
"enabled": true,
"email": "jane@example.com",
"emailVerified": true
}
}
}
```
## List your own role assignments [#list-your-own-role-assignments]
List every role assignment you hold, across all organizations you belong to. A `projectId` of `null` means the assignment is org-wide.
```sh
origin iam current-user-grants
```
## List another principal’s roles [#list-another-principals-roles]
List every member of the organization with its role URNs, and find the principal in the output.
```sh
origin iam list-members --org-id
```
To see each assignment’s project scope, list the principal’s grants. Each grant shows its project scope:
```sh
origin iam principal-grants --org-id --principal
```
In the API, the `orgRoleAssignments` query returns the same scopes for the whole organization. See [Manage organization members](/docs/iam/manage-members).
## Find a permission key [#find-a-permission-key]
List every permission the platform defines, with its service, resource type and action.
```sh
origin iam permissions
```
For the permissions each role grants, see [Built-in roles](/docs/iam/roles).
## Check a permission on a resource [#check-a-permission-on-a-resource]
1. Get the URN of the resource you want to check. Every resource returns its URN in its `urn` field.
1. Check whether the principal holds the permission on that resource.
```sh
origin iam has-permission \
--principal service_account: \
--permission-key compute.instance.launch \
--on-resource-urn
```
1. Read the result: `true` means a request needing that permission on that resource is allowed; `false` means it would be refused.
The check applies the same rules as a real request, including project scope. See [How a request is authorized](/docs/iam/access-model#how-a-request-is-authorized).
## Using the API [#using-the-api]
The queries are `currentUser`, `currentUserGrants`, `orgMembers`, `orgRoleAssignments`, `permissions` and `hasPermission`, all in the `iam` namespace.
```graphql
query {
iam {
hasPermission(input: {
principal: "user:"
permissionKey: "network.vpc.create"
onResourceUrn: ""
})
}
}
```
## Related [#related]
- [Access model](/docs/iam/access-model)
- [Built-in roles](/docs/iam/roles)
- [`origin iam` commands](/docs/iam/reference/cli)
# What is Origin Cloud IAM?
IAM controls who can do what in your Origin Cloud organization. Learn how principals, roles, role assignments and permissions fit together.
IAM (Identity and Access Management) controls who can do what in your organization. You give people and automation access by assigning them built-in roles, either across the whole organization or for one project. Every API request is checked against those assignments, so you can also ask in advance whether a request will be allowed.
A principal is a user or a service account. A role assignment gives a principal one role, either org-wide or for a single project. The role is a fixed set of permissions, and each permission allows one action, such as `compute.instance.launch`, on resources inside the assignment's scope. For the details, see [Access model](/docs/iam/access-model).
## Features [#features]
- **Built-in roles**: Owner, Viewer, IAM Editor and three billing roles, each with a fixed set of permissions. See [Built-in roles](/docs/iam/roles).
- **Role assignments**: Grant a role to a user or service account org-wide or for one project, and revoke it again. See [Assign and revoke roles](/docs/iam/assign-roles).
- **Organization members**: Invite people by email, list who has access, and remove a member's access in one step. See [Manage organization members](/docs/iam/manage-members).
- **Service accounts**: Non-interactive credentials for CI pipelines, scripts and infrastructure-as-code tools, with their own principal and roles. See [Service accounts](/docs/iam/service-accounts).
- **Access checks**: Look up your own grants, list available permissions, and check whether a principal holds a permission on a resource. See [Check access](/docs/iam/check-access).
- **Audit log**: A record of who changed access in your organization and when. See [Audit log](/docs/iam/audit-log).
## Ways to access IAM [#ways-to-access-iam]
- **CLI**: The `origin iam` command group. See [CLI access](/docs/platform/access/cli) to install and sign in, and [origin iam commands](/docs/iam/reference/cli) for every command.
- **GraphQL API**: IAM queries and mutations live under the `iam` namespace of the API. See [API access](/docs/platform/access/api) and the [IAM reference](/docs/iam/reference) for the list of operations.
## Limitations [#limitations]
- Custom roles aren't supported. You can assign and revoke the built-in roles only.
- Groups aren't principals. The API lists three built-in groups by name and description, but you can't add members to a group or assign a role to one.
- Role assignments are unconditional. You can't restrict a grant to a time window or an extra attribute check.
- A service account's access is the union of its roles. You can't narrow one credential to a subset of what its roles allow.
- Service accounts authenticate against the platform's own identity provider only. Federation with an external identity provider isn't supported.
For quotas, see [Limits](/docs/platform/reference/limits).
## Related [#related]
- [Organizations and projects](/docs/platform/organizations): the scopes that role assignments apply to
- [Billing access](/docs/platform/billing/billing-access): who can see and change billing accounts
- [CLI access](/docs/platform/access/cli): log in with `origin id login`
## Next steps [#next-steps]
- Read the [Access model](/docs/iam/access-model) to understand scopes and permissions.
- [Invite a member](/docs/iam/manage-members) to your organization.
- [Create a service account](/docs/iam/service-accounts) for automation.
# Manage organization members
Invite people to your organization by email, list members and pending invites, remove a member's access, and cancel an invite before it applies.
A member is any principal with at least one role assignment in your organization. You add people by email with an invite, which grants them one role org-wide. To change the roles of an existing member, [assign and revoke roles](/docs/iam/assign-roles).
## Before you begin [#before-you-begin]
- To invite, remove or cancel an invite: an org-wide `roles/owner` assignment. You can only invite with a role you could assign yourself, and only remove a member whose every role you could revoke. See [Who can assign a role](/docs/iam/access-model#who-can-assign-a-role).
- To list members and invites: an org-wide `roles/owner`, `roles/viewer` or `roles/iam/editor` assignment.
- Your organization ID (``).
## Invite a member [#invite-a-member]
1. Find the URN of the role the new member should get with `list-roles`. See [Built-in roles](/docs/iam/roles).
1. Send the invite:
```sh
origin iam invite-member --org-id \
--email jane@example.com \
--role-urn urn:origin:cloud:iam::::tc/role/roles/viewer
```
- Account exists: the role is granted org-wide immediately. There’s no separate step to accept.
- No account yet: the invite is stored as pending. It’s applied the first time that address signs up and signs in to the console, or reads its own identity with `origin iam current-user`. If by then you can no longer assign the role yourself, the invite is dropped instead.
1. Verify the invite. An existing account appears in the member list; a pending invite appears in the invite list.
```sh
origin iam list-members --org-id
origin iam list-invites --org-id
```
Invites are org-wide only. To give someone access to a single project, ask them to sign up and send you the `userId` that `origin iam current-user` shows them. Then assign a project-scoped role to `user:`.
## List members and invites [#list-members-and-invites]
- `list-members` shows every principal with an active role assignment, at any scope, with all of its role URNs. For users, it includes the name and email address where the platform can resolve them. Service accounts with roles appear here too.
- `principal-grants` shows one principal’s role assignments, each with its project scope.
- `list-invites` shows pending invites: the ID, email address, role URN, who invited them and when. An invite disappears from the list once it’s applied or canceled.
## Remove a member [#remove-a-member]
Removing a member revokes every role the principal holds in the organization, org-wide and in every project. To take away a single role, [revoke the role](/docs/iam/assign-roles#revoke-a-role) instead.
1. Find the member’s principal in the output of `list-members`.
1. Remove the member.
```sh
origin iam remove-member --org-id --principal user:
```
1. Run `list-members` again and check that the principal is gone.
Removing a principal that holds no roles succeeds and changes nothing. If the member is the organization’s last org-wide owner, the platform refuses with `CONFLICT` and removes nothing. See [The last owner is protected](/docs/iam/access-model#the-last-owner-is-protected). If the member holds a role you couldn’t revoke yourself, such as a billing role when you hold none, the platform refuses with `FORBIDDEN` and removes nothing.
## Cancel a pending invite [#cancel-a-pending-invite]
`remove-member` acts only on role assignments, so it doesn’t cancel a pending invite.
1. Find the invite’s ID with `list-invites`.
1. Cancel the invite.
```sh
origin iam revoke-invite --org-id --invite-id
```
1. Run `list-invites` again and check that the invite is gone.
## Using the API [#using-the-api]
The mutations are `inviteMember`, `removeMember` and `revokeInvite`; the queries are `orgMembers` and `orgInvites`, all in the `iam` namespace. `orgRoleAssignments` returns the same data as `orgMembers` with one entry per assignment, including its project scope and when it was created. For the full list, see the [IAM reference](/docs/iam/reference).
```graphql
mutation {
iam {
inviteMember(input: {
orgId: ""
email: "jane@example.com"
roleUrn: "urn:origin:cloud:iam::::tc/role/roles/viewer"
})
}
}
```
## Related [#related]
- [Assign and revoke roles](/docs/iam/assign-roles)
- [Access model](/docs/iam/access-model)
- [Organizations](/docs/platform/organizations)
- [Audit log](/docs/iam/audit-log) – invites, cancellations and removals are recorded
# origin iam commands
Every origin iam command with its flags: members, invites, service accounts, role assignments and permission checks.
This page lists every `origin iam` command. Logging in is `origin id login`; see [Use the CLI](/docs/platform/access/cli).
## invite-member [#invite-member]
Invite a person to an org by email. Grants access immediately if they already have an account; otherwise stores a pending invite applied automatically the first time they authenticate.
```sh
origin iam invite-member --org-id --email --role-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--org-id ` | yes | ID of the organisation. |
| `--email ` | yes | Email address to invite. |
| `--role-urn ` | yes | URN of the built-in role to grant once accepted. |
## remove-member [#remove-member]
Remove a member’s access to an org - revokes every role they hold in it, at every project scope.
```sh
origin iam remove-member --org-id --principal
```
| Option | Required | Description |
| --- | --- | --- |
| `--org-id ` | yes | ID of the organisation. |
| `--principal ` | yes | The principal to remove, e.g. `user:` |
## revoke-invite [#revoke-invite]
Cancel a pending invite before it’s been accepted.
```sh
origin iam revoke-invite --org-id --invite-id
```
| Option | Required | Description |
| --- | --- | --- |
| `--org-id ` | yes | ID of the organisation. |
| `--invite-id ` | yes | ID of the invite to revoke (see [`list-invites`](#list-invites)) |
## list-members [#list-members]
List every principal with an active role assignment on an org.
```sh
origin iam list-members --org-id
```
| Option | Required | Description |
| --- | --- | --- |
| `--org-id ` | yes | ID of the organisation. |
## list-invites [#list-invites]
List pending (not yet accepted) invites for an org.
```sh
origin iam list-invites --org-id
```
| Option | Required | Description |
| --- | --- | --- |
| `--org-id ` | yes | ID of the organisation. |
## create-service-account [#create-service-account]
Create a service account for an organization. The response contains an OAuth client ID and client secret for the client-credentials grant; the secret is shown once, so store it now. The service account starts with no roles; grant it access with [`assign-role`](#assign-role).
```sh
origin iam create-service-account --org-id --name
```
| Option | Required | Description |
| --- | --- | --- |
| `--org-id ` | yes | ID of the organisation. |
| `--name ` | yes | Display name for the service account. |
## revoke-service-account [#revoke-service-account]
Revoke a service account. Its credential stops working immediately: every request for a new access token is refused. An access token issued before the revocation stays valid until it expires. Its role assignments are kept; remove them with [`revoke-role`](#revoke-role). See [Service accounts](/docs/iam/service-accounts).
```sh
origin iam revoke-service-account --org-id --service-account-id
```
| Option | Required | Description |
| --- | --- | --- |
| `--org-id ` | yes | ID of the organisation. |
| `--service-account-id ` | yes | ID of the service account to revoke (see [`list-service-accounts`](#list-service-accounts)) |
## list-service-accounts [#list-service-accounts]
List every service account (active or revoked) created for an org.
```sh
origin iam list-service-accounts --org-id
```
| Option | Required | Description |
| --- | --- | --- |
| `--org-id ` | yes | ID of the organisation. |
## assign-role [#assign-role]
Assign a built-in role to a principal, org-wide or project-scoped.
```sh
origin iam assign-role [OPTIONS] --org-id --principal --role-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--org-id ` | yes | ID of the organisation. |
| `--project-id ` | no | Narrows the assignment to a single project. Omit for an org-wide grant. |
| `--principal ` | yes | The principal to grant the role to, e.g. `user:` |
| `--role-urn ` | yes | URN of the built-in role to assign. |
## revoke-role [#revoke-role]
Revoke a previously assigned role from a principal.
```sh
origin iam revoke-role [OPTIONS] --org-id --principal --role-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--org-id ` | yes | ID of the organisation. |
| `--project-id ` | no | Must match the scope (org-wide vs. the given project) the role was originally assigned with. |
| `--principal ` | yes | The principal to revoke the role from, e.g. `user:` |
| `--role-urn ` | yes | URN of the role to revoke. |
## current-user [#current-user]
Show the currently authenticated user.
```sh
origin iam current-user
```
This command takes no options.
## current-user-grants [#current-user-grants]
List the currently authenticated user’s role grants.
```sh
origin iam current-user-grants
```
This command takes no options.
## principal-grants [#principal-grants]
List every role a principal holds in an org, with each grant’s project scope.
```sh
origin iam principal-grants --org-id --principal
```
| Option | Required | Description |
| --- | --- | --- |
| `--org-id ` | yes | ID of the organisation. |
| `--principal ` | yes | The principal to look up, e.g. `user:` |
## list-roles [#list-roles]
List the built-in roles available in an organization.
```sh
origin iam list-roles --org-id
```
| Option | Required | Description |
| --- | --- | --- |
| `--org-id ` | yes | ID of the organisation. |
## get-role [#get-role]
Get a single built-in role and its permissions.
```sh
origin iam get-role --role-urn
```
| Option | Required | Description |
| --- | --- | --- |
| `--role-urn ` | yes | URN of the role. |
## permissions [#permissions]
List every permission the platform knows about.
```sh
origin iam permissions
```
This command takes no options.
## has-permission [#has-permission]
Check whether a principal has a given permission on a resource.
```sh
origin iam has-permission --on-resource-urn --principal --permission-key
```
| Option | Required | Description |
| --- | --- | --- |
| `--on-resource-urn ` | yes | URN of the resource to check the permission against. |
| `--principal ` | yes | The principal to check, e.g. `user:` |
| `--permission-key ` | yes | Permission key to check, e.g. `network.vpc.list` |
# IAM reference
Where to find every origin iam command and built-in role, and a one-line summary of each IAM query and mutation in the GraphQL API.
Look up exact commands, roles and API operations here. For how IAM works, see [Access model](/docs/iam/access-model).
## Reference pages [#reference-pages]
| Page | What it lists |
| --- | --- |
| [CLI commands](/docs/iam/reference/cli) | Every `origin iam` command with its options. See [`origin iam` commands](/docs/iam/reference/cli). |
| [Built-in roles](/docs/iam/roles) | Every role with its URN and permissions. See [Built-in roles](/docs/iam/roles). |
| [Errors](/docs/platform/reference/errors) | Error codes shared by every API operation. See [Errors](/docs/platform/reference/errors). |
## GraphQL queries [#graphql-queries]
All queries are fields of the `iam` namespace of the query root.
| Query | Returns |
| --- | --- |
| `currentUser` | The signed-in user. |
| `currentUserGrants` | Every role assignment the caller holds, in all organizations. |
| `principalGrants` | Every role assignment one principal holds in the organization, with its scope and creation time. Needs `iam.member.list`, like `orgRoleAssignments`. |
| `roles` | Every built-in role with its permissions. |
| `role` | One built-in role by the URN `roles` lists. Needs no permission. |
| `groups` | The three built-in groups, by name and description. Groups aren’t principals and can’t hold roles. |
| `group` | One built-in group by URN, with your organization ID in it: `urn:origin:cloud:iam::::tc/group/`. |
| `permissions` | Every permission the platform defines. |
| `hasPermission` | Whether a principal holds a permission on a resource. |
| `orgMembers` | Every principal with a role assignment in the organization, with its role URNs. |
| `orgRoleAssignments` | Every role assignment in the organization, with its scope and creation time. |
| `orgInvites` | Pending invites in the organization. |
| `serviceAccounts` | Every service account in the organization, active or revoked, without secrets. |
| `auditLogEntries` | One page of the organization’s audit log. See [Audit log](/docs/iam/audit-log). |
## GraphQL mutations [#graphql-mutations]
All mutations are fields of the `iam` namespace of the mutation root.
| Mutation | Effect |
| --- | --- |
| `assignRole` | Assigns a built-in role to a principal, org-wide or for one project. Only a role whose permissions you hold yourself at that scope. |
| `revokeRole` | Revokes one role from a principal at exactly the given scope. Only a role whose permissions you hold yourself at that scope. |
| `inviteMember` | Invites a person by email with one org-wide role, which you must be able to assign. |
| `removeMember` | Revokes every role a principal holds in the organization, if you could revoke each of them. |
| `revokeInvite` | Cancels a pending invite. |
| `createServiceAccount` | Creates a service account and returns its client ID and one-time client secret. |
| `revokeServiceAccount` | Disables a service account’s credential. |
## Example: list one principal’s grants [#example-list-one-principals-grants]
`principalGrants` takes its arguments in an `input` object with `orgId` and `principal`. This form replaced a bare `principal` argument on 12 October 2026, without a deprecation period. A grant whose `projectId` is `null` is org-wide.
```graphql
query {
iam {
principalGrants(input: {
orgId: ""
principal: "user:"
}) {
urn
projectId
roles {
roleUrn
}
createdAt
createdBy
}
}
}
```
The CLI equivalent is `origin iam principal-grants --org-id --principal `.
# Built-in roles
Every built-in IAM role with its ID, URN, what it's for and the exact permissions it grants, including the billing roles that Owner doesn't include.
Origin Cloud has six built-in roles. You can’t create your own. Each section lists the role’s ID, the URN you pass to role commands, where you can assign it, and every permission it grants. Permission keys have the form `..`; the tables group them by `.`. For how roles, scopes and permissions work together, see [Access model](/docs/iam/access-model).
| ID | Name | For |
| --- | --- | --- |
| [`roles/owner`](#rolesowner) | Owner | Full control of the organization, except billing accounts |
| [`roles/viewer`](#rolesviewer) | Viewer | Read-only access to everything Owner can change |
| [`roles/iam/editor`](#rolesiameditor) | IAM Editor | Assigning and revoking roles within its own permissions |
| [`roles/billing/administrator`](#rolesbillingadministrator) | Billing Account Administrator | Full control of billing accounts |
| [`roles/billing/user`](#rolesbillinguser) | Billing Account User | Billing accounts without deleting them |
| [`roles/billing/viewer`](#rolesbillingviewer) | Billing Account Viewer | Read-only access to billing accounts |
## roles/owner [#rolesowner]
Full control of the organization’s projects, resources and access. Owner doesn’t include any billing account permission: an Owner can switch which billing account a project is charged to (`admin.project.attach`) and manage spend limits, but can’t view, create, change or delete a billing account. For that, assign a billing role; see [Billing access](/docs/platform/billing/billing-access).
**URN:** `urn:origin:cloud:iam::::tc/role/roles/owner`
**Scope:** org-wide or one project. Only an org-wide Owner can manage members and service accounts. Because Owner holds no billing permission, an Owner can’t assign or revoke the billing roles unless it also holds `roles/billing/administrator`.
| Resource | Actions |
| --- | --- |
| `admin.organisation` | `get`, `list`, `update`, `create`, `delete` |
| `admin.project` | `get`, `list`, `update`, `create`, `delete`, `attach` |
| `admin.resource_quota` | `get`, `update` |
| `admin.spend_limit` | `get`, `update` |
| `admin.support_case` | `list`, `get`, `create`, `update` |
| `admin.usage` | `list` |
| `compute.image` | `get`, `list`, `create`, `delete`, `update` |
| `compute.instance` | `get`, `list`, `update`, `launch`, `terminate`, `start`, `stop`, `attach`, `detach` |
| `compute.key_pair` | `get`, `list`, `create`, `delete` |
| `iam.audit_log` | `list` |
| `iam.group` | `get`, `list`, `update`, `create`, `delete` |
| `iam.member` | `list`, `create`, `revoke` |
| `iam.permission` | `query` |
| `iam.role` | `get`, `list`, `update`, `create`, `delete`, `assign`, `revoke` |
| `iam.service_account` | `list`, `create`, `revoke` |
| `network.acl` | `get`, `list`, `create`, `update`, `delete` |
| `network.dns_policy` | `get`, `list`, `create`, `update`, `set_default`, `delete`, `attach` |
| `network.floating_ip` | `get`, `list`, `create`, `attach`, `detach`, `delete` |
| `network.interface` | `get`, `list`, `create`, `delete`, `attach` |
| `network.internet_gateway` | `get`, `attach`, `detach` |
| `network.nat_gateway` | `get`, `list`, `create`, `delete` |
| `network.route_table` | `get`, `list`, `create`, `update`, `delete` |
| `network.security_group` | `get`, `list`, `create`, `update`, `delete` |
| `network.subnet` | `get`, `list`, `create`, `update`, `delete` |
| `network.vpc` | `get`, `list`, `create`, `delete` |
| `observability.metric` | `get` |
| `pvs.snapshot` | `get`, `list`, `create`, `delete`, `update`, `protect`, `unprotect` |
| `pvs.volume` | `get`, `list`, `create`, `delete`, `update` |
Some keys are reserved: no operation uses them yet. Built-in roles and groups can’t be created, changed or deleted, so the `create`, `update` and `delete` actions on `iam.role` and `iam.group` allow nothing today.
## roles/viewer [#rolesviewer]
Read-only access: every `get` and `list` permission that Owner holds. A Viewer can list members, pending invites, service accounts and the audit log, but can’t change anything. Viewer includes no billing account permission.
**URN:** `urn:origin:cloud:iam::::tc/role/roles/viewer`
**Scope:** org-wide or one project.
| Resource | Actions |
| --- | --- |
| `admin.organisation` | `get`, `list` |
| `admin.project` | `get`, `list` |
| `admin.resource_quota` | `get` |
| `admin.spend_limit` | `get` |
| `admin.support_case` | `list`, `get` |
| `admin.usage` | `list` |
| `compute.image` | `get`, `list` |
| `compute.instance` | `get`, `list` |
| `compute.key_pair` | `get`, `list` |
| `iam.audit_log` | `list` |
| `iam.group` | `get`, `list` |
| `iam.member` | `list` |
| `iam.role` | `get`, `list` |
| `iam.service_account` | `list` |
| `network.acl` | `get`, `list` |
| `network.dns_policy` | `get`, `list` |
| `network.floating_ip` | `get`, `list` |
| `network.interface` | `get`, `list` |
| `network.internet_gateway` | `get` |
| `network.nat_gateway` | `get`, `list` |
| `network.route_table` | `get`, `list` |
| `network.security_group` | `get`, `list` |
| `network.subnet` | `get`, `list` |
| `network.vpc` | `get`, `list` |
| `observability.metric` | `get` |
| `pvs.snapshot` | `get`, `list` |
| `pvs.volume` | `get`, `list` |
## roles/iam/editor [#rolesiameditor]
Lets a principal list members and roles, and assign and revoke roles in the organization. An IAM Editor can’t invite or remove members or manage service accounts; those need Owner.
An IAM Editor can only hand out what it already has. Like every principal, it can assign or revoke a role only if it holds every permission of that role itself at the scope of the grant; see [Who can assign a role](/docs/iam/access-model#who-can-assign-a-role). With IAM Editor alone, that is IAM Editor itself. To let it assign Viewer as well, assign it Viewer too. An IAM Editor can never make anyone an Owner, itself included.
**URN:** `urn:origin:cloud:iam::::tc/role/roles/iam/editor`
**Scope:** org-wide. Role operations act on the organization, so a project-scoped IAM Editor can’t use them.
| Resource | Actions |
| --- | --- |
| `iam.member` | `list` |
| `iam.role` | `get`, `list`, `assign`, `revoke` |
## roles/billing/administrator [#rolesbillingadministrator]
Full control of the organization’s billing accounts: view, create, update and delete them. Whoever creates an organization holds this role org-wide.
**URN:** `urn:origin:cloud:iam::::tc/role/roles/billing/administrator`
**Scope:** org-wide only. Assign it without a project.
| Resource | Actions |
| --- | --- |
| `admin.billing_account` | `get`, `list`, `create`, `update`, `delete` |
## roles/billing/user [#rolesbillinguser]
Everything the Billing Account Administrator can do, except deleting a billing account.
**URN:** `urn:origin:cloud:iam::::tc/role/roles/billing/user`
**Scope:** org-wide only. Assign it without a project.
| Resource | Actions |
| --- | --- |
| `admin.billing_account` | `get`, `list`, `create`, `update` |
## roles/billing/viewer [#rolesbillingviewer]
Read-only access to the organization’s billing accounts.
**URN:** `urn:origin:cloud:iam::::tc/role/roles/billing/viewer`
**Scope:** org-wide only. Assign it without a project.
| Resource | Actions |
| --- | --- |
| `admin.billing_account` | `get`, `list` |
## Related [#related]
- [Access model](/docs/iam/access-model)
- [Assign and revoke roles](/docs/iam/assign-roles)
- [Billing access](/docs/platform/billing/billing-access)
- [`list-roles`](/docs/iam/reference/cli#list-roles) and [`permissions`](/docs/iam/reference/cli#permissions) commands
# Use service accounts
Create a service account for CI and scripts, exchange its client ID and secret for an access token, grant it roles, and revoke it.
A service account is a non-interactive credential for automation such as CI pipelines, scripts and infrastructure-as-code tools. It belongs to one organization and acts as its own principal, `service_account:`. Its access is checked exactly like a user’s: it can do what its role assignments allow, and nothing else.
A service account authenticates with an OAuth 2.0 client ID and client secret, using the client credentials grant against the platform’s identity provider. The resulting access token is sent to the API like a user’s.
## Before you begin [#before-you-begin]
- To create or revoke a service account: an org-wide `roles/owner` assignment.
- To list service accounts: an org-wide `roles/owner` or `roles/viewer` assignment.
- Your organization ID (``).
## Create a service account [#create-a-service-account]
1. Create the service account with a name that tells you what uses it.
```sh
origin iam create-service-account --org-id --name ci-deploy
```
The output contains the service account’s `id`, its `principal`, and the credential: `clientId` and `clientSecret`.
The client secret is shown only once. Store it in your secret manager now. No API returns it again; if you lose it, create a new service account.
1. Grant the service account the roles it needs. A new service account holds no roles and can’t do anything until you assign one. Use the `principal` from the previous step.
```sh
origin iam assign-role --org-id \
--project-id