Documentation

Everything needed to install it, embed it, or teach it a new language.

Install

The IDE and engine

pip install nishachar-ide

Requires Python 3.10 or newer. This gives you the nishachar command, the HTTP API, and the Python library.

The embeddable component

npm install @nishachar/ide

Or skip the install entirely and use a CDN:

<script type="module" src="https://cdn.jsdelivr.net/npm/@nishachar/ide"></script>

Container

docker run --rm -p 8777:8777 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/ni-sh-a-char/nishachar-ide:2.0.0 --runner docker --host 0.0.0.0

Mounting the Docker socket lets the server start a sandboxed container per language. Without it you still get the API and IDE, limited to the toolchains inside the image.

Quick start

nishachar                       # the IDE, in your browser
nishachar run hello.she         # language inferred from the extension
nishachar run -l rust -c 'fn main(){println!("hi")}'
nishachar languages             # what exists, and what you have installed

CLI reference

nishachar

With no arguments, starts the server and opens the IDE in your browser — the Jupyter model. There is no Electron download.

nishachar run

nishachar run FILE                 # infer language from extension
nishachar run FILE -l python       # force a language
nishachar run -l py -c 'print(1)'   # run a snippet
echo 'print(1)' | nishachar run -l py -   # read stdin

The exit code is the program's own exit code, so it composes with shell scripts and CI.

nishachar languages

Lists every registered language. A * marks the ones your machine can run right now. --available shows only those.

nishachar serve

The API without opening a browser.

Component API

<nishachar-ide> is a native custom element. It needs no framework wrapper because custom elements are part of the platform.

Attributes

Properties, methods and events

const ide = document.querySelector('nishachar-ide');

ide.value    = 'print("hello")';   // read/write the buffer
ide.language = 'python';
ide.stdin    = 'piped input';
await ide.run();                    // resolves with the result object
ide.focus();

ide.addEventListener('ready',  e => e.detail.languages);
ide.addEventListener('change', e => e.detail.code);
ide.addEventListener('run',    e => e.detail.language);
ide.addEventListener('result', e => e.detail.stdout);

Press Ctrl/Cmd + Enter in the editor to run.

Theming

nishachar-ide {
  --nsc-accent: #ff4f81;
  --nsc-bg: #000;
  --nsc-mono: 'JetBrains Mono', monospace;
  --nsc-radius: 4px;
  height: 600px;
}
nishachar-ide::part(toolbar) { border-bottom: 2px solid var(--nsc-accent); }

Exposed parts: toolbar, editor, output, run-button.

Python library

import nishachar

result = nishachar.run('say "hello"', "she")
result.stdout       # 'hello\n'
result.exit_code    # 0
result.duration_ms  # 158
result.ok           # True
result.timed_out    # False
result.truncated    # False

nishachar.run_file("script.rs", runner="docker", timeout=30)
nishachar.languages()        # every Language in the registry
nishachar.registry.require("go")

HTTP API

curl -X POST http://localhost:8777/api/run \
  -H 'content-type: application/json' \
  -d '{"language":"she","code":"say \"hi\"","stdin":"","timeout":10}'

{"stdout":"hi\n","stderr":"","exitCode":0,"durationMs":158,
 "timedOut":false,"truncated":false,"runner":"local","language":"she","ok":true}

Language registry

Every language is one JSON file. Adding one requires no source changes.

{
  "id": "ruby",
  "name": "Ruby",
  "extensions": [".rb"],
  "image": "ruby:3.3-slim",
  "run": ["ruby", "{file}"],
  "template": "puts \"Hello from Ruby!\"\n"
}

Placeholders substitute inside an argument, so "-o{bin}" works. Commands are argument vectors, never shell strings — nothing reaches a shell, so there is no quoting to get right and nothing to inject.

Full field reference and contribution guide →

Execution tiers

auto resolves per language: your local toolchain if you have it, a container if you don't. That is what lets Rust run on a machine with only Python installed.

Security

Server defaults are deliberately restrictive:

• The unsandboxed runner is refused off loopback unless explicitly overridden.
• CORS is closed. An open policy on a localhost server would let any page you visit execute code on your machine.
• The Host header is validated on loopback binds, which is what stops DNS rebinding.
• The terminal is off until --allow-shell.
• Every tier enforces a timeout and an output cap, and kills the whole process tree.

Full threat model, including what it does not protect against →

Self-hosting

Serving this to people you do not trust:

nishachar serve \
  --host 0.0.0.0 \
  --runner docker \          # never 'local'
  --timeout 10 \
  --cors https://your-site.example

Leave the terminal off, put it behind a reverse proxy with rate limiting, and run the whole thing inside a VM. Containers share a kernel; they are a strong boundary, not an absolute one.

Troubleshooting

“X is not installed or not on PATH”

The local toolchain is missing. Install it, or run with --runner docker to use a container instead.

The nishachar command isn't found after install

pip installed it somewhere off your PATH. python -m nishachar works identically, or add the reported scripts directory to PATH.

The first in-browser run is slow

Expected. Pyodide is a full CPython build and takes roughly three seconds to download and start. It is cached afterwards, and SHE adds about two more seconds the first time while micropip fetches it from PyPI.

The embedded component won't reach my server

CORS is closed by default. Start the server with --cors https://your-site.example.

The terminal shows no colours on Windows

ConPTY needs the optional dependency: pip install "nishachar-ide[pty]". Without it the terminal falls back to pipes, which run commands but have no TTY.