{"_id":"@cogineai/mafs-server","name":"@cogineai/mafs-server","dist-tags":{"alpha":"0.1.0-alpha.0","latest":"0.1.0-alpha.0"},"versions":{"0.1.0-alpha.0":{"name":"@cogineai/mafs-server","version":"0.1.0-alpha.0","description":"mafs daemon server for agent workspace filesystems","keywords":["bash","fuse","typescript","vfs","ai-agents","agent-sandbox","langchain","virtual-filesystem","llm-agents","agent-tools","claude-code","openai-agents"],"homepage":"https://github.com/cogine-ai/CogineX-mono#readme","bugs":{"url":"https://github.com/cogine-ai/CogineX-mono/issues"},"repository":{"type":"git","url":"git+https://github.com/cogine-ai/CogineX-mono.git","directory":"packages/mafs/typescript/packages/server"},"license":"Apache-2.0","author":{"name":"lc708","email":"kiedis@foxmail.com"},"publishConfig":{"access":"public"},"type":"module","main":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js"},"./package.json":"./package.json","./bin/daemon":"./dist/bin/daemon.js"},"bin":{"mafs-daemon":"dist/bin/daemon.js"},"dependencies":{"fastify":"^5.8.5","@fastify/multipart":"^10.0.0","yaml":"^2.6.0","@cogineai/mafs-core":"0.1.0-alpha.0","@cogineai/mafs-node":"0.1.0-alpha.0"},"devDependencies":{"@types/node":"^22.0.0","tsup":"^8.5.0","typescript":"^6.0.0","vitest":"^3.0.0"},"scripts":{"build":"tsup","test":"vitest run","typecheck":"tsc --noEmit"},"_id":"@cogineai/mafs-server@0.1.0-alpha.0","_integrity":"sha512-prgYC7J2rTPGTwdwyQnVOW7u1IXaY7c5UZE9NXWz4BdAXBOJrpUEqUmSOc2kzRELLGj8JqN1GzoVvVBj7NgQwg==","_resolved":"/private/var/folders/w3/1jnv2n65319gjrn7xmghv87m0000gn/T/6d7fc4e6b60c1dc07dc6db808c98468a/cogineai-mafs-server-0.1.0-alpha.0.tgz","_from":"file:cogineai-mafs-server-0.1.0-alpha.0.tgz","_nodeVersion":"22.16.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-prgYC7J2rTPGTwdwyQnVOW7u1IXaY7c5UZE9NXWz4BdAXBOJrpUEqUmSOc2kzRELLGj8JqN1GzoVvVBj7NgQwg==","shasum":"2d8af33dde0bb87025fbabe4e5189203facdfcc8","tarball":"https://registry.npmjs.org/@cogineai/mafs-server/-/mafs-server-0.1.0-alpha.0.tgz","fileCount":11,"unpackedSize":118225,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIGwxQPZlaZP5BqompcqPBVH8EoXRJXclu1G2nJiUDo83AiEA0lr10fa31Vwc+8GlVhvtyEzHvB25XPR2LMGo72AJ7QM="}]},"_npmUser":{"name":"lc708","email":"kiedis@foxmail.com"},"directories":{},"maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mafs-server_0.1.0-alpha.0_1779464758830_0.4962378628678483"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-22T15:45:58.650Z","0.1.0-alpha.0":"2026-05-22T15:45:59.001Z","modified":"2026-05-22T15:45:59.296Z"},"maintainers":[{"name":"lc708","email":"kiedis@foxmail.com"}],"description":"mafs daemon server for agent workspace filesystems","homepage":"https://github.com/cogine-ai/CogineX-mono#readme","keywords":["bash","fuse","typescript","vfs","ai-agents","agent-sandbox","langchain","virtual-filesystem","llm-agents","agent-tools","claude-code","openai-agents"],"repository":{"type":"git","url":"git+https://github.com/cogine-ai/CogineX-mono.git","directory":"packages/mafs/typescript/packages/server"},"author":{"name":"lc708","email":"kiedis@foxmail.com"},"bugs":{"url":"https://github.com/cogine-ai/CogineX-mono/issues"},"license":"Apache-2.0","readme":"# @cogineai/mafs-server\n\n[![npm version](https://img.shields.io/npm/v/%40cogineai%2Fmafs-server.svg)](https://www.npmjs.com/package/@cogineai/mafs-server)\n[![License](https://img.shields.io/npm/l/%40cogineai%2Fmafs-server.svg)](https://github.com/cogine-ai/CogineX-mono/blob/main/packages/mafs/LICENSE)\n\n`mafs-daemon` — a Fastify-based HTTP server that exposes MAFS Workspaces over a stable JSON API, plus the building blocks to embed that API into your own Fastify app.\n\nThis is the daemon backing the [`mafs`](../cli) CLI. It's also how non-TypeScript clients talk to MAFS: the [Python bridge](https://github.com/cogine-ai/CogineX-mono/tree/main/packages/mafs/python) uses these endpoints, browser apps proxy through them when they need Node-only resources, and the CogineX control plane uses the daemon as its data-plane HTTP boundary.\n\n## Install\n\n```bash\n# As a global CLI:\nnpm install -g @cogineai/mafs-server\n\n# As a library (embed the routes into your own Fastify app):\nnpm install @cogineai/mafs-server\n```\n\nRequires Node.js ≥ 20.\n\n## Run the daemon\n\n```bash\nmafs-daemon\n# starts on 127.0.0.1:8765 by default\n\n# Or via npx without a global install:\nnpx @cogineai/mafs-server\n```\n\nConfiguration is via environment variables:\n\n| Env                       | Default    | Description                                                                                         |\n| ------------------------- | ---------- | --------------------------------------------------------------------------------------------------- |\n| `MAFS_DAEMON_PORT`        | `8765`     | Listen port.                                                                                        |\n| `MAFS_ALLOWED_HOSTS`      | _loopback_ | Comma-separated Host-header allow-list (DNS rebinding protection).                                  |\n| `MAFS_PERSIST_DIR`        | _disabled_ | When set, the daemon snapshots / restores workspace state to this directory across restarts.        |\n| `MAFS_IDLE_GRACE_SECONDS` | `30`       | Seconds without a workspace before the daemon self-exits; also the grace window after the last one. |\n\nThe daemon always binds to `127.0.0.1`; for non-loopback exposure, run behind a reverse proxy and set `MAFS_ALLOWED_HOSTS` accordingly.\n\nThe daemon is loopback-only by default and rejects any HTTP request whose `Host` header is not in `MAFS_ALLOWED_HOSTS`. This prevents [DNS rebinding attacks](https://github.com/cogine-ai/CogineX-mono/blob/main/packages/mafs/typescript/packages/server/src/host_validation.ts) when developers run the daemon alongside a browser.\n\n## HTTP API\n\nAll routes are mounted under the `/v1` prefix.\n\n| Path                                       | Methods         | Description                                                                |\n| ------------------------------------------ | --------------- | -------------------------------------------------------------------------- |\n| `/v1/health`                               | `GET`           | Liveness probe.                                                            |\n| `/v1/shutdown`                             | `POST`          | Trigger graceful shutdown.                                                 |\n| `/v1/workspaces`                           | `POST`          | Create a workspace from a `CreateWorkspaceRequest` (`{ id?, config }`).    |\n| `/v1/workspaces`                           | `GET`           | List workspaces (brief shape).                                             |\n| `/v1/workspaces/{id}`                      | `GET`           | Inspect a workspace; pass `?verbose=true` for cache / history internals.   |\n| `/v1/workspaces/{id}`                      | `DELETE`        | Stop and destroy a workspace.                                              |\n| `/v1/workspaces/{id}/snapshot`             | `GET`           | Stream a tar snapshot of the workspace as the response body.               |\n| `/v1/workspaces/load`                      | `POST`          | Load a workspace from a multipart tar (`tar` + optional `id`, `override`). |\n| `/v1/workspaces/{id}/clone`                | `POST`          | Clone a workspace with optional `override`.                                |\n| `/v1/workspaces/{id}/refresh`              | `POST`          | Clear file / index cache for a workspace path (`{ path? }`).               |\n| `/v1/workspaces/{id}/execute`              | `POST`          | Run a shell command (sync; pass `?background=true` to return a `jobId`).   |\n| `/v1/workspaces/{id}/sessions`             | `POST`, `GET`   | Create / list sessions.                                                    |\n| `/v1/workspaces/{id}/sessions/{sessionId}` | `DELETE`        | End a session.                                                             |\n| `/v1/jobs`                                 | `GET`           | List jobs (`?workspaceId=` filter).                                        |\n| `/v1/jobs/{id}`                            | `GET`, `DELETE` | Inspect or cancel a job spawned by `execute`.                              |\n| `/v1/jobs/{id}/wait`                       | `POST`          | Block until a job completes (optional `{ timeoutS }`).                     |\n\nAll requests and responses are JSON; the canonical shapes are in [`packages/server/src/schemas.ts`](https://github.com/cogine-ai/CogineX-mono/blob/main/packages/mafs/typescript/packages/server/src/schemas.ts).\n\n## Use programmatically\n\n`buildApp` returns a fully-built Fastify instance. Call it from your own bootstrap when you want full control over the listen address, logging, persistence directory, or DNS-rebinding allow-list:\n\n```ts\nimport { buildApp } from '@cogineai/mafs-server'\n\nconst app = buildApp({\n  persistDir: '/var/lib/myapp/mafs',\n  idleGraceSeconds: 60,\n  allowedHosts: ['mafs.internal'], // or ['*'] behind a trusted reverse proxy\n})\n\nawait app.restorePromise // wait for any persisted workspaces to restore\nawait app.listen({ port: 8765, host: '127.0.0.1' })\n```\n\nThe package also exports config helpers — `loadWorkspaceConfig`, `interpolateEnv`, `configToWorkspaceArgs`, and types `WorkspaceConfigRaw`, `WorkspaceArgs`, `MountBlock` — that the [`@cogineai/mafs-cli`](../cli) `mafs workspace create` command uses to load a YAML/JSON workspace descriptor into the `config` field of the create request. They are useful if you want to construct create-request bodies in your own clients.\n\nThere is no public router-by-router embed API: the daemon is shipped as one cohesive Fastify instance and is intended to run standalone (process or sidecar).\n\n## Quick start — create, execute, snapshot\n\n```bash\n# The daemon auto-spawns on the first command that needs it.\nmafs workspace create ws.yaml --id demo\nmafs execute --workspace demo --command 'echo hello > /data/hello.txt && cat /data/hello.txt'\nmafs workspace snapshot demo demo.tar\n```\n\nOr hit the HTTP API directly:\n\n```bash\n# Health.\ncurl -fsSL http://127.0.0.1:8765/v1/health\n\n# Create. The body matches CreateWorkspaceRequest = { id?, config }.\ncurl -fsSL http://127.0.0.1:8765/v1/workspaces \\\n  -H 'Content-Type: application/json' \\\n  --data '{\"id\":\"demo\",\"config\":{\"mounts\":{\"/data\":{\"type\":\"ram\"}},\"mode\":\"write\"}}'\n\n# Execute (synchronous; pass ?background=true to get a jobId back instead).\ncurl -fsSL http://127.0.0.1:8765/v1/workspaces/demo/execute \\\n  -H 'Content-Type: application/json' \\\n  --data '{\"command\":\"echo hello > /data/hello.txt && cat /data/hello.txt\"}'\n```\n\n## Companion packages\n\n- [`@cogineai/mafs-cli`](../cli) — `coginex` + `mafs` binaries (the `mafs` CLI talks to this daemon).\n- [`@cogineai/mafs-core`](../core) — runtime-agnostic primitives the daemon serves over HTTP.\n- [`@cogineai/mafs-node`](../node) — Node resources used by the daemon to back workspaces.\n- [`@cogineai/mafs-browser`](../browser) — browser bundle that can talk to this daemon when it needs Node-only resources.\n- [`@cogineai/mafs-agents`](../agents) — adapters for agent frameworks.\n\n## License & attribution\n\nApache-2.0. MAFS is a fork of [Mirage](https://github.com/strukto-ai/mirage); see the project-level [`NOTICE`](https://github.com/cogine-ai/CogineX-mono/blob/main/packages/mafs/NOTICE) for attribution and the relationship to upstream.\n","readmeFilename":"README.md","_rev":"1-bdd829ba60d8e01f8a4435d8e5105ab7"}