> ## Documentation Index > Fetch the complete documentation index at: https://docs.storiza.store/llms.txt > Use this file to discover all available pages before exploring further. # Run a shell command inside a VPS via the QEMU guest agent > Runs one command inside the guest as root and waits for it to finish, returning stdout and the exit code. Goes through the QEMU guest agent, not SSH, so it works without network access to the VPS — but it needs the agent to be installed and answering, which it will not be while the machine is still booting or if the image never had it. On Linux the command runs through `/bin/sh -c`; on Windows it runs through PowerShell (`powershell.exe -EncodedCommand`), where the exit code is 0 or 1. Pipes and redirection work on both. Output is capped; redirect to a file and fetch it in pieces if you need more than that. **This is root (SYSTEM on Windows) on the machine.** It is owner-only — a share token cannot reach it — and every call is audit-logged with the command that ran. **Required API key permission:** `vps:write` ## OpenAPI ````yaml /openapi.json post /vps/{vmId}/execute openapi: 3.0.0 info: title: Storiza API version: '1.0' description: Manage Storiza servers, apps and subscriptions programmatically. servers: - url: https://api.storiza.store security: - bearerAuth: [] tags: - name: Servers description: Create, order, renew and upgrade VPS servers, and read their details. - name: Server power & commands description: >- Start, stop, reboot and force-stop a server, check its status and run commands on it. - name: Server settings description: >- Rename a server, reinstall its operating system and follow its installation. - name: Server firewall description: Turn a server's firewall on or off and manage its rules. - name: Server metrics description: CPU, memory, disk and network usage, now and over time. - name: Server backups description: Order the backup add-on, and take, list and delete backups. - name: Server snapshots description: Take, list and delete snapshots of a server. - name: Server sharing description: A share link that lets someone else open the server. - name: Server catalog description: >- Plans, operating systems, categories, datacenters and backup plans. Public — no key needed. - name: Apps description: >- Deploy, order, renew and configure apps — game servers, databases and bots. - name: App lifecycle & console description: >- Start, stop, restart and kill an app, read its output and metrics, and send it commands. - name: App files description: >- Read, write, move and delete the files in an app's volume, and its SFTP access. - name: App backups description: Back up an app, download a backup, and restore from one. - name: App domains description: Your own domains for an app, and their DNS verification. - name: App groups description: Private networks that let your apps reach each other by hostname. - name: App catalog description: Templates, plans and locations for apps. - name: Subscriptions description: What you pay for, how often it renews, and stopping or resuming it. - name: Payments description: >- Follow a payment after an order, and the methods and currencies you can pay with. - name: Account description: Your profile, and a summary of everything you own. - name: SSH keys description: Public keys you can install on new Linux servers. paths: /vps/{vmId}/execute: post: tags: - Server power & commands summary: Run a shell command inside a VPS via the QEMU guest agent description: >- Runs one command inside the guest as root and waits for it to finish, returning stdout and the exit code. Goes through the QEMU guest agent, not SSH, so it works without network access to the VPS — but it needs the agent to be installed and answering, which it will not be while the machine is still booting or if the image never had it. On Linux the command runs through `/bin/sh -c`; on Windows it runs through PowerShell (`powershell.exe -EncodedCommand`), where the exit code is 0 or 1. Pipes and redirection work on both. Output is capped; redirect to a file and fetch it in pieces if you need more than that. **This is root (SYSTEM on Windows) on the machine.** It is owner-only — a share token cannot reach it — and every call is audit-logged with the command that ran. **Required API key permission:** `vps:write` parameters: - schema: type: string format: uuid required: true name: vmId in: path requestBody: content: application/json: schema: type: object properties: command: type: string minLength: 1 maxLength: 4000 timeoutMs: type: integer minimum: 1000 maximum: 300000 default: 30000 required: - command responses: '200': description: Command executed content: application/json: schema: type: object properties: success: type: boolean enum: - true message: type: string enum: - Command executed data: type: object properties: exitCode: type: number stdout: type: string truncated: type: boolean required: - exitCode - stdout - truncated required: - success - message - data '400': description: >- VPS must be running to execute a command | This VPS has been suspended due to abuse and cannot be managed | The QEMU guest agent is not responding — the VPS may still be booting, or the agent may not be installed | Failed to run the command content: application/json: schema: type: object properties: success: type: boolean enum: - false type: type: string code: type: string error: type: string details: nullable: true required: - success - type - code - error examples: vpsNotActive: summary: VPS must be running to execute a command value: success: false type: API code: VPS_NOT_ACTIVE error: VPS must be running to execute a command vpsSuspended: summary: >- This VPS has been suspended due to abuse and cannot be managed value: success: false type: API code: VPS_SUSPENDED error: >- This VPS has been suspended due to abuse and cannot be managed guestAgentUnavailable: summary: >- The QEMU guest agent is not responding — the VPS may still be booting, or the agent may not be installed value: success: false type: API code: GUEST_AGENT_UNAVAILABLE error: >- The QEMU guest agent is not responding — the VPS may still be booting, or the agent may not be installed executionFailed: summary: Failed to run the command value: success: false type: API code: EXECUTION_FAILED error: Failed to run the command '401': description: >- Authentication required | Authentication required: use session or shareToken content: application/json: schema: type: object properties: success: type: boolean enum: - false type: type: string code: type: string error: type: string details: nullable: true required: - success - type - code - error examples: authenticationRequired: summary: Authentication required value: success: false type: API code: AUTHENTICATION_ERROR error: Authentication required vpsAuthenticationRequired: summary: 'Authentication required: use session or shareToken' value: success: false type: API code: AUTHENTICATION_ERROR error: 'Authentication required: use session or shareToken' '403': description: >- This resource is not running | This resource has no subscription | Renew this resource's subscription to use it again | Account is banned | Account is suspended | Insufficient permissions | A share token cannot run commands on a VPS content: application/json: schema: type: object properties: success: type: boolean enum: - false type: type: string code: type: string error: type: string details: nullable: true required: - success - type - code - error examples: resourceNotActive: summary: This resource is not running value: success: false type: API code: RESOURCE_NOT_ACTIVE error: This resource is not running subscriptionRequired: summary: This resource has no subscription value: success: false type: API code: SUBSCRIPTION_REQUIRED error: This resource has no subscription subscriptionExpired: summary: Renew this resource's subscription to use it again value: success: false type: API code: SUBSCRIPTION_EXPIRED error: Renew this resource's subscription to use it again accountBanned: summary: Account is banned value: success: false type: API code: ACCOUNT_BANNED error: Account is banned accountSuspended: summary: Account is suspended value: success: false type: API code: ACCOUNT_SUSPENDED error: Account is suspended insufficientPermissions: summary: Insufficient permissions value: success: false type: API code: AUTHORIZATION_ERROR error: Insufficient permissions shareTokenNotAllowed: summary: A share token cannot run commands on a VPS value: success: false type: API code: AUTHORIZATION_ERROR error: A share token cannot run commands on a VPS '404': description: VPS not found content: application/json: schema: type: object properties: success: type: boolean enum: - false type: type: string code: type: string error: type: string details: nullable: true required: - success - type - code - error examples: vpsNotFound: summary: VPS not found value: success: false type: API code: NOT_FOUND error: VPS not found '422': description: Validation error content: application/json: schema: type: object properties: success: type: boolean enum: - false type: type: string enum: - API code: type: string enum: - VALIDATION_ERROR error: type: string enum: - Validation error details: type: object additionalProperties: type: object properties: _errors: type: array items: type: string required: - success - type - code - error - details example: success: false type: API code: VALIDATION_ERROR error: Validation error details: _errors: - The whole schema has some validation problems some_field: _errors: - This field has some validation problem '500': description: Internal Server Error content: application/json: schema: type: object properties: success: type: boolean enum: - false type: type: string enum: - API code: type: string enum: - INTERNAL_ERROR error: type: string enum: - Internal server error details: nullable: true required: - success - type - code - error example: success: false type: API code: INTERNAL_ERROR error: Internal server error security: - bearerAuth: [] components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- An API key from the Storiza dashboard (API & Integrations), sent as `Authorization: Bearer stz_…`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.