kosa8

kosa8 Cloud sandboxes for n8n: run commands and move files in sealed microVMs

Package Information

Released: this month
Downloads: 0 weekly / 0 monthly
Latest Version: 0.1.0
Author: Kosa8 Labs

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

Follow the installation guide in the n8n community nodes documentation:

  1. In n8n, open Settings > Community Nodes.
  2. 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):

  1. Sign in to kosa8 Cloud and create an API key at https://app.kosa8.com/app#keys. Keys start with k8c_live_.
  2. In n8n, create a new credential of type Kosa8 Cloud API.
  3. Paste the key into API Key. Leave Base URL at https://api.kosa8.com unless kosa8 gave you another address.
  4. 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_message and the upgrade_url where 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/.

Resources

License

MIT

Discussion