@arcturn/server

Internal to the arcturn CLI. Published so arcturn resolves; its API may change in any release without a major version bump. Embedders should depend on @arcturn/core and @arcturn/ai, whose surfaces are the ones the SDK documents.

WebSocket server exposing Arcturn agent sessions. The same Agent that runs in the CLI or embedded via @arcturn/core can run behind this server and be driven remotely — a web UI, a mobile app, a teammate's editor — over the typed protocol defined by @arcturn/protocol. The CLI wires this together as arcturn serve.

What's in it

src/index.ts exports:

• SessionHost, SessionHostOptions, SessionHostError, SessionHostErrorCode, AgentFactoryOptions — manages live agent sessions independent of transport.
• ArcturnServer, ArcturnServerOptions, ArcturnServerStartOptions — a WebSocket server that exposes a SessionHost over JSON text frames validated against @arcturn/protocol's wire contracts.
• isAuthenticateFrame, tokensMatch, AuthenticateFrame — shared-token authentication for the first frame of a connection.

Install

Arcturn is not yet published to npm. Until it is, use it from a clone of the monorepo as a pnpm workspace package:

git clone https://github.com/sitharaj88/arcturn.git && cd arcturn
pnpm install && pnpm -r build

Then depend on it from another workspace package: "@arcturn/server": "workspace:*".

Usage

import { ArcturnServer } from "@arcturn/server";
import type { SessionHost } from "@arcturn/server";

declare const sessionHost: SessionHost; // built from your own AgentFactoryOptions

const server = new ArcturnServer({
  sessionHost,
  token: "a-shared-secret", // omit only for an explicitly unauthenticated loopback server
});

const port = await server.start({ host: "127.0.0.1", port: 0 });
console.log(`listening on ws://127.0.0.1:${port}`);

Read this before binding anything other than loopback: a connection that completes authentication (or, when no token is configured, any connection) gets full tool execution as the process running the server. Binding a non-loopback interface with no token is a hard refusal at construction time.

Docs

• Server mode — flags, the wire protocol, authentication, and the full threat model behind arcturn serve.
• Embedding with the SDK — how this package fits with the rest of the runtime.

License

Apache-2.0 — see LICENSE.

👤 Author

Sitharaj Seenivasan

• 🌐 Website: sitharaj.in
• 💼 LinkedIn: sitharaj08
• 💻 GitHub: sitharaj88

☕ Support

If this project helps you, consider buying me a coffee — it keeps the work going.

📄 License

Licensed under the Apache License 2.0. © 2026 Sitharaj Seenivasan.