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.
- Binary messages are keystrokes going in and terminal output coming out.
- Text messages are JSON control. Send
{"type":"resize","cols":100,"rows":30}when the window changes size. When the program ends you receive{"type":"exit","code":0}, and then the socket closes. command(for example["python3"]) runs that program instead of a login shell. By default you getbash -l(orsh -l) in/workspace.
// 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
- A link allows one method (
GETto download,PUTto upload) on one path, on one sandbox. It works forttl_sseconds, from 10 to 300 (the default is 300), and never past the sandbox'sdelete_after. - It goes to the sandbox's host directly, not through the API. The only limits are the sandbox's disk and 4 GiB per upload.
- Anyone holding the URL can use it until it expires, so treat it as a secret. A
GETlink needssandboxes:readto create and aPUTlink needssandboxes:write. Each one is recorded in the audit log assandbox.file_link, with the path and method but never the token. - A sleeping sandbox is woken before the link is given. If it falls asleep again before the link is
used, the host answers
409 use_api: ask for a new link. - Downloads are sent as
application/octet-streamattachments. A browser saves them and never renders them.
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.