inbash

Telegram-native operating runtime engine.

Turns Telegram into a virtual filesystem, command shell, and distributed OS-like environment over MTProto (powered by GramJS).

Overview

Telegram chats     → filesystem directories
Forum topics       → subdirectories
Messages           → files
Commands           → shell programs
Sessions           → kernel processes

Installation

npm install inbash
# or
pnpm add inbash

Node.js ≥ 18 required.

Quick Start

import { InbashCore } from "inbash";

const shell = new InbashCore({
  sessions: [
    {
      id: "primary",
      kind: "user",
      credential: process.env.TG_SESSION!,   // GramJS StringSession
      apiId: Number(process.env.TG_API_ID),
      apiHash: process.env.TG_API_HASH!,
    },
  ],
});

await shell.connect();

// List all chats (root of the virtual FS)
const { output } = await shell.exec("ls /");
console.log(output);

// Navigate into a chat
await shell.exec("cd my_channel");

// Read a message
await shell.exec("fetch 12345");

// Runtime statistics
await shell.exec("stats");

// Graceful shutdown
await shell.shutdown();

Bot Mode

const shell = new InbashCore({
  sessions: [
    {
      id: "bot",
      kind: "bot",
      credential: process.env.BOT_TOKEN!,
      apiId: Number(process.env.TG_API_ID),
      apiHash: process.env.TG_API_HASH!,
    },
  ],
});

Multi-Session Pool

const shell = new InbashCore({
  sessions: [
    { id: "user-1", kind: "user", credential: SESSION_1, apiId, apiHash, weight: 2 },
    { id: "user-2", kind: "user", credential: SESSION_2, apiId, apiHash, weight: 1 },
    { id: "bot-1",  kind: "bot",  credential: BOT_TOKEN, apiId, apiHash, weight: 1 },
  ],
  queueConcurrency: 10,
  retryMaxAttempts: 5,
});

Sessions are selected via weighted round-robin. Rate-limited sessions are automatically skipped until the window expires.

Built-in Commands

| Command | Aliases | Description | |---------|---------|-------------| | ls [path] | list, dir | List contents of a virtual FS path | | cd <path> | chdir | Change working directory | | fetch <path> | cat, read | Read a message's content | | stats | info, status | Runtime and FS statistics | | pwd | — | Print current working directory |

Plugin System

import type { Plugin } from "inbash";

const myPlugin: Plugin = {
  name: "greet",
  version: "1.0.0",
  description: "Greeting commands",
  commands: [
    {
      name: "hello",
      description: "Say hello",
      args: [{ name: "name", required: false }],
      async handler(ctx) {
        const name = ctx.args[0] ?? "world";
        return { output: `Hello, ${name}!`, exitCode: 0 };
      },
    },
  ],
};

await shell.loadPlugin(myPlugin);
const result = await shell.exec("hello Alice");
// → "Hello, Alice!"

XML Command Definitions

<!-- commands.xml -->
<commands>
  <command name="greet" plugin="demo">
    <description>Greet a user</description>
    <args>
      <arg name="name" required="true">
        <description>Name to greet</description>
      </arg>
    </args>
  </command>
</commands>

import { readFileSync } from "fs";

shell.loadCommandsFromXml(readFileSync("commands.xml", "utf8"), {
  greet: async (ctx) => ({
    output: `Hello, ${ctx.args[0] ?? "stranger"}!`,
    exitCode: 0,
  }),
});

Events

shell.events.on("message", (event) => {
  console.log("New message:", event.text, "from", event.chatId);
});

shell.events.on("command", (event) => {
  console.log(`[${event.sessionId}] ${event.command} → exit ${event.result.exitCode} (${event.durationMs}ms)`);
});

shell.events.on("sessionRotate", (event) => {
  console.log(`Session rotated: ${event.fromSessionId} → ${event.toSessionId} (${event.reason})`);
});

shell.events.on("rateLimit", (event) => {
  console.warn(`Rate limited on session "${event.sessionId}" for ${event.retryAfterMs}ms`);
});

API Reference

InbashCore

| Method | Returns | Description | |--------|---------|-------------| | connect() | Promise<void> | Connect all sessions | | shutdown() | Promise<void> | Drain queue and disconnect | | exec(line) | Promise<{output, exitCode}> | Run a shell command | | loadPlugin(plugin) | Promise<void> | Load a plugin | | unloadPlugin(name) | Promise<void> | Unload a plugin | | loadCommandsFromXml(xml, handlers) | void | Load XML command definitions |

SessionManager

| Method | Description | |--------|-------------| | connectAll() | Connect all sessions | | disconnectAll() | Disconnect all sessions | | selectSession(reason?) | Round-robin session picker | | selectLeastLoaded() | Pick the least-busy session | | addSession(config) | Hot-add a session at runtime | | removeSession(id) | Hot-remove a session | | getStates() | Snapshot of all session states |

TelegramFS

| Method | Description | |--------|-------------| | resolve(path) | Resolve a path to an FSNode | | listChildren(path) | List children of a directory node | | upsert(node) | Insert or update a node in cache | | invalidate(path) | Clear cached entries for a path | | getStats() | Return FS node counts |

Integration with inbash-search

import { InbashCore } from "inbash";
import { InbashSearch } from "inbash-search";

const shell = new InbashCore({ sessions: [...] });
const search = new InbashSearch(shell);

await shell.connect();
await search.startIndexing();

const results = await search.search("typescript tutorial");
const tagged  = await search.searchTag("python");
const stats   = await search.getStats();

Environment Variables

| Variable | Description | |----------|-------------| | TG_API_ID | Telegram API ID from my.telegram.org | | TG_API_HASH | Telegram API hash | | TG_SESSION | GramJS StringSession string (user mode) | | BOT_TOKEN | Bot token from @BotFather (bot mode) |

License

MIT