PkgFoundry
Catalog npm
Back to packageRELEASE DETAILS

1.1.0

npm

8remo

Remote AgentCLI and web client.

Published5 May 2026
Direct dependencies25
Transitive dependenciesNot calculated

README

Current package documentation

Vibe-Coding Anywhere with 8remo

8remo app icon
8remo - Vibe-Coding Anywhere.

8remo is a local-first remote workspace tool: one npm command starts a host process and serves a browser client for terminal, files, and local site proxy workflows.

Install and start

npm install -g 8remo
8remo setup
8remo --root <project-directory>

Use --root to choose the directory that 8remo can expose. The browser client can browse files, preview file contents, and create terminal sessions only inside that selected root. By default, 8remo starts a Cloudflare Quick Tunnel and shows an 8remo Quick URL, relay URL, access key, and QR code in the terminal UI.

For local-only access, pass --no-tunnel:

8remo --root <project-directory> --no-tunnel

To keep 8remo running in the background with a notification-area icon:

8remo background --tray --root <project-directory>

The default local host is http://localhost:2208.

Commands

8remo --root <project-directory>          # start with Cloudflare Quick Tunnel
8remo --root <project-directory> --no-tunnel # start for local browser access only
8remo                                  # return to the detached host UI when one is already running
8remo ui --root <project-directory>       # start and open the local Web UI
8remo background --root <project-directory>
8remo background --tray --root <project-directory>
8remo status                          # show detached background host status
8remo stop                            # stop the detached background host
8remo update                          # update a global install
8remo otp setup                       # create a Google Authenticator compatible OTP key
8remo otp status                      # show whether OTP unlock is enabled
8remo otp renew                       # rotate the persistent OTP key
8remo otp revoke                      # disable OTP unlock
8remo doctor                          # check runtime tools and generated assets
8remo setup                           # install cloudflared for tunnel support

Options:

8remo --port 3308 --root <project-directory>
8remo ui --host 0.0.0.0
8remo --root <project-directory> --no-tunnel
8remo --root <project-directory> --relay-url https://8remo.online
8remo --tray --root <project-directory>
8remo setup --skip-cloudflared

If the CLI is started in a non-interactive shell, pass --root <directory> or set EIGHT_REMO_ROOT.

Host terminal UI

When 8remo runs in an interactive terminal, the host process shows a colorized keyboard menu. Use arrow keys to move, Enter to select, Esc to go back, and Ctrl+C to stop the host.

Before the host starts, an initial setup stage appears when TOTP or Telegram credentials are missing. It can create the authenticator QR code and save dedicated 8remo Telegram settings under ~/.8remo/telegram.json. Non-interactive runs skip this stage; configure TOTP with the dedicated otp command and Telegram with EIGHT_REMO_TELEGRAM_BOT_TOKEN / EIGHT_REMO_TELEGRAM_CHAT_ID or the host terminal UI instead.

The host menu can open the Web UI, review access requests, inspect trusted OTP devices, remove approved devices, manage Telegram notifications, run initial setup, refresh pairing state, hide to the system tray when supported, keep running in the current terminal as a fallback, or exit. Multi-select screens use Space to toggle items and Enter to continue.

Access request and trusted-device removal actions ask for confirmation before changing state.

Background and tray

8remo background --root <directory> starts the same host server as a detached npm process and returns control to the terminal. It writes process metadata and logs under ~/.8remo.

8remo background --root <project-directory>
8remo background --tray --root <project-directory>
8remo --tray --root <project-directory>
8remo status
8remo stop

The background command still serves the Web UI on the selected host and port, and it starts Cloudflare Quick Tunnel by default. Use --no-tunnel for local-only background mode. Use Telegram approval replies for remote approval workflows when the terminal UI is not visible.

Tray mode keeps 8remo as an npm CLI while exposing a notification-area icon when the OS session supports one. In an interactive terminal session with tray support, 8remo starts or reuses a detached tray host first, then shows the terminal UI as a controller for that background host. Hide / Keep Running closes only the controller menu; the server and Cloudflare tunnel keep running in the detached host. Run 8remo again to return to that detached session. The tray menu can copy the active URL, toggle launch-at-login, and quit the host. On headless Linux or unsupported sessions, 8remo keeps running without the tray icon.

Update a global npm install with:

8remo update
npm install -g 8remo

Browser workspace

The web client has Tree, File, and Agent views on mobile. Selecting a file opens the File view with parsed Markdown rendering for .md, .markdown, and .mdx files; other files render as wrapped monospace text. On desktop, the file preview is merged into the Tree workspace so the tree and selected file stay visible together.

The Agent CLI supports multiple terminal sessions. On mobile, use the paste button in the Agent CLI header to send clipboard text to the active terminal, or use the copy button to enter line-copy mode. Tap a visible terminal line to copy it, or long press to copy the wrapped output block.

OTP credential unlock

8remo can accept a 6-digit TOTP code from Google Authenticator or another compatible authenticator app on the credential screen. The existing short-lived pairing URL still works as a bootstrap fallback.

Create or inspect the persistent OTP credential from the host machine:

8remo otp setup
8remo otp status
8remo otp show --reveal-secret
8remo otp renew
8remo otp revoke

The OTP seed is stored in ~/.8remo/otp.json by default. Set EIGHT_REMO_OTP_FILE to use another file. setup and renew print an enrollment QR code; treat that output like a password because the seed remains valid until renew or revoke.

OTP attempts are rate-limited before they can create the normal 24-hour browser session.

After a remote browser signs in with OTP through a valid relay access key, 8remo remembers that browser as a trusted device and opens the workspace without a second host-approval step. On later visits through a fresh valid relay access key, the same browser can skip TOTP because the access key proves the current route and the browser-held trusted-device cookie proves the remembered device. Revoking the trusted device in the host UI forces TOTP again. Direct tunnel/origin requests cannot use a trusted-device cookie alone to skip OTP.

Trusted devices are stored in ~/.8remo/trusted-devices.json by default. Set EIGHT_REMO_TRUSTED_DEVICES_FILE to use another file. The store contains hashed device fingerprints and hashed tunnel client signals, not raw browser device secrets, IP addresses, user agents, OTP codes, or pairing tokens. If the browser, network address, or user-agent changes, 8remo may require host approval again. Use the host terminal UI to remove selected approved devices or remove all trusted devices.

Local setup checks

Use doctor to check the local runtime and optional tunnel tooling:

8remo doctor

The command checks Node.js, cloudflared, the compiled server, and the exported web client. Missing core runtime tools return a failing exit code. Missing optional tools or generated assets are reported with fix suggestions.

Use setup to install optional tunnel tooling:

8remo setup

The command installs cloudflared when it is missing. It does not run npm install, install dev-time tooling, build the project, or validate generated server/web assets. Use a built 8remo package for normal runtime setup; in a development checkout, run npm install once and npm run build separately when source files change.

On Windows it uses:

winget install --id Cloudflare.cloudflared --accept-package-agreements --accept-source-agreements

On macOS it uses Homebrew when brew is available. On Ubuntu and Debian-style Linux systems with apt-get, it adds Cloudflare's apt repository and installs cloudflared with apt-get install -y cloudflared. On Debian-style Linux systems without apt-get, it downloads the latest Cloudflare .deb package and installs it with sudo dpkg -i. Other Linux distributions should install cloudflared manually, or use:

8remo setup --skip-cloudflared

Remote access through Cloudflare Tunnel

Install cloudflared, then start 8remo with --tunnel:

8remo --root <project-directory>

The CLI still serves the local UI on localhost, then starts a Cloudflare Quick Tunnel to that local Node host. When cloudflared prints the generated trycloudflare.com address, 8remo prints an 8remo Quick URL, an 8remo Relay URL, a manual access key, and the direct Cloudflare Tunnel URL. Open the quick URL or scan the QR code to reach the current tunnel through https://8remo.online.

Access keys are short-lived routing envelopes. The hosted relay is a Cloudflare Worker that reads the access key, stores it in an HTTP-only 8remo.online relay cookie, and proxies requests to the current trycloudflare.com tunnel so the browser can stay on https://8remo.online. If OTP is enabled, the first untrusted browser sees a TOTP prompt in the 8remo app. After a valid TOTP code, 8remo creates a 24-hour session and stores the browser as trusted. Authenticated browsers can keep using the relay for that session even after the original access key expires; unauthenticated browsers still need a fresh access key. Later visits from that browser through a valid relay access key open without TOTP. If OTP is not enabled, the Worker injects the current pairing token server-side while proxying, including Socket.IO/WebSocket handshakes. Remote tunnel clients cannot regenerate pairing tokens.

Treat relay URLs and access keys as temporary secrets. 8remo periodically checks the public tunnel through /api/health. If cloudflared exits, no public URL appears during startup, or health checks fail repeatedly, 8remo restarts the tunnel, drops stale tunnel URLs from the host UI, and generates a fresh relay URL and access key for the new route.

If EIGHT_REMO_TELEGRAM_BOT_TOKEN and EIGHT_REMO_TELEGRAM_CHAT_ID are available in the process environment, or if credentials are saved in ~/.8remo/telegram.json, 8remo sends the relay quick URL and a QR image to that Telegram chat. Telegram delivery is optional; startup continues if the credentials are missing or the send fails. The host terminal UI includes a Telegram Notifications menu for setting, testing, or clearing the dedicated 8remo bot credentials without touching Claude task-completion hook settings.

If cloudflared is not on PATH, pass its location:

8remo --root <project-directory> --cloudflared <cloudflared-path>

To point generated relay links at another connect page:

8remo --root <project-directory> --relay-url https://8remo.online

To deploy the hosted relay Worker:

npm run deploy:relay

The Worker configuration is in wrangler.toml. It serves the static access-key page from relay/ when no key is present, then proxies keyed sessions through 8remo.online without redirecting the browser to the raw tunnel host.

Develop from source

Use these commands only when working inside this checkout:

npm install
npm run dev
npm run build
npm start

npm run dev starts the CLI host from TypeScript. npm run build compiles the CLI/server and static web client. npm start runs the built CLI.

MVP features

  • Paired local browser URL with a 30-minute token.
  • Multiple WebSocket terminal sessions backed by the host shell.
  • File explorer and folder creation under the selected root, with real-path checks to block .. traversal and symlink/junction escapes.
  • Local dev-server proxy at /proxy/:port/.
  • Optional Cloudflare Quick Tunnel and relay access key for remote browser access.

Later stage

  • Hosted edge broker.
  • Real PTY persistence via a native PTY backend.
  • Remote desktop streaming and input control.
  • Tauri desktop app.
  • React Native / Expo mobile app.

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Declared dependencies 25

Native requirements
25 direct targetsNot calculated transitive count
Package / targetRequirementRelationship
mime
Environment
{
  "local_name": "mime",
  "alias": false,
  "peer_metadata": null
}
^4.1.0runtime
next
Environment
{
  "local_name": "next",
  "alias": false,
  "peer_metadata": null
}
^16.2.4runtime
open
Environment
{
  "local_name": "open",
  "alias": false,
  "peer_metadata": null
}
^10.2.0runtime
react
Environment
{
  "local_name": "react",
  "alias": false,
  "peer_metadata": null
}
^19.2.3runtime
qrcode
Environment
{
  "local_name": "qrcode",
  "alias": false,
  "peer_metadata": null
}
^1.5.4runtime
express
Environment
{
  "local_name": "express",
  "alias": false,
  "peer_metadata": null
}
^5.2.1runtime
systray
Environment
{
  "local_name": "systray",
  "alias": false,
  "peer_metadata": null
}
^1.0.5runtime
node-pty
Environment
{
  "local_name": "node-pty",
  "alias": false,
  "peer_metadata": null
}
^1.1.0runtime
react-dom
Environment
{
  "local_name": "react-dom",
  "alias": false,
  "peer_metadata": null
}
^19.2.3runtime
socket.io
Environment
{
  "local_name": "socket.io",
  "alias": false,
  "peer_metadata": null
}
^4.8.3runtime
@xterm/xterm
Environment
{
  "local_name": "@xterm/xterm",
  "alias": false,
  "peer_metadata": null
}
^6.0.0runtime
lucide-react
Environment
{
  "local_name": "lucide-react",
  "alias": false,
  "peer_metadata": null
}
^0.561.0runtime
@types/qrcode
Environment
{
  "local_name": "@types/qrcode",
  "alias": false,
  "peer_metadata": null
}
^1.5.6runtime
react-markdown
Environment
{
  "local_name": "react-markdown",
  "alias": false,
  "peer_metadata": null
}
^10.1.0runtime
qrcode-terminal
Environment
{
  "local_name": "qrcode-terminal",
  "alias": false,
  "peer_metadata": null
}
^0.12.0runtime
@xterm/addon-fit
Environment
{
  "local_name": "@xterm/addon-fit",
  "alias": false,
  "peer_metadata": null
}
^0.11.0runtime
socket.io-client
Environment
{
  "local_name": "socket.io-client",
  "alias": false,
  "peer_metadata": null
}
^4.8.3runtime
react-simple-keyboard
Environment
{
  "local_name": "react-simple-keyboard",
  "alias": false,
  "peer_metadata": null
}
^3.8.198runtime
tsx
Environment
{
  "local_name": "tsx",
  "alias": false,
  "peer_metadata": null
}
^4.21.0development
typescript
Environment
{
  "local_name": "typescript",
  "alias": false,
  "peer_metadata": null
}
^5.9.3development
@types/node
Environment
{
  "local_name": "@types/node",
  "alias": false,
  "peer_metadata": null
}
^25.0.3development
@types/react
Environment
{
  "local_name": "@types/react",
  "alias": false,
  "peer_metadata": null
}
^19.2.7development
@types/express
Environment
{
  "local_name": "@types/express",
  "alias": false,
  "peer_metadata": null
}
^5.0.6development
@types/react-dom
Environment
{
  "local_name": "@types/react-dom",
  "alias": false,
  "peer_metadata": null
}
^19.2.3development
@types/qrcode-terminal
Environment
{
  "local_name": "@types/qrcode-terminal",
  "alias": false,
  "peer_metadata": null
}
^0.12.2development

Distribution files

1 collected
Distribution 1

Source distribution

Source file
Checksums from source
{
  "shasum": "20f56a41953cdef28d8703729212ea8bb74947e6",
  "tarball": "https://registry.npmjs.org/8remo/-/8remo-1.1.0.tgz",
  "fileCount": 58,
  "integrity": "sha512-2MCSWFVKYX6ETET/VaspsXGfbiIsJxWPWn7+rHabDSjOaxx2IyLk3ZAjQSV7Cyz5WkyY62yZO1kPbQ6jFMHTMg==",
  "signatures": [
    {
      "sig": "MEQCIFyyxknpSGdci9qottLrVo48Z3y3Zj/B5ZlJ9/39p5ZCAiAtR1sNXoL8GMq8grYATswT2x9JwzGyvs9TxPVMBYwh2g==",
      "keyid": "SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"
    }
  ],
  "unpackedSize": 1879739
}

Metadata history

Meaningful changes
Current collected state Current

Observed since 20 Oct, 21:25 UTC

No superseded metadata states collected. Unchanged observations do not create new revisions.

Record identity

package_version:30f5cceb6a2cf8ee2e2044d6cb0d48455f9d60ca4723d56817da2dae17bf32ad

Other collected versions

1.1.55 May1.1.45 May1.1.35 May1.1.25 May1.1.15 MayView all collected versions →