kosa8 docs

Guides / kosa8 Cloud / Terminal and large files

Terminal and large files

A kosa8 Cloud sandbox gives you a real terminal over a WebSocket, for a person or for a program that drives one (a REPL, an editor, a TUI). Files move as streams, any size, to any path in the sandbox, with byte ranges and parts, and a presigned link lets anything with the URL download or upload one file straight to the sandbox's host.

An interactive terminal

curl -s -X POST https://api.kosa8.com/v1/sandboxes/sbx_…/terminal \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"cols":120,"rows":40}'
# {"terminal":{"url":"wss://host-1.kosa8.com/host/v1/sandboxes/sbx_…/terminal?cols=120&rows=40&token=…",
#   "expires_at":1789000000000, "protocol":"…"}}

Connect a WebSocket to url before expires_at (at most five minutes). Once connected, the terminal stays open as long as the WebSocket does.

// Node, with the ws package
import WebSocket from "ws";
const { terminal } = await (await fetch(`https://api.kosa8.com/v1/sandboxes/${id}/terminal`, {
  method: "POST", headers: { Authorization: `Bearer ${process.env.KOSA8_API_KEY}` } })).json();
const ws = new WebSocket(terminal.url);
ws.on("message", (data, isText) => isText ? console.error(String(data)) : process.stdout.write(data));
ws.on("open", () => ws.send(Buffer.from("ls -la\n")));

Each terminal is its own container from the sandbox's image, with /workspace mounted. In a persistent sandbox it is not the sandbox's long-lived container: what you install outside /workspace from the terminal is not seen by exec, and the other way round. A sleeping sandbox is woken (and billed again) before the URL is given; an open terminal keeps it awake. Opening one needs sandboxes:write and is recorded in the audit log as sandbox.terminal_open. What you type is not recorded.

Large files through the API

# upload: the request body is the file, to any absolute path
curl -s -X PUT "https://api.kosa8.com/v1/sandboxes/sbx_…/files?path=/workspace/data.csv" \
  -H "Authorization: Bearer $KOSA8_API_KEY" --data-binary @data.csv
# {"file":{"path":"/workspace/data.csv","type":"file","size":73400320,…}}

# download
curl -s "https://api.kosa8.com/v1/sandboxes/sbx_…/files?path=/tmp/model.bin" \
  -H "Authorization: Bearer $KOSA8_API_KEY" -o model.bin

/files and /files/raw are the same route: the bytes stream between you and the sandbox and are never held whole on the way, so there is no 8 MiB limit. A file can be at any absolute path: /workspace, which lasts across sleep and snapshots, or anywhere else in the sandbox's container (/tmp, /root, /home/…), the filesystem its commands see. Paths with .. are refused.

Parts, ranges and resuming

# download bytes 0-1048575 only (206 Partial Content)
curl -s -H "Range: bytes=0-1048575" "https://api.kosa8.com/v1/sandboxes/sbx_…/files?path=/tmp/big.bin" \
  -H "Authorization: Bearer $KOSA8_API_KEY" -o part0

# upload a part at a byte offset; the rest of the file is kept
curl -s -X PUT "https://api.kosa8.com/v1/sandboxes/sbx_…/files?path=/tmp/big.bin&offset=67108864" \
  -H "Authorization: Bearer $KOSA8_API_KEY" --data-binary @part1

# or add to the end
curl -s -X PUT "https://api.kosa8.com/v1/sandboxes/sbx_…/files?path=/tmp/log.txt&append=1" \
  -H "Authorization: Bearer $KOSA8_API_KEY" --data-binary @more.txt

One request body through the API is at most 100 MB (Cloudflare's limit). Send a bigger file as parts with offset=, in any order or several at once, or send it to the host straight with the direct files_url or a link (below). mode=755 sets the permission bits. A full disk answers 507.

Straight to the host: files_url

A create answers with direct (and POST /v1/sandboxes/{id}/direct gives a fresh one). Where the host supports it, direct.files_url takes the same token as direct.exec_url, for GET and PUT ?path= with ranges, offset= and append=:

curl -s -X PUT "$FILES_URL?path=/workspace/dataset.tar" -H "Authorization: Bearer $TOKEN" \
  --data-binary @dataset.tar

It skips the API and its 100 MB limit (4 GiB a request). The token lasts five minutes, works only for that sandbox, never wakes a sleeping one (409 use_api), and each upload is recorded in the audit log as sandbox.file_write with via: direct.

Presigned links

curl -s -X POST https://api.kosa8.com/v1/sandboxes/sbx_…/files/link \
  -H "Authorization: Bearer $KOSA8_API_KEY" -H 'Content-Type: application/json' \
  -d '{"path":"/workspace/dataset.tar","method":"PUT","ttl_s":300}'
# {"link":{"url":"https://host-1.kosa8.com/host/v1/sandboxes/sbx_…/files/raw?path=…&token=…",
#   "method":"PUT","path":"/workspace/dataset.tar","expires_at":1789000000000}}

curl -s -X PUT --data-binary @dataset.tar "$URL"     # no API key needed

Where it is available

Terminals and streamed files need a host whose agent supports them. On an older host, the routes answer 501 not_available, and /files (up to 8 MiB) keeps working as before.