{"id":28446927,"url":"https://github.com/os-js/osjs-proc-provider","last_synced_at":"2025-06-30T06:32:26.423Z","repository":{"id":55552238,"uuid":"162915002","full_name":"os-js/osjs-proc-provider","owner":"os-js","description":"OS.js Process Service Provider","archived":false,"fork":false,"pushed_at":"2022-08-09T22:52:35.000Z","size":30,"stargazers_count":4,"open_issues_count":1,"forks_count":3,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-06-06T11:08:47.417Z","etag":null,"topics":["osjs","osjs-provider"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/os-js.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null},"funding":{"github":"andersevenrud","patreon":"andersevenrud","open_collective":"osjs","liberapay":"os-js","custom":"https://paypal.me/andersevenrud"}},"created_at":"2018-12-23T18:32:43.000Z","updated_at":"2023-12-14T06:20:01.000Z","dependencies_parsed_at":"2022-08-15T03:01:07.525Z","dependency_job_id":null,"html_url":"https://github.com/os-js/osjs-proc-provider","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/os-js/osjs-proc-provider","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/os-js%2Fosjs-proc-provider","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/os-js%2Fosjs-proc-provider/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/os-js%2Fosjs-proc-provider/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/os-js%2Fosjs-proc-provider/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/os-js","download_url":"https://codeload.github.com/os-js/osjs-proc-provider/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/os-js%2Fosjs-proc-provider/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260985060,"owners_count":23092880,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["osjs","osjs-provider"],"created_at":"2025-06-06T11:08:47.622Z","updated_at":"2025-06-30T06:32:26.412Z","avatar_url":"https://github.com/os-js.png","language":"JavaScript","funding_links":["https://github.com/sponsors/andersevenrud","https://patreon.com/andersevenrud","https://opencollective.com/osjs","https://liberapay.com/os-js","https://paypal.me/andersevenrud","https://www.patreon.com/user?u=2978551\u0026ty=h\u0026u=2978551","https://liberapay.com/os-js/"],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"OS.js Logo\" src=\"https://raw.githubusercontent.com/os-js/gfx/master/logo-big.png\" /\u003e\n\u003c/p\u003e\n\n[OS.js](https://www.os-js.org/) is an [open-source](https://raw.githubusercontent.com/os-js/OS.js/master/LICENSE) web desktop platform with a window manager, application APIs, GUI toolkit, filesystem abstractions and much more.\n\n[![Support](https://img.shields.io/badge/patreon-support-orange.svg)](https://www.patreon.com/user?u=2978551\u0026ty=h\u0026u=2978551)\n[![Support](https://img.shields.io/badge/opencollective-donate-red.svg)](https://opencollective.com/osjs)\n[![Donate](https://img.shields.io/badge/liberapay-donate-yellowgreen.svg)](https://liberapay.com/os-js/)\n[![Donate](https://img.shields.io/badge/paypal-donate-yellow.svg)](https://paypal.me/andersevenrud)\n[![Community](https://img.shields.io/badge/join-community-green.svg)](https://community.os-js.org/)\n\n# OS.js Proc Service Provider\n\nAdds support for spawning and piping processes and pseudo terminals on the node server.\n\nCommunicates via the internal websocket.\n\n## Installation\n\n```bash\nnpm install @osjs/proc-provider\n```\n\nIn your initialization scripts:\n\n```javascript\n// Client index.js file\nimport {ProcServiceProvider} from '@osjs/proc-provider';\nosjs.register(ProcServiceProvider);\n\n// Client index.scss file\n@import \"~@osjs/proc-provider/dist/main.css\";\n\n// Server index.js file\nconst {ProcServiceProvider} = require('@osjs/proc-provider/src/server.js');\nosjs.register(ProcServiceProvider);\n```\n\n## Configuration\n\nBy default the server provider is set up to only allow users with the `admin` group to access this feature.\n\nYou can change this by adding options:\n\n```javascript\nconst {ProcServiceProvider} = require('@osjs/proc-provider/src/server.js');\nosjs.register(ProcServiceProvider, {\n  args: {\n    groups: ['other-group']\n  }\n});\n```\n\n## API\n\nYou can reach this service with `core.make('osjs/proc')`.\n\n* `pty(cmd, ...args) =\u003e Promise\u003cp, Error\u003e` - Creates a new pseudo terminal over websocket\n* `spawn(cmd, ...args) =\u003e Promise\u003cp, Error\u003e` - Spawns a new process over websocket\n* `exec(cmd, ...args) =\u003e Promise\u003c{code, stdout, stderr}, Error\u003e` - Execs a process over http\n* `xterm(win[, options]) =\u003e Xterm` - Creates a new [xterm.js](https://github.com/xtermjs/xterm.js) class instance and bind it to a window\n\nThe `cmd` can either be a string, or an object: `{cmd: string, env: {A: 'value'}}`.\n\nThe `p` returned in a promise resolution is an `EventEmitter` with some special methods for interacting with the process.\n\n*See examples below*.\n\n### Pseudo terminal over websocket\n\nExecute a process, but inside a PTY. This makes it possible to use interactive processes.\n\n*Note that it is not possible to differentiate between stdout and stderr in this case.*\n\n```javascript\ncore.make('osjs/proc')\n  .pty('ls')\n  .then(p =\u003e {\n    // Process events\n    p.on('data', str =\u003e console.log(str))\n    p.on('exit', code =\u003e console.info(code))\n\n    // Internal events\n    p.on('spawned', () =\u003e {}); // Spawn successful\n    p.on('error', error =\u003e console.error(error)); // Spawn errors\n\n    // Send data to the shell\n    p.send('Hello World\\n');\n\n    // You can kill long running processes\n    p.kill();\n  })\n```\n\n### Execute over websocket\n\nExecute a process via standard node child_process.\n\n*Note that processes that requires an interactive shell won't work here. See PTY above.*\n\n```javascript\ncore.make('osjs/proc')\n  .spawn('ls')\n  .then(p =\u003e {\n    // Process events\n    p.on('stdout', str =\u003e console.log(str))\n    p.on('stderr', str =\u003e console.warn(str))\n    p.on('exit', code =\u003e console.info(code))\n\n    // Internal events\n    p.on('spawned', () =\u003e {}); // Spawn successful\n    p.on('error', error =\u003e console.error(error)); // Spawn errors\n\n    // You can kill long running processes\n    p.kill();\n  })\n```\n\n### Execute over http\n\nDirectly execute a program via child_process and return the result.\n\n```javascript\ncore.make('osjs/proc')\n  .exec('ls')\n  .then(({stdout, stderr, code}) =\u003e console.log(stdout, stderr, code))\n```\n\n### Passing arguments\n\n```javascript\ncore.make('osjs/proc')\n  .spawn('ls', '-l') // Works for all methods\n```\n\n### Passing environmental variables\n\nYou can also pass environmental data to all methods.\n\n```javascript\ncore.make('osjs/proc')\n  .spawn({cmd: 'ls', env: {foo: 'bar'}}) // Works for all methods\n```\n\n### Spawning windows to monitor output\n\nFor a PTY this also supports input. Just spawn a process as above, but:\n\n```javascript\ncore.make('osjs/proc')\n  .pty('ls')\n  .then(p =\u003e {\n    const win = p.createWindow({\n      // Keep window open for as long as you want\n      keepOpen: false\n    })\n\n    // Close window after 2.5s when command is complete\n    p.on('exit', () =\u003e setTimeout(() =\u003e win.destroy(), 2500))\n  })\n```\n\n### Attaching a shell via GUI\n\nYou can attach an Xterm (PTY recommended) to any arbitrary DOM element.\n\nThis example shows you how to use it in Hyperapp:\n\n\u003e Note that the `xterm` reference is a [xterm.js](https://github.com/xtermjs/xterm.js) class instance. The addon `fit` has been loaded and you can specify terminal options via the second argument: `.xterm(win, {terminal: {}})`.\n\n```javascript\nimport {h, app} from 'hyperapp';\nimport {Box} from '@osjs/gui';\n\n// Create a custom hyperapp component\n// The CSS is included by this provider\nconst XtermElement = props =\u003e h('div', {\n  class: 'osjs-gui osjs-gui-xterm',\n  oncreate: el =\u003e props.xterm.open(el),\n  onclick: () =\u003e props.xterm.focus()\n});\n\n// When you render your window, create a new Xterm reference\n// Then provide it as a reference to the component\nwin.render(($content, win) =\u003e {\n  const pp = core.make('osjs/proc');\n  const xterm = pp.xterm(win);\n  const hyperapp = app({}, {\n    runPty: () =\u003e {\n      pp.pty('ls', '-l')\n        .then(p =\u003e p.attachXterm(xterm))\n        .catch(error =\u003e console.error(error));\n    }\n  }, (state, actions) =\u003e {\n    return h(Box, {\n      grow: 1,\n      shrink: 1\n    }, h(XtermElement, {xterm}));\n  }, $content);\n\n  // Execute immediately. You can call this action from a button or whatever\n  // using components\n  hyperapp.runPty();\n});\n```\n\n## Features\n\n- Launch processes via websocket (pipeable)\n- Launch pseudo terminals via websocket (pipeable)\n- Launch process via http\n- Support for manually killing a running process\n- Server clears out stale processes (ex when client disconnects)\n- Works on all platforms\n\n## TODO\n\n- [ ] Add option for spawning standalone socket\n- [ ] Move the HTTP API purely to websocket signals ?\n- [ ] Add a system socket and host service\n- [ ] Add `shell` method for direct PTY\n\n## Contribution\n\n* **Sponsor on [Github](https://github.com/sponsors/andersevenrud)**\n* **Become a [Patreon](https://www.patreon.com/user?u=2978551\u0026ty=h\u0026u=2978551)**\n* **Support on [Open Collective](https://opencollective.com/osjs)**\n* [Contribution Guide](https://github.com/os-js/OS.js/blob/master/CONTRIBUTING.md)\n\n## Documentation\n\nSee the [Official Manuals](https://manual.os-js.org/) for articles, tutorials and guides.\n\n## Links\n\n* [Official Chat](https://gitter.im/os-js/OS.js)\n* [Community Forums and Announcements](https://community.os-js.org/)\n* [Homepage](https://os-js.org/)\n* [Twitter](https://twitter.com/osjsorg) ([author](https://twitter.com/andersevenrud))\n* [Google+](https://plus.google.com/b/113399210633478618934/113399210633478618934)\n* [Facebook](https://www.facebook.com/os.js.org)\n* [Docker Hub](https://hub.docker.com/u/osjs/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fos-js%2Fosjs-proc-provider","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fos-js%2Fosjs-proc-provider","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fos-js%2Fosjs-proc-provider/lists"}