@aitty/server

Node runtime for hosting PTY-backed agent CLIs behind a loopback HTTP and WebSocket session.

Use this package in the host process that starts an agent such as Codex, Claude Code, or Factory Droid. Pair it with @aitty/browser in your frontend.

Install

npm i @aitty/server

Usage

import { createAittyServer, loadRuntimeDependencies } from "@aitty/server";

const dependencies = await loadRuntimeDependencies();

const session = await createAittyServer(
  {
    command: "codex",
    args: [],
    cwd: process.cwd(),
    publicHost: "codex.my-app.localhost",
    portless: {
      project: "my-app",
      label: "codex"
    },
    shell: {
      appearance: {
        theme: "dark"
      },
      title: "Codex",
      subtitle: "Browser terminal for Codex"
    }
  },
  dependencies
);

console.log(session.url);

await session.close();
await session.closed;

session.url contains the browser session path and token. Treat it as session-scoped local credentials.

portless controls the stable pathname only, for example /s/my-app/codex-<id>. Aitty still serves the session over HTTP/WebSocket, so the URL keeps an origin such as http://codex.my-app.localhost:<port>. Use publicHost to change the printed host, or publicOrigin when the session is mounted behind a reverse proxy or remote-control service.

Main Exports

• createAittyServer() starts the PTY, HTTP server, WebSocket transport, and default shell.
• loadRuntimeDependencies() loads @aitty/node-pty, ws, and open runtime dependencies.
• createBrowserShellHtml() renders the default embeddable shell document.
• createPtySession() and createOutputBuffer() are compatibility re-exports from @aitty/node-pty.
• createWebSocketTransport() exposes the lower-level WebSocket transport for custom hosts.
• createNetworkPolicy(), isHostAllowed(), and isOriginAllowed() validate loopback, public host, and explicit public origin access.

Notes

• Requires Node.js 20 or newer.
• The server defaults to loopback use. Bind to a LAN/public interface only when the host application explicitly owns that risk.
• Applications own browser opening, persistence, headers, and surrounding UI.

More Documentation

• Concepts and architecture
• Embedding and framework recipes
• Cloudflare Tunnel and Zero Trust

License

Apache-2.0