---
title: "Operate on saved project files"
method: POST
path: "/v1/sandboxes/{id}/files"
tags: ["Sandboxes"]
---

# Operate on saved project files

`POST /v1/sandboxes/{id}/files`

## Request

- Base URL: `/` (relative, and the document was published on a file host, not at the API’s origin)
- URL: `/v1/sandboxes/{id}/files`
- Auth: HTTP bearer

Returns a fenced command receipt. Read its verified JSON output through the execution stream. Reads use chunks up to 256 KiB and writes use chunks up to 32 KiB. Existing file writes require the current SHA-256.

## Path parameters

- `id` string, required

## Headers

- `Idempotency-Key` string, required

## Request body

- SandboxFileOperation
  - `operation` 'list' | 'stat' | 'read' | 'write', required
  - `path` string, required
  - `data` string, byte
  - `offset` integer
  - `limit` integer
  - `expected_sha256` string
  - `create_parents` boolean

## Response `202`

Success

- SandboxExec
  - `id` string, required
  - `sandbox_id` string, required
  - `spec` SandboxExecRequest, required
    - `command` string[], required: Process argument vector. No shell parsing is performed.
    - `cwd` string: Optional canonical absolute POSIX working directory.
    - `env` object: Nonsecret environment values. Values equal to any retained tenant secret are rejected. Use sandbox secrets for confidential values.
    - `timeout_s` integer: Process timeout no greater than the sandbox maximum lifetime.
    - `stdin` boolean: Enable framed stdin writes for this process.
    - `tty` boolean: Allocate a controlling terminal with merged stdout and stderr. Requires stdin and explicit rows and cols.
    - `rows` integer
    - `cols` integer
  - `state` 'queued' | 'dispatching' | 'running' | 'completed' | 'failed' | 'cancelled' | 'lost', required
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required
  - `dispatched_at` string, date-time, nullable
  - `deadline_at` string, date-time, nullable
  - `started_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable
  - `exit_code` integer, nullable: Process exit code when known. A completed process can have a nonzero exit code.
  - `failure_code` string: Failure to start or maintain execution, separate from a process exit code.
  - `output_sequence` integer, required
  - `stdout_bytes` integer, required
  - `stderr_bytes` integer, required
  - `final_output_sequence` integer, nullable
  - `cancel_requested_at` string, date-time, nullable
  - `cancel_reason` string

## Other responses

- `default`: Operation refused with a diagnostic and next action

---

[API](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api.md) - [All operations](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/llms.txt) - [OpenAPI document](https://skmtc.dev/nodus-compute/apis/nodus-infrastructure-execution-api/revisions/a59210899d95?raw)