SuperAPI AI Directory

neko

General & other

View repository

Updated 10-16 06:41

About this skill

Public Tunnels and Sandboxes with neko

neko puts a port on the internet with one command. It has two modes:

  • neko tunnel PORT shares a port already running on the host (127.0.0.1:PORT).
  • neko run ... --tunnel PORT boots a fresh shuru microVM sandbox, runs a command in it, and shares the port the command listens on.

Both give a public URL at <subdomain>.neko.computer. A subdomain is generated (like swift-otter-h7kq) unless you pass --subdomain.

Setup

Sign in once. Opening any tunnel needs a SuperHQ account.

neko login

Share a local port (no sandbox)

The server is already running on the host. This works on any platform.

# terminal already running: npm run dev on :3000
neko tunnel 3000
# -> tunnel open: https://swift-otter-h7kq.neko.computer -> 127.0.0.1:3000

neko tunnel 3000 --subdomain my-demo
# -> https://my-demo.neko.computer -> 127.0.0.1:3000

Leave it running; press ctrl-c to close the tunnel.

Run in a sandbox and share it

neko run boots an isolated Linux microVM, mounts the current directory at /workspace, runs the command there, and streams output. With --tunnel it also exposes the guest port to a public URL. Requires macOS on Apple Silicon (the VM uses Apple Virtualization).

# anonymous, ephemeral sandbox: serve the current dir and share it
neko run --tunnel 8000 -- python3 -m http.server 8000

The base image is a minimal Debian aarch64 with no language runtime, so the command must install what it needs. neko runs the command as argv directly, with no shell, so shell operators like && need an explicit sh -c:

neko run --tunnel 8000 -- sh -c 'apt-get update && apt-get install -y python3 && python3 -m http.server 8000'

Computers and checkpoints (instant boot)

Installing a runtime on every run is slow. Provision it once, snapshot the disk, then boot from the snapshot instantly.

A computer is a named, versioned sandbox (a branch). A checkpoint is an immutable disk snapshot (a commit). --checkpoint [LABEL] snapshots on the way down; --from REF boots from a checkpoint.

# 1. provision once into a computer named "web", label the snapshot "ready"
neko run web --checkpoint ready -- sh -c 'apt-get update && apt-get install -y python3'

# 2. boot from that checkpoint instantly and serve, sharing the port
neko run web --from web@ready --tunnel 8000 -- python3 -m http.server 8000

# resuming a named computer picks up its latest head automatically
neko run web --tunnel 8000 -- python3 -m http.server 8000

--from takes name (the computer head) or name@label (a specific checkpoint).

Managing computers

neko ls                          # list computers
neko history web                 # checkpoint history of a computer
neko clone web@ready staging     # new computer from a ref (shared node) or an image file
neko rm web                      # remove a computer, reclaim its orphaned checkpoints
neko rm web --keep-checkpoints   # remove the computer but keep its checkpoints
neko gc                          # prune checkpoints unreachable from any computer

neko run flags

neko run [NAME] [flags] -- COMMAND

--tunnel PORT        expose the guest port to a public https URL
--subdomain SUB      request a specific subdomain instead of a generated one
--from REF           boot from a checkpoint (name or name@label)
--checkpoint [LABEL] snapshot the disk on exit, optionally labelled

Omit NAME for an anonymous, ephemeral sandbox (discarded on exit). Pass NAME to persist it as a computer.

Other commands

neko upgrade    # update neko to the latest release

Common patterns

Share a dev server from your machine

# server already running locally on :5173
neko tunnel 5173 --subdomain preview
# share https://preview.neko.computer with a teammate or a webhook

Serve a static site from a sandbox

neko run --tunnel 8000 -- sh -c 'apt-get update && apt-get install -y python3 && cd /workspace && python3 -m http.server 8000'

Reusable runtime, then fast serves

# once: bake a node runtime into a checkpoint
neko run app --checkpoint node -- sh -c 'apt-get update && apt-get install -y nodejs npm'

# many times: instant boot, install deps from the mounted cwd, serve
neko run app --from app@node --tunnel 3000 -- sh -c 'cd /workspace && npm install && npm run dev'

Expose a webhook receiver

neko run --tunnel 4000 -- sh -c 'apt-get update && apt-get install -y python3 && cd /workspace && python3 webhook.py'
# point the provider at https://<sub>.neko.computer

Important constraints

  • Login required. Every tunnel needs neko login (a SuperHQ account). Quotas apply per account (daily and concurrent tunnel limits).
  • neko run is macOS Apple Silicon only. It boots a real microVM via Apple Virtualization. neko tunnel PORT (local port) works anywhere.
  • No shell by default. neko run -- CMD execs argv directly. Use -- sh -c '...' for pipes, &&, redirects, or globs.
  • Minimal base image. The sandbox is a bare Debian aarch64 with no runtime. Install what you need inline, or bake it into a checkpoint.
  • cwd is mounted at /workspace. The command runs there.
  • Ephemeral unless named or checkpointed. An anonymous neko run discards its disk on exit. Name it, or use --checkpoint, to keep state.
  • The tunnel closes when the process exits. Keep neko run --tunnel or neko tunnel in the foreground; ctrl-c ends it.

Deep-dive