> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hopx.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Command Execution

> Command execution resource for running shell commands in HopX sandboxes using the JavaScript/TypeScript SDK. Complete reference for the Commands class including async methods for running commands synchronously and in the background. Includes TypeScript examples for system administration and automation.

**Version:** 0.1.22\
**Last Verified:** 2025-01-27\
**Package:** `@hopx-ai/sdk` on [npm](https://www.npmjs.com/package/@hopx-ai/sdk)

## Overview

The `Commands` resource provides shell command execution capabilities for sandboxes. Access it via the `commands` property on a `Sandbox` instance.

## Methods

### `run`

Run a shell command.

```typescript theme={null}
async commands.run(
    command: string,
    options?: CommandOptions
): Promise<CommandResponse>
```

**Parameters:**

* `command` (`string`): Shell command to execute
* `options.timeout` (`number`, optional): Command timeout in seconds (default: `30`)
* `options.background` (`boolean`, optional): Run in background (default: `false`)
* `options.workingDir` (`string`, optional): Working directory (default: `'/workspace'`)
* `options.env` (`Record<string, string>`, optional): Environment variables

**Returns:** `Promise<CommandResponse>` - Command execution result

**Example:**

```typescript theme={null}
const result = await sandbox.commands.run('ls -la /workspace');
console.log(result.stdout);
console.log(`Exit code: ${result.exitCode}`);
```

***

### `runBackground`

Run command in background.

```typescript theme={null}
async commands.runBackground(
    command: string,
    options?: Omit<CommandOptions, 'background'>
): Promise<{ processId: string }>
```

**Returns:** `Promise<{ processId: string }>` - Process ID

***

## Related Classes

* **[Sandbox](/sdk/javascript/sandbox)** - Main sandbox class
* **[Files](/sdk/javascript/files)** - File operations resource

## See Also

* [Core Concepts: Execution](/core-concepts/execution) - Learn about code execution
* [Sandbox Class](/sdk/javascript/sandbox) - Access commands via `sandbox.commands`

## Related

* **[Python SDK: Commands](/sdk/python/commands)** - Python SDK command execution
* **[Running Commands](/core-concepts/commands/running)** - Learn about command execution
* **[Background Commands](/core-concepts/commands/background)** - Run commands in background

## Next Steps

* Learn about [Running Commands](/core-concepts/commands/running) for synchronous execution
* Explore [Background Commands](/core-concepts/commands/background) for non-blocking tasks
* Review [Code Execution](/core-concepts/code-execution/synchronous) for programmatic execution
* **[CLI Commands](/cli/commands/cmd)** - Execute shell commands from CLI