{"id":50551789,"url":"https://github.com/miketeddyomondi/locci-box","last_synced_at":"2026-06-04T04:02:10.273Z","repository":{"id":358147588,"uuid":"1240230293","full_name":"MikeTeddyOmondi/locci-box","owner":"MikeTeddyOmondi","description":"Locci Box is your Ai Agent's best code sandbox executions environment","archived":false,"fork":false,"pushed_at":"2026-05-24T11:51:14.000Z","size":1376,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-24T12:10:05.140Z","etag":null,"topics":["ai","ai-agents","libkrun","microvm","sandbox","vmm"],"latest_commit_sha":null,"homepage":"https://box.locci.cloud","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MikeTeddyOmondi.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-15T22:46:52.000Z","updated_at":"2026-05-24T11:51:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/MikeTeddyOmondi/locci-box","commit_stats":null,"previous_names":["miketeddyomondi/locci-box"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/MikeTeddyOmondi/locci-box","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeTeddyOmondi%2Flocci-box","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeTeddyOmondi%2Flocci-box/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeTeddyOmondi%2Flocci-box/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeTeddyOmondi%2Flocci-box/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MikeTeddyOmondi","download_url":"https://codeload.github.com/MikeTeddyOmondi/locci-box/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MikeTeddyOmondi%2Flocci-box/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33888302,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-04T02:00:06.755Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","libkrun","microvm","sandbox","vmm"],"created_at":"2026-06-04T04:02:09.075Z","updated_at":"2026-06-04T04:02:10.265Z","avatar_url":"https://github.com/MikeTeddyOmondi.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Locci Box\n\nA B2B platform that lets businesses and AI agents run untrusted code safely inside isolated microVMs using the [microsandbox SDK](https://github.com/superradcompany/microsandbox).\n\n## What's Inside\n\n| Package | Description |\n|---------|-------------|\n| `src/` | Express API — sandbox execution, JWT + API-key auth, multi-tenancy, MCP |\n| `web/` | TanStack Start web app — playground, code editor, auth UI |\n| `cli/` | `loccibox` CLI — compiled binary, API-key authenticated |\n| `.bob_sessions/` | Contains all the IBM Bob chat sessions |\n\n## Features\n\n- **Hardware-isolated execution** — every sandbox runs in its own microVM\n- **Sub-100ms boot times** — fast microVM startup via microsandbox\n- **Multi-tenant** — isolated sandboxes per organisation with usage limits\n- **Dual authentication** — JWT for the web app, API keys for the CLI / API\n- **Web playground** — run and test code in the browser\n- **MCP integration** — AI agents can call sandbox tools via Model Context Protocol\n- **Docker ready** — single `docker compose up` to run API + web\n\n## Supported Languages\n\n- Python\n- Node.js (JavaScript / TypeScript)\n- Bash\n- Ruby\n\n---\n\n## Quick Start\n\n### Prerequisites\n\n- **Node.js 22+** and **pnpm 9+**\n- **microsandbox CLI** — required for sandbox execution (KVM-based microVMs):\n  ```bash\n  curl -fsSL https://install.microsandbox.dev | sh\n  msb start          # start the microsandbox daemon\n  msb status         # verify it's running\n  ```\n  \u003e Requires Linux with KVM support (`/dev/kvm`). The daemon must be running before starting the API.\n\n### Development\n\n```bash\n# Clone\ngit clone https://github.com/MikeTeddyOmondi/locci-box.git\ncd locci-box\n\n# Install all workspace dependencies\npnpm install\n\n# Copy env and fill in values\ncp .env.example .env\n\n# Start API + web together\npnpm dev:all\n```\n\n| Service | URL |\n|---------|-----|\n| API | http://localhost:5757 |\n| Web | http://localhost:3000 |\n\n### Docker (recommended for production)\n\nSee [docs/DOCKER.md](./docs/DOCKER.md) for full instructions.\n\n```bash\n# 1. Install and start microsandbox daemon (on the host)\ncurl -fsSL https://install.microsandbox.dev | sh \u0026\u0026 msb start\n\n# 2. Configure and start\ncp .env.example .env   # fill in ADMIN_API_KEY and JWT_SECRET\ndocker compose up -d\n```\n\n| Service | URL |\n|---------|-----|\n| API | http://localhost:5757 |\n| Web | http://localhost:4173 |\n\n---\n\n## Authentication\n\n### Web App (JWT)\n\nThe web app authenticates via `POST /api/auth/login` or `POST /api/auth/register` and receives a 24-hour JWT stored in `localStorage`. A demo account (`demo@loccibox.dev` / `demo1234`) is seeded automatically.\n\n### CLI / API (API Key)\n\n```bash\nAuthorization: Bearer YOUR_API_KEY\n```\n\nThe default dev key is `sk_test_default_key_12345`. Generate production keys via the admin API.\n\n---\n\n## API Reference\n\n### Auth\n\n| Method | Path | Description |\n|--------|------|-------------|\n| POST | `/api/auth/register` | Create account → returns JWT |\n| POST | `/api/auth/login` | Sign in → returns JWT |\n| POST | `/api/auth/logout` | Invalidate session |\n\n### Sandbox\n\n| Method | Path | Auth | Description |\n|--------|------|------|-------------|\n| POST | `/api/sandbox/run` | JWT or API key | Execute code in microVM |\n| GET | `/api/sandbox/:id/status` | JWT or API key | Sandbox status |\n| DELETE | `/api/sandbox/:id` | JWT or API key | Stop sandbox |\n\n#### POST /api/sandbox/run\n\n```bash\ncurl -X POST http://localhost:5757/api/sandbox/run \\\n  -H \"Authorization: Bearer sk_test_default_key_12345\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"language\":\"python\",\"code\":\"print(\\\"Hello from microVM!\\\")\",\"timeout\":30}'\n```\n\n```json\n{\n  \"success\": true,\n  \"data\": {\n    \"sandbox_id\": \"sbox_abc123xyz\",\n    \"status\": \"completed\",\n    \"stdout\": \"Hello from microVM!\\n\",\n    \"stderr\": \"\",\n    \"exit_code\": 0,\n    \"duration_ms\": 87\n  }\n}\n```\n\n**Parameters:** `language` (`python` | `node` | `bash` | `ruby`), `code` (max 1 MB), `timeout` (seconds, default 30).\n\n### Admin\n\n| Method | Path | Auth | Description |\n|--------|------|------|-------------|\n| GET | `/api/metrics` | Admin API key | System-wide metrics |\n| GET | `/health` | — | Health check |\n\n---\n\n## CLI Tool\n\n```bash\n# Run interactively from the monorepo\ncd cli \u0026\u0026 pnpm install \u0026\u0026 pnpm build\n./loccibox --help\n\n# Or via Docker\ndocker compose --profile cli run --rm cli loccibox run -l python -c \"print('hi')\"\n```\n\n```bash\nloccibox init                                     # configure API URL + key\nloccibox run -l python -c \"print('hello')\"        # run code\nloccibox run -l node   -f script.js               # run file\nloccibox status \u003csandbox-id\u003e                      # check status\nloccibox metrics                                  # view usage\n```\n\nSee [cli/README.md](./cli/README.md) for full CLI docs.\n\n---\n\n## MCP Server\n\n```bash\npnpm mcp   # or: node dist/mcp/server.js\n```\n\nRegister with Claude Code:\n\n```bash\nclaude mcp add --transport stdio locci-box -- node dist/mcp/server.js\n```\n\nAvailable tools: `run_sandbox`, `get_sandbox_status`, `stop_sandbox`.\n\n---\n\n## Environment Variables\n\n```env\n# API\nPORT=5757\nNODE_ENV=development\nADMIN_API_KEY=admin_your_secret_key_here\nJWT_SECRET=locci-box-dev-secret-change-in-production\nDEFAULT_MAX_CONCURRENT_SANDBOXES=5\nDEFAULT_SANDBOX_TIMEOUT_SECONDS=30\nDEFAULT_RATE_LIMIT_PER_MINUTE=60\nLOG_LEVEL=info\n\n# Web app (browser)\nVITE_API_URL=http://localhost:5757\n\n# Docker Compose\nWEB_PORT=4173\nLOCCIBOX_API_URL=http://api:5757\n```\n\n---\n\n## Project Structure\n\n```\nlocci-box/\n├── src/                    # Express API\n│   ├── app.ts\n│   ├── server.ts\n│   ├── routes/\n│   │   ├── auth.ts         # JWT auth endpoints\n│   │   ├── sandbox.ts\n│   │   ├── metrics.ts\n│   │   └── health.ts\n│   ├── services/\n│   │   ├── UserService.ts  # In-memory user store + bcrypt\n│   │   ├── SandboxService.ts\n│   │   └── TenantService.ts\n│   ├── middleware/\n│   │   ├── auth.ts         # JWT + API-key dual auth\n│   │   ├── rateLimiter.ts\n│   │   └── errorHandler.ts\n│   ├── mcp/server.ts\n│   └── config/env.ts\n├── web/                    # TanStack Start web app\n│   ├── src/\n│   │   ├── routes/\n│   │   │   ├── index.tsx   # Landing page\n│   │   │   ├── login.tsx   # Sign in / register / demo\n│   │   │   ├── playground.tsx\n│   │   │   └── code.tsx\n│   │   ├── lib/auth.tsx    # Auth context + JWT helpers\n│   │   └── integrations/api/client.ts\n│   └── Dockerfile\n├── cli/                    # loccibox CLI\n│   ├── src/\n│   └── Dockerfile\n├── docs/                   # Documentation\n│   ├── DOCKER.md\n│   ├── QUICKSTART.md\n│   └── ...\n├── Dockerfile              # API image\n├── compose.yaml\n├── .env.example\n└── pnpm-workspace.yaml\n```\n\n---\n\n## Security\n\n- Hardware-isolated microVMs (no shared process risk)\n- JWT authentication for web users (24h expiry)\n- API key authentication for programmatic access\n- Per-tenant rate limiting and concurrent sandbox limits\n- Code size limits (1 MB max)\n- Execution timeout enforcement\n- Structured audit logging (Pino)\n\n---\n\n## Documentation\n\n| Doc | Description |\n|-----|-------------|\n| [docs/DOCKER.md](./docs/DOCKER.md) | Docker \u0026 Compose guide |\n| [docs/QUICKSTART.md](./docs/QUICKSTART.md) | Get started in 3 minutes |\n| [docs/SETUP.md](./docs/SETUP.md) | Detailed installation |\n| [docs/API_COLLECTION.md](./docs/API_COLLECTION.md) | curl examples for every endpoint |\n| [docs/ENV_CONFIGURATION.md](./docs/ENV_CONFIGURATION.md) | Environment variable reference |\n\n---\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiketeddyomondi%2Flocci-box","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmiketeddyomondi%2Flocci-box","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmiketeddyomondi%2Flocci-box/lists"}