# 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 get `bash -l` (or `sh -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](https://docs.kosa8.com/guides/cloud/) 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 (`GET` to download, `PUT` to upload) on one path, on one sandbox. It works for `ttl_s` seconds, from 10 to 300 (the default is 300), and never past the sandbox's `delete_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 `GET` link needs `sandboxes:read` to create and a `PUT` link needs `sandboxes:write`. Each one is recorded in the audit log as `sandbox.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-stream` attachments. 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.

---
Source: https://docs.kosa8.com/guides/cloud-terminal-files/
