Server Mode — Run bunqueue as a Standalone TCP & HTTP Service

Run bunqueue as a standalone server with HTTP and TCP APIs.

Starting the Server

# Default ports (TCP: 6789, HTTP: 6790)
bunqueue

# With custom configuration
bunqueue start \
  --tcp-port 6789 \
  --http-port 6790 \
  --data-path ./data/queue.db

# With authentication
AUTH_TOKENS=secret1,secret2 bunqueue

Configuration File

The recommended way to configure bunqueue is with a bunqueue.config.ts file in your project root:

import { defineConfig } from 'bunqueue';

export default defineConfig({
  server: { tcpPort: 6789, httpPort: 6790 },
  auth: { tokens: ['my-secret-token'] },
  storage: { dataPath: './data/queue.db' },
  cloud: {
    url: 'https://cloud.bunqueue.io',
    apiKey: process.env.BUNQUEUE_CLOUD_API_KEY,
  },
});

Then just run bunqueue start — the config file is auto-discovered. See Configuration File for the full reference.

Environment Variables

Environment variables still work as fallback when no config file is present.

Variable	Default	Description
`TCP_PORT`	`6789`	TCP server port
`HTTP_PORT`	`6790`	HTTP server port
`HOST`	`0.0.0.0`	Server hostname
`DATA_PATH`	(memory)	SQLite database path
`AUTH_TOKENS`	(none)	Comma-separated auth tokens
`CORS_ALLOW_ORIGIN`	`(none)`	CORS allowed origins
`LOG_FORMAT`	`text`	Log format (text/json)

See Environment Variables for the complete reference.

Docker

FROM oven/bun:latest
WORKDIR /app
COPY package.json bun.lockb ./
RUN bun install --production
COPY . .
EXPOSE 6789 6790
CMD ["bun", "run", "src/main.ts"]

docker build -t bunqueue .
docker run -p 6789:6789 -p 6790:6790 \
  -v ./data:/app/data \
  -e DATA_PATH=/app/data/queue.db \
  bunqueue

Connecting from Client

When the server is running, clients connect automatically via TCP:

import { Queue, Worker } from 'bunqueue/client';

// No embedded option = TCP mode (connects to localhost:6789)
const queue = new Queue('tasks');
const worker = new Worker('tasks', async (job) => {
  console.log('Processing:', job.data);
  return { success: true };
});

// Add jobs
await queue.add('my-job', { foo: 'bar' });

Custom Connection

const queue = new Queue('tasks', {
  connection: {
    host: '192.168.1.100',
    port: 6789,
    token: 'my-secret-token',  // If AUTH_TOKENS is set on server
  }
});

const worker = new Worker('tasks', handler, {
  connection: {
    host: '192.168.1.100',
    port: 6789,
    token: 'my-secret-token',
  }
});

Graceful Shutdown

The server handles SIGINT and SIGTERM:

Stops accepting new connections
Waits for active jobs to complete (30s timeout)
Flushes data to disk
Exits cleanly

Connecting AI Agents (MCP)

AI agents connect to a running bunqueue server via the MCP server. The MCP server runs as a separate process and communicates with your server over TCP.

# Start bunqueue server
bunqueue start --data-path ./data/queue.db

# In another terminal, connect Claude Code
claude mcp add bunqueue -- bunx bunqueue-mcp

// Claude Desktop / Cursor / Windsurf — add to MCP config
{
  "mcpServers": {
    "bunqueue": {
      "command": "bunx",
      "args": ["bunqueue-mcp"]
    }
  }
}

With authentication:

AUTH_TOKENS=my-secret bunqueue start

The MCP server picks up the connection settings from environment variables (TCP_PORT, HOST, AUTH_TOKENS). Agents get 73 tools to add jobs, manage queues, schedule crons, retry failures, set rate limits, and monitor everything.

For HTTP handlers (agent-only feature), agents register a URL endpoint and bunqueue auto-processes jobs via HTTP calls — no Worker deployment needed. See MCP Server guide for the full reference.