neko puts a port on the internet with one command. It has two modes:
neko tunnel PORTshares a port already running on the host (127.0.0.1:PORT).neko run ... --tunnel PORTboots 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 runis 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 -- CMDexecs 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 rundiscards its disk on exit. Name it, or use--checkpoint, to keep state. - The tunnel closes when the process exits. Keep
neko run --tunnelorneko tunnelin the foreground; ctrl-c ends it.
Deep-dive
- docs/rfcs/0002-computers-and-checkpoints.md — the computer and checkpoint model
- docs/specs/tunnel-protocol.md — the tunnel wire protocol