Package Information
Available Nodes
Documentation generating…
Documentation
n8n-nodes-kosa8
This is an n8n community node for kosa8 Cloud. It lets your n8n workflows and AI agents run commands and move files in kosa8 Cloud sandboxes: sealed Linux microVMs you create, use and delete through the kosa8 Cloud API.
n8n is a fair-code licensed workflow automation platform.
- Installation
- Credentials
- Operations
- Using it as an AI agent tool
- Example workflow
- Errors
- Compatibility
- Pricing
- Resources
Installation
Follow the installation guide in the n8n community nodes documentation:
- In n8n, open Settings > Community Nodes.
- Select Install, enter
n8n-nodes-kosa8, and confirm.
The package has no runtime dependencies.
Credentials
The node uses a Kosa8 Cloud API credential (n8n requires credential names in title case):
- Sign in to kosa8 Cloud and create an API key at https://app.kosa8.com/app#keys. Keys start with
k8c_live_. - In n8n, create a new credential of type Kosa8 Cloud API.
- Paste the key into API Key. Leave Base URL at
https://api.kosa8.comunless kosa8 gave you another address. - Save. n8n checks the key with
GET /v1/templates.
The key is sent as Authorization: Bearer <key>. Give it the sandboxes:read and sandboxes:write scopes (or a scope that includes them).
Operations
Sandbox
| Operation | What it does |
|---|---|
| Create | Creates a sandbox and waits until it is running. Choose a Template (or the organization default) and, under Options: Name, Size (2x4, 4x8, 8x16 or 16x32 vCPU x GiB), Region, Delete After (Seconds) (60 s to 90 days), Sleep After (Seconds), Environment Variables, Persistent, and Wait Timeout (Seconds). A sized sandbox boots cold and can take longer; the node polls until it is running. |
| Get | Returns one sandbox. |
| Get Many | Lists sandboxes, newest first, with Return All / Limit and filters for Name and Include Deleted. |
| Delete | Deletes a sandbox permanently, with its files. Returns { "deleted": true }. |
| Sleep | Snapshots a sandbox and frees its memory. It wakes on the next command or file call. |
| Wake | Restores a sleeping sandbox now. |
| Execute Command | Runs a command and returns stdout, stderr and exit_code. Command Type is either Shell Command (one line run with sh -c, so pipes, && and variables work) or Arguments (the program and each argument separately, no shell). Set Timeout (Seconds) (a command that waits for its answer runs at most 90 s), per-command Environment Variables, Fail on Non-Zero Exit Code, and Run in Background for longer commands. |
| Get Background Command | Returns the state, exit code and output so far of a command started with Run in Background. |
Get, Get Many, Create, Sleep and Wake have a Simplify switch (on by default) that returns the ten most useful fields: id, name, state, template, region, cpus, mem_mb, created_at, delete_after, cost_usd. Turn it off for the full sandbox record.
File
Paths are absolute, or relative to /workspace. /workspace is the sandbox's working folder; it is kept when the sandbox sleeps.
| Operation | What it does |
|---|---|
| Read | Downloads a file and puts it in a binary field (default data), ready for other nodes. |
| Write | Uploads a file. Input Type is Binary File (from a binary field of the input item) or Text (UTF-8). Options: Append, Permissions (octal, like 644). |
| List | Lists a folder (default /workspace): one item per file or folder, with name, path, type, size, mode and mod_time. |
| Delete | Deletes a file, or a folder with Recursive. Returns { "deleted": true }. |
Pick the sandbox from a list, or give its ID (sbx_…), usually by expression from an earlier Create step: {{ $('Create Sandbox').item.json.id }}.
Using it as an AI agent tool
The node is marked usableAsTool, so you can attach it to n8n's AI Agent node as a tool. An agent can then create a sandbox, run code in it, read and write files, and delete the sandbox when it is done. Setting Delete After (Seconds) on Create is a good guard so a sandbox an agent forgets is removed on its own.
Example workflow
Manual Trigger → Create → Execute Command (echo hello && uname -a) → Write (/workspace/n8n-hello.txt) → Read → List (/workspace) → Delete.
Every node after Create uses {{ $('Create Sandbox').item.json.id }} as the sandbox ID. The Execute Command output looks like:
{
"sandbox_id": "sbx_…",
"exit_code": 0,
"stdout": "hello\nLinux kosa8-guest 6.18.35 #1 SMP … x86_64 Linux\n",
"stderr": ""
}
Errors
The node shows kosa8 Cloud's own message for a failed call, with what to do next:
- 401: the API key is wrong or revoked. Create a new one at https://app.kosa8.com/app#keys.
- 402: no plan, a plan limit, a failed payment or the spending cap. The node shows kosa8's
agent_messageand theupgrade_urlwhere you can fix it. - 404: the sandbox or path does not exist.
- 429: too many requests (retried for you, honouring
Retry-After) or too many active sandboxes (quota_exceeded: delete sandboxes you no longer need). - 504
exec_timeout: a command ran past its timeout or the 90 s limit. Use Run in Background for long commands.
Turn on the node's On Error > Continue setting to get the message in the output instead of stopping the workflow.
Compatibility
Built with @n8n/node-cli and tested against n8n 2.48.4 on Node.js 22.
Pricing
kosa8 Cloud is a paid service; plans start at $29 a month. See https://kosa8.com/pricing/.