npm package: @noxsoft/jack
Description: Local executor that lets cloud ANIMA jack into your machine — file system, shell, browser, and computer use.
Author: NoxSoft DAO LLC
Latest version: 0.2.1

# @noxsoft/jack

> Local executor for ANIMA Cloud. The brain runs in the cloud, the body runs on your laptop.

When ANIMA Cloud needs to read your files, run a build, drive your browser, or click around your desktop, it doesn't do it on a Railway worker — it sends the tool call to **your** machine, where `noxsoft-jack` is running. Each user runs their own executor, so cloud worker capacity isn't burned on per-user file systems.

## Install

```bash
npm install -g @noxsoft/jack

# Optional — enable browser automation
npx playwright install chromium

# Optional — enable computer use (mouse/keyboard/screen)
npm install -g @nut-tree-fork/nut-js
```

## Run

```bash
export ANIMA_API_KEY=ak_live_xxxxxxxxxxxxxxxx
noxsoft-jack --root ~/code/myproject

# Bind to a specific ANIMA so only its jobs route here
noxsoft-jack --root ~/code/myproject --anima "Code Helper"
noxsoft-jack --root ~/code/myproject --anima a1b2c3d4-...

# Attach to a real Chrome instance on startup. If nothing is listening
# on port 9222, jack will spawn one with a dedicated noxsoft-jack profile
# (logins persist between sessions). You can also toggle this from the
# /dashboard/jack page after the client is running.
noxsoft-jack --chrome-port 9222
```

You'll see:

```
▶ noxsoft-jack v0.1.0
  cloud:    https://anima.noxsoft.net
  root:     /Users/you/code/myproject
✓ connected — session a1b2c3d4
  waiting for jobs…
```

Now any ANIMA agent job you launch with `requires_jack: true` will route its file/shell/browser/computer tools through this process.

## Tools exposed

| Tool       | Default | What it does                                       |
|------------|---------|----------------------------------------------------|
| `Read`     | on      | Read a file (offset/limit support)                 |
| `Write`    | on      | Write a file (creates parents)                     |
| `Edit`     | on      | Find/replace edit                                  |
| `Glob`     | on      | Pattern match files in the jail                    |
| `Stat`     | on      | File metadata                                      |
| `Bash`     | on      | Run shell commands (`--no-bash` to disable)        |
| `Browser`  | on*     | Playwright browser automation (`--no-browser`)     |
| `Computer` | on*     | Mouse/keyboard/screen via nut-js (`--no-computer`) |

\* requires the optional dep installed

## Safety

- All filesystem ops are jailed under `--root`. The cloud cannot escape it.
- `--no-bash`, `--no-browser`, `--no-computer` give you opt-outs per capability.
- The session secret never leaves your machine and is rotated on every connect.
- Ctrl-C disconnects instantly.

## Why this exists

Cloud workers are expensive and shared. If every user's coding job ran on Railway, we'd be paying for tens of thousands of disposable workspaces. With `@noxsoft/jack`, the cloud only does orchestration (planning, LLM calls, memory) and the local machine does the actual work — so we can serve 10× the users on the same cloud capacity, and your files never leave your laptop.