---
title: "Run one command in a computer"
method: POST
path: "/v1/computers/{id}/exec"
tags: ["Computers"]
---

# Run one command in a computer

`POST /v1/computers/{id}/exec`

## Request

- Base URL: `https://api.steel.dev`
- URL: `https://api.steel.dev/v1/computers/{id}/exec`
- Auth: one of:
  - API key in header `steel-api-key`
  - none

Give exactly one of command (run by /bin/sh -c) and argv. Output is text with stdout and stderr merged. With stream true (the default) the response is newline-delimited JSON events: start, output, keepalive, exit. With stream false the output is collected into one JSON result, cut at 8 MiB and marked truncated. timeoutSeconds bounds the run time (at most 3600) and is reported as timedOut with exit code -1. The command is killed when the client disconnects; start long-lived processes with setsid nohup.

## Path parameters

- `id` string, required

## Headers

- `steel-project-id` string

## Request body

- union
  - object
    - `argv` string[]: A program and its arguments, run without a shell.
    - `command` string, required: A shell command, run by /bin/sh -c.
    - `cwd` string
    - `env` object
    - `stream` boolean
    - `timeoutSeconds` integer
  - object
    - `argv` string[], required: A program and its arguments, run without a shell.
    - `command` string: A shell command, run by /bin/sh -c.
    - `cwd` string
    - `env` object
    - `stream` boolean
    - `timeoutSeconds` integer

## Response `200`

The command ran. The content type follows the stream flag.

- ExecComputerResult
  - `exitCode` integer, required
  - `output` string, required
  - `timedOut` boolean, required
  - `truncated` boolean, required

## Other responses

- `400`: The request is malformed.
- `403`: Computers require a project-scoped API key.
- `404`: The computer does not exist in this project.
- `413`: The request body exceeds 1 MiB.
- `502`: The computer did not answer.
- `503`: The computer is not available right now. Retry after the given delay.
- `504`: The computer did not answer in time.

## Changes

- **2026-10-16** `8f7e74e04bd3`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/steel-dev/apis/steel-api/changes/v1/computers/:id/exec/post.md)

---

[API](https://skmtc.dev/steel-dev/apis/steel-api.md) - [All operations](https://skmtc.dev/steel-dev/apis/steel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/steel-dev/apis/steel-api/revisions/8f7e74e04bd3?raw)