> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentium.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Socket gateways

> Public socket gateways signatures and configuration in @agentium/transport 4.0.0.

Import these **10 exports** from `@agentium/transport`. Read the [socket gateways guide](/transport/socketio) for setup and behavior, or return to the [package reference](/api-reference/transport).

A `?` marks an optional field. These are declarations for lookup; run the examples in the linked guide. Follow related-type links for Agentium types and source links for imported dependency types.

## BrowserGatewayOptions

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/transport/src/socketio/browser-gateway.ts)

```typescript theme={null}
export interface BrowserGatewayOptions {
    /** Named BrowserAgent instances. Clients select one via agentName. */
    agents: Record<string, BrowserAgentLike>;
    /** Socket.IO server instance */
    io: any;
    /** Socket.IO namespace. Default: "/agentium-browser" */
    namespace?: string;
    /** Optional auth middleware applied to the namespace */
    authMiddleware?: (socket: any, next: (err?: Error) => void) => void;
    /**
     * Stream screenshots to the client in real-time.
     * Default: true. Disable for bandwidth-constrained clients.
     */
    streamScreenshots?: boolean;
}
```

Related: [`EventBus`](/api-reference/core/events#eventbus).

## createAgentGateway

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/transport/src/socketio/gateway.ts)

```typescript theme={null}
export declare function createAgentGateway(options: GatewayOptions): void;
```

Related: [`GatewayOptions`](/api-reference/transport/sockets#gatewayoptions).

## createBrowserGateway

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/transport/src/socketio/browser-gateway.ts)

```typescript theme={null}
/**
 * Create a Socket.IO gateway that streams BrowserAgent execution in real-time.
 *
 * ## Client → Server events
 * - `browser.start` — kick off a browser task
 * - `browser.stop`  — cancel a running task
 *
 * ## Server → Client events
 * - `browser.started`    — task accepted
 * - `browser.screenshot` — live screenshot (base64 PNG)
 * - `browser.action`     — action about to execute
 * - `browser.step`       — full step with screenshot + DOM
 * - `browser.done`       — task finished (result, success, duration, video)
 * - `browser.error`      — error occurred
 * - `browser.stopped`    — task was cancelled
 */
export declare function createBrowserGateway(opts: BrowserGatewayOptions): void;
```

Related: [`BrowserGatewayOptions`](/api-reference/transport/sockets#browsergatewayoptions).

## createVisionGateway

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/transport/src/socketio/vision-gateway.ts)

```typescript theme={null}
export declare function createVisionGateway(opts: VisionGatewayOptions): void;
```

Related: [`VisionGatewayOptions`](/api-reference/transport/sockets#visiongatewayoptions).

## createVoiceGateway

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/transport/src/socketio/voice-gateway.ts)

```typescript theme={null}
/** Bounded per-connection audio delivery; each output frame must be acknowledged by the client. */
export declare function createVoiceGateway(opts: VoiceGatewayOptions): void;
```

Related: [`VoiceGatewayOptions`](/api-reference/transport/sockets#voicegatewayoptions).

## GatewayOptions

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/transport/src/socketio/types.ts)

```typescript theme={null}
export interface GatewayOptions {
    security: GatewaySecurityOptions;
    /** Bounds apply per socket; outgoing frames use the Engine.IO drain contract. */
    textStream?: TextStreamLimits;
    maxConcurrentRuns?: number;
    /** Maximum collected final Agent text bytes. Default 256 KiB. */
    maxOutputBytes?: number;
    /**
     * Use a Registry for live auto-discovery. The gateway resolves agents/teams
     * at event time — any instance created after the gateway starts is automatically
     * reachable.
     *
     * When omitted, falls back to the global registry from `@agentium/core`.
     * Pass `false` to disable registry-based lookup (use explicit maps only).
     *
     * @example
     * createAgentGateway({ io, security: { mode: "local" } });
     * new Agent({ name: "bot", model: openai("gpt-4o") }); // immediately reachable
     */
    registry?: Registry | false;
    /**
     * Auto-discover agents and teams from a mixed array.
     * Each item is classified by its `.kind` and keyed by `.name`.
     */
    serve?: Servable[];
    agents?: Record<string, Agent | ServableAgent>;
    teams?: Record<string, Team>;
    io: any;
    namespace?: string;
    /** Must call next; thrown/rejected errors deny access. Returned promises settle before admission. */
    authMiddleware?: (socket: any, next: (err?: Error) => void) => void | Promise<void>;
    /** Max requests per minute per socket. Default: 60 */
    maxRequestsPerMinute?: number;
    /** Named tool library exposed via tools.list event. */
    toolLibrary?: Record<string, ToolDef>;
    /** Toolkit instances whose tools are exposed via tools.list. Merged with toolLibrary. */
    toolkits?: Toolkit[];
}
```

Related: [`Agent`](/api-reference/core/agent#agent), [`GatewaySecurityOptions`](/api-reference/transport/sockets#gatewaysecurityoptions), [`Registry`](/api-reference/core/serve#registry), [`Servable`](/api-reference/core/serve#servable), [`ServableAgent`](/api-reference/core/serve#servableagent), [`Team`](/api-reference/core/team#team), [`TextStreamLimits`](/api-reference/transport/streaming#textstreamlimits), [`ToolDef`](/api-reference/core/tools#tooldef), [`Toolkit`](/api-reference/core/toolkits#toolkit).

## GatewayResourceRequest

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/transport/src/socketio/types.ts)

```typescript theme={null}
export interface GatewayResourceRequest {
    identity: Readonly<HostedIdentity>;
    operation: "discover" | "execute" | "session:create" | "session:use" | "run:cancel";
    resource: {
        kind: "agent" | "team" | "workflow" | "tool" | "session" | "run";
        id: string;
        target?: string;
    };
}
```

Related: [`HostedIdentity`](/api-reference/transport/http#hostedidentity).

## GatewaySecurityOptions

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/transport/src/socketio/types.ts)

```typescript theme={null}
export type GatewaySecurityOptions = {
    mode: "local";
} | {
    mode: "authenticated";
    /** Read only host-verified socket.data, never handshake payload claims. */
    resolveIdentity: (verifiedState: unknown) => HostedIdentity | null | Promise<HostedIdentity | null>;
    /** session:create must atomically bind the generated ID; deny unknown session:use. */
    authorizeResource: (request: GatewayResourceRequest) => boolean | Promise<boolean>;
};
```

Related: [`GatewayResourceRequest`](/api-reference/transport/sockets#gatewayresourcerequest), [`HostedIdentity`](/api-reference/transport/http#hostedidentity).

## VisionGatewayOptions

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/transport/src/socketio/vision-gateway.ts)

```typescript theme={null}
export interface VisionGatewayOptions {
    agents: Record<string, VisionAgent>;
    io: any;
    namespace?: string;
    authMiddleware?: (socket: any, next: (err?: Error) => void) => void;
}
```

Related: [`VisionAgent`](/api-reference/core/vision#visionagent).

## VoiceGatewayOptions

[Source](https://github.com/agentiumOS/agentium/blob/v4.0.0/packages/transport/src/socketio/voice-gateway.ts)

```typescript theme={null}
export interface VoiceGatewayOptions {
    agents: Record<string, VoiceAgent>;
    io: any;
    namespace?: string;
    /** Establish trusted identity in socket.data.auth {userId,tenantId,sessionId}. */
    authMiddleware?: (socket: any, next: (err?: Error) => void) => void;
    maxAudioFrameBytes?: number;
    maxPendingAudioBytes?: number;
    playbackAckTimeoutMs?: number;
}
```

Related: [`VoiceAgent`](/api-reference/core/voice#voiceagent).

## Supporting types

These local shapes appear in public signatures but are not named exports of this entrypoint.

### BrowserAgentLike

```typescript theme={null}
/**
 * Minimal interface for a BrowserAgent — avoids a hard dependency on @agentium/browser.
 * Any object that matches this shape (e.g. a real BrowserAgent) works.
 */
interface BrowserAgentLike {
    name: string;
    eventBus: EventBus;
    run(task: string, opts?: {
        startUrl?: string;
        apiKey?: string;
        sessionId?: string;
    }): Promise<{
        result: string;
        success: boolean;
        finalUrl: string;
        durationMs: number;
        videoPath?: string;
        steps: Array<{
            index: number;
            action: unknown;
            screenshot: Buffer;
            pageUrl: string;
            pageTitle: string;
            dom?: string;
        }>;
    }>;
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.