@locci/box

CLI for Locci Box — execute code in isolated microVM sandboxes, manage API keys, and connect AI agents via MCP.

Installation

# NPM (recommended)
npm install -g @locci/box

# or via pnpm
pnpm add -g @locci/box

# or without installing
npx @locci/box --help

Quick Start

# 1. Configure
loccibox init

# 2. Run code
loccibox run -l python -c "print('Hello from Locci Box!')"

# 3. Run from a file
loccibox run -l node -f script.js

Commands

init

Interactive setup wizard — sets API URL, API key, and profile name.

loccibox init

login

Authenticate with email and password to get a JWT for key management.

loccibox login

run

Execute code in an isolated sandbox.

loccibox run [options]

Options:
  -l, --lang <language>    python | node | bash | ruby  (required)
  -c, --code <code>        Inline code to execute
  -f, --file <path>        Path to a code file
  -t, --timeout <seconds>  Execution timeout in seconds (default: 30)
  --profile <name>         Use a specific profile

loccibox run -l python -c "print('hello')"
loccibox run -l bash -c "echo \$HOSTNAME"
loccibox run -l node -f index.js -t 60

sandboxes

List all currently running sandboxes — recover IDs when a response was lost.

loccibox sandboxes [--profile <name>]

status

Check the status of a specific sandbox by ID.

loccibox status <sandbox-id> [--profile <name>]

stop

Stop and destroy a running sandbox.

loccibox stop <sandbox-id> [-y] [--profile <name>]

Flags:
  -y, --yes    Skip confirmation prompt

keys

Manage API keys (requires loccibox login first).

loccibox keys list
loccibox keys create --name "my-key"
loccibox keys revoke <key-id>
loccibox keys delete <key-id>

metrics

View system and tenant usage statistics (requires admin key).

loccibox metrics [--profile <name>]

mcp start

Start a stdio MCP server — connect Claude Desktop, Cursor, or any MCP client directly to Locci Box.

loccibox mcp start

mcp config

Print ready-to-paste MCP config for your client.

loccibox mcp config

Example output:

{
  "mcpServers": {
    "locci-box": {
      "command": "loccibox",
      "args": ["mcp", "start"],
      "env": {
        "LOCCIBOX_API_URL": "https://api-box.locci.cloud",
        "LOCCIBOX_API_KEY": "lbk_live_..."
      }
    }
  }
}

MCP Tools

When connected via loccibox mcp start or the HTTP transport, the following tools are available to AI agents:

| Tool | Description | |------|-------------| | run_sandbox | Execute code in an isolated microVM | | get_sandbox_status | Check the status of a running sandbox | | stop_sandbox | Stop and destroy a sandbox | | list_sandboxes | List all active sandboxes (use when a prior run_sandbox response was lost) |

Configuration

Config is stored at ~/.loccibox/config.json:

{
  "defaultProfile": "default",
  "profiles": {
    "default": {
      "apiUrl": "https://api-box.locci.cloud",
      "apiKey": "lbk_live_..."
    }
  }
}

Environment variables override the config file:

export LOCCIBOX_API_URL="https://api-box.locci.cloud"
export LOCCIBOX_API_KEY="lbk_live_..."

HTTP MCP Transport

If the API server has MCP_HTTP_ENABLED=true, it also accepts MCP over HTTP at POST /mcp:

{
  "mcpServers": {
    "locci-box": {
      "type": "http",
      "url": "https://box.locci.cloud/mcp",
      "headers": { "Authorization": "Bearer lbk_live_..." }
    }
  }
}

Project Structure

cli/
├── src/
│   ├── commands/   init · login · run · sandboxes · status · stop · metrics · keys · mcp
│   ├── lib/        api.ts · config.ts · output.ts
│   ├── types/      index.ts
│   └── index.ts
├── dist/           compiled output (published to NPM)
├── package.json
└── tsconfig.json

License

MIT — see LICENSE