# sandboxes-api ## Pages - [Sandboxes API](https://docs.ezghcloud.com/sandboxes-api/index.md) — Sandboxes are isolated machines started from a container image. Every path is under an organization; lists are paged with limit, cursor and nextCursor. - [Attach to an interactive command](https://docs.ezghcloud.com/sandboxes-api/AttachExec/index.md) — A WebSocket, attached once, by the caller that created the command. Binary messages carry one channel byte and then bytes: 0 is stdin from the client, 1 stdout and 2 stderr to it. Text messages are JSON: the client sends {"type": "resize", "cols", "rows"}, {"type": "signal", "signal"} (HUP, INT, QUIT, TERM, KILL, USR1, USR2, WINCH) and {"type": "stdinClose"}; the server sends {"type": "exit", "exitCode", "signal", "code"} or {"type": "error", "code", "message"} and closes. - [Create a sandbox](https://docs.ezghcloud.com/sandboxes-api/CreateSandbox/index.md) — Synchronous: waits up to 10 seconds for the sandbox to start and answers with the sandbox as it is by then, usually running. A sandbox that could not be started is answered too, with status failed and a statusReason. 400 image_not_found, 400 for a bot the organization doesn't have, 403 access_denied naming bots.pass, 403 image_access_denied, 409 quota_exceeded. - [Delete a sandbox](https://docs.ezghcloud.com/sandboxes-api/DeleteSandbox/index.md) — Answers with the sandbox, status deleting. It is 404 once it is gone. - [Run a command in a sandbox](https://docs.ezghcloud.com/sandboxes-api/ExecCommand/index.md) — Answers 200 with application/x-ndjson, a line as output arrives: {"stream": "stdout" or "stderr", "data": base64}, then a last line {"exitCode", "signal", "timedOut", "error"}. With interactive true it answers 201 with an execId to attach to within 30 seconds instead. A suspended sandbox is resumed first. A suspended sandbox in a VPC that can't reach its VPC now is 409 vpc_unavailable. 409 sandbox_not_running when it is stopped, failed or impaired; 503 sandbox_busy while it is changing status. Takes no Idempotency-Key. - [Get a sandbox](https://docs.ezghcloud.com/sandboxes-api/GetSandbox/index.md) - [List a project's sandboxes, newest first](https://docs.ezghcloud.com/sandboxes-api/ListSandboxes/index.md) - [Read a file from a sandbox](https://docs.ezghcloud.com/sandboxes-api/ReadFile/index.md) — The file's bytes, streamed, with no Content-Length. A suspended sandbox is resumed first. A suspended sandbox in a VPC that can't reach its VPC now is 409 vpc_unavailable. 404 not_found when there is no such file, 403 file_permission_denied, 400 invalid_request for a directory. A read that fails after the 200 ends the response abnormally (a reset stream over HTTP/2, no final chunk over HTTP/1.1): a body that ends cleanly is the whole file. - [Resume a suspended sandbox](https://docs.ezghcloud.com/sandboxes-api/ResumeSandbox/index.md) — Waits up to 10 seconds. memoryRestored says whether its processes carried on or it was started again from its disk. 409 sandbox_not_suspended when it isn't suspended; 409 sandbox_held or organization_held when EZGH has put the sandbox or the organization on hold; 409 vpc_unavailable when a sandbox in a VPC can't reach its VPC now; 503 no_capacity when there is no room for it now. - [Start a stopped sandbox](https://docs.ezghcloud.com/sandboxes-api/StartSandbox/index.md) — Starts it again from its disk. Waits up to 10 seconds. 409 sandbox_not_stopped when it isn't stopped; 409 sandbox_held or organization_held when EZGH has put the sandbox or the organization on hold; 409 vpc_unavailable when a sandbox in a VPC can't reach its VPC now; 503 no_capacity when there is no room for it now. - [Stop a sandbox](https://docs.ezghcloud.com/sandboxes-api/StopSandbox/index.md) — Its processes end; its disk is kept. Waits up to 10 seconds. 409 sandbox_not_running when it is neither running nor suspended. - [Suspend a sandbox](https://docs.ezghcloud.com/sandboxes-api/SuspendSandbox/index.md) — Saves the sandbox's memory and disk and frees its host. Waits up to 10 seconds. 409 sandbox_not_running when it isn't running. - [Write a file into a sandbox](https://docs.ezghcloud.com/sandboxes-api/WriteFile/index.md) — The body is the file, at most 5 GiB, replacing any file at the path only once all of it has arrived. A suspended sandbox is resumed first. A suspended sandbox in a VPC that can't reach its VPC now is 409 vpc_unavailable. - [Error](https://docs.ezghcloud.com/sandboxes-api/schemas/Error/index.md) — Every non-2xx answer. Clients branch on code, never on message. - [ExecPending](https://docs.ezghcloud.com/sandboxes-api/schemas/ExecPending/index.md) - [ExecRequest](https://docs.ezghcloud.com/sandboxes-api/schemas/ExecRequest/index.md) - [FileWritten](https://docs.ezghcloud.com/sandboxes-api/schemas/FileWritten/index.md) - [QuotaExceeded](https://docs.ezghcloud.com/sandboxes-api/schemas/QuotaExceeded/index.md) — quota_exceeded: the quota that refused the request. Never with Retry-After. - [Sandbox](https://docs.ezghcloud.com/sandboxes-api/schemas/Sandbox/index.md) - [SandboxCreate](https://docs.ezghcloud.com/sandboxes-api/schemas/SandboxCreate/index.md) - [SandboxList](https://docs.ezghcloud.com/sandboxes-api/schemas/SandboxList/index.md) - [SandboxStatus](https://docs.ezghcloud.com/sandboxes-api/schemas/SandboxStatus/index.md) — Clients treat any other value as unknown.