{"id":21070381,"url":"https://github.com/stencila/executa","last_synced_at":"2025-08-16T16:07:46.153Z","repository":{"id":35839367,"uuid":"211765515","full_name":"stencila/executa","owner":"stencila","description":"⚡ Execution engine for executable documents","archived":false,"fork":false,"pushed_at":"2025-04-16T11:01:50.000Z","size":3306,"stargazers_count":7,"open_issues_count":41,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-16T14:43:30.674Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stencila.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"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}},"created_at":"2019-09-30T03:11:15.000Z","updated_at":"2025-02-26T18:06:26.000Z","dependencies_parsed_at":"2023-11-11T02:21:04.002Z","dependency_job_id":"65f4d590-963f-45f3-8852-d98e0f36cb3d","html_url":"https://github.com/stencila/executa","commit_stats":null,"previous_names":[],"tags_count":72,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Fexecuta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Fexecuta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Fexecuta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stencila%2Fexecuta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stencila","download_url":"https://codeload.github.com/stencila/executa/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254473763,"owners_count":22077165,"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":[],"created_at":"2024-11-19T18:46:44.093Z","updated_at":"2025-05-16T05:30:44.499Z","avatar_url":"https://github.com/stencila.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ⚡ Executa\n\n#### Execution engine for executable documents\n\n[![Build Status](https://dev.azure.com/stencila/stencila/_apis/build/status/stencila.executa?branchName=master)](https://dev.azure.com/stencila/stencila/_build/latest?definitionId=4\u0026branchName=master)\n[![Code coverage](https://codecov.io/gh/stencila/executa/branch/master/graph/badge.svg)](https://codecov.io/gh/stencila/executa)\n[![NPM](https://img.shields.io/npm/v/@stencila/executa.svg?style=flat)](https://www.npmjs.com/package/@stencila/executa)\n\n## Install\n\n```bash\nnpm install --global @stencila/executa\n```\n\n## Use\n\n\u003c!-- prettier-ignore-start --\u003e\n\u003c!-- CONFIGA-USAGE-BEGIN --\u003e\nAll configuration options can be set, in descending order of priority, by:\n\n- a command line argument e.g. `--\u003cvalue\u003e \u003cvalue\u003e`\n- an environment variable prefixed with `EXECUTA_` e.g. `EXECUTA_\u003coption\u003e=\u003cvalue\u003e`\n- a `.json` or `.ini` configuration file, set using the `--config` option, or `.executarc` by default\n\u003c!-- CONFIGA-USAGE-END --\u003e\n\n\u003c!-- CONFIGA-TABLE-BEGIN --\u003e\n| Name          | Description                                                                                            | Type               | Validators                                                 | Default         |\n| ------------- | ------------------------------------------------------------------------------------------------------ | ------------------ | ---------------------------------------------------------- | --------------- |\n| debug         | Display debug log data?                                                                                | `boolean`          |                                                            | `false`         |\n| stdio         | Start a `stdio` server.                                                                                | `boolean`          |                                                            | `false`         |\n| vsock         | Start a `vsock` server.\u003ca href=\"#vsock-details\"\u003e\u003csup\u003e1\u003c/sup\u003e\u003c/a\u003e                                       | `boolean | number` |                                                            | `false`         |\n| tcp           | Start a TCP server.\u003ca href=\"#tcp-details\"\u003e\u003csup\u003e2\u003c/sup\u003e\u003c/a\u003e                                             | `boolean | string` | pattern: `/^((tcp?://)?([^:/]+)(:(d+))?(/(.+))?)|(d+)$/`   | `false`         |\n| http          | Start a HTTP server.\u003ca href=\"#http-details\"\u003e\u003csup\u003e3\u003c/sup\u003e\u003c/a\u003e                                           | `boolean | string` | pattern: `/^((https?://)?([^:/]+)(:(d+))?(/(.+))?)|(d+)$/` | `false`         |\n| ws            | Start a WebSocket server.\u003ca href=\"#ws-details\"\u003e\u003csup\u003e4\u003c/sup\u003e\u003c/a\u003e                                        | `boolean | string` | pattern: `/^((wss?://)?([^:/]+)(:(d+))?(/(.+))?)|(d+)$/`   | `false`         |\n| timeout       | Duration of inactivity after which the process should stop.\u003ca href=\"#timeout-details\"\u003e\u003csup\u003e5\u003c/sup\u003e\u003c/a\u003e | `number`           |                                                            | `0`             |\n| timelimit     | Maximum duration for the process.\u003ca href=\"#timelimit-details\"\u003e\u003csup\u003e6\u003c/sup\u003e\u003c/a\u003e                         | `number`           |                                                            | `0`             |\n| peers         | List of peer addresses.\u003ca href=\"#peers-details\"\u003e\u003csup\u003e7\u003c/sup\u003e\u003c/a\u003e                                       | `string[]`         |                                                            | `[\"stdio://*\"]` |\n| queueLength   | Maximum length of the request queue.\u003ca href=\"#queueLength-details\"\u003e\u003csup\u003e8\u003c/sup\u003e\u003c/a\u003e                    | `number`           | minimum: `0`                                               | `1000`          |\n| queueInterval | Interval between attempts to reduce request queue.\u003ca href=\"#queueInterval-details\"\u003e\u003csup\u003e9\u003c/sup\u003e\u003c/a\u003e    | `number`           | exclusiveMinimum: `0`                                      | `1`             |\n| queueStale    | Duration after which a request is removed from queue.\u003ca href=\"#queueStale-details\"\u003e\u003csup\u003e10\u003c/sup\u003e\u003c/a\u003e   | `number`           | exclusiveMinimum: `0`                                      | `3600`          |\n\n\n1. \u003ca id=\"vsock-details\"\u003e\u003c/a\u003eIf a `number`, it will be used as the port number.\nIf `true`, the default Vsock port `6000` will be used.\n2. \u003ca id=\"tcp-details\"\u003e\u003c/a\u003eIf a `string`, it will be parsed and used as the address\nof the TCP server.\nIf `true`, the default TCP address `tcp://127.0.0.1:7000`\nwill be used.\n3. \u003ca id=\"http-details\"\u003e\u003c/a\u003eIf a `string`, it will be parsed and used as the address\nof the HTTP server.\nIf `true`, the default HTTP address `http://127.0.0.1:8000`\nwill be used.\n4. \u003ca id=\"ws-details\"\u003e\u003c/a\u003eIf a `string`, it will be parsed and used as the address\nof the WebSocket server.\nIf `true`, the default WebSocket address `ws://127.0.0.1:9000`\nwill be used.\n5. \u003ca id=\"timeout-details\"\u003e\u003c/a\u003eSeconds. Zero means no timeout.\n6. \u003ca id=\"timelimit-details\"\u003e\u003c/a\u003eSeconds. Zero means no time limit.\n7. \u003ca id=\"peers-details\"\u003e\u003c/a\u003eEach string in this list is parsed as an address to\na peer executor. e.g. `https://123.45.67.89/`, `docker://image`\n8. \u003ca id=\"queueLength-details\"\u003e\u003c/a\u003eWhen queue reaches this length, subsequent requests will\nfail with an error response to client.\n9. \u003ca id=\"queueInterval-details\"\u003e\u003c/a\u003eSeconds.\n10. \u003ca id=\"queueStale-details\"\u003e\u003c/a\u003eSeconds. Client will be notified when a request is removed.\n\n\u003c!-- CONFIGA-TABLE-END --\u003e\n\u003c!-- prettier-ignore-end --\u003e\n\n## Develop\n\n### Testing with the REPL\n\nThere is an interactive REPL that can be used with the both `query` and `execute` CLI commands e.g.\n\n```bash\nnpm run cli -- execute --repl --debug\n```\n\n### Testing in the browser\n\n1. Serve Executa over HTTP (to provide static HTML) and WebSocket (to provide JSON RPC):\n\n   ```bash\n   npm run cli:dev -- serve --http --ws\n   ```\n\n\u003e The `:dev` suffix to `cli` uses `ts-node-dev` which will restart the process when any source files change.\n\n2. Visit http://localhost:8000 in your browser and play around with the `\u003cstencila-code-chunk\u003e` WebComponent that is connected to the Executa WebSocket that you just started.\n\n![](.github/executa-in-browser.png)\n\n### Debug inspecting\n\nThere is a NPM script, `cli:debug`, that can be useful for debugging the CLI, for example, from within VSCode (which will auto attach to the Node process), e.g.\n\n```bash\nnpm run cli:debug -- serve --http\n```\n\n\u003e The `:debug` suffix to `cli` enables the Node [debug inspector](https://nodejs.org/en/docs/guides/debugging-getting-started/) so you can use your favorite IDE to attach to the CLI and step through the code.\n\n## FAQ\n\n#### Why is `@types/ws` a production dependency?\n\nThis package has several dependents e.g `@stencila/basha`. If `@types/ws` is not installed as a production dependency,\nwhen you try to build dependent packages, you get the error \"Cannot find type definition file for 'ws'.\". By having it\nas a production dependency here, each dependent package does not have to install it as a development dependency.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstencila%2Fexecuta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstencila%2Fexecuta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstencila%2Fexecuta/lists"}