OpenParable
Skip to content
← Back to skills

Server Deployment

DevOps & Security
server-deployment

Server Deployment is an Agent Skill for devops & security published in the durable-streams/durable-streams repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Running durable stream servers. DurableStreamTestServer for development (Node.js, @durable-streams/server, not for production), Caddy plugin for production with Caddyfile configuration, data_dir for file-backed persistence, max_file_handles tuning, long_poll_timeout, server binary downloads for macOS Linux Windows, @durable-streams/cli tool setup, conformance test runner.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/durable-streams/durable-streams/blob/HEAD/packages/client/skills/server-deployment/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/server-deployment, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Durable Streams — Server Deployment

Two server options: a Node.js development server for prototyping and a Caddy-based production server with file persistence and CDN support.

Setup

Development server (Node.js)

import { DurableStreamTestServer } from "@durable-streams/server"

const server = new DurableStreamTestServer({
  port: 4437,
  host: "127.0.0.1",
})

await server.start()
console.log(`Dev server running on ${server.url}`)

Production server (Caddy binary)

Download the binary from GitHub releases for your platform.

# Start the server
./durable-streams-server run --config Caddyfile

Caddyfile configuration:

:8787 {
  route /v1/stream/* {
    durable_streams {
      data_dir ./data
      max_file_handles 200
      long_poll_timeout 60s
    }
  }
}

Core Patterns

CLI for testing

# Install CLI
npm install -g @durable-streams/cli

# Set server URL
export STREAM_URL=http://localhost:4437

# Create, write, read
durable-stream create my-stream
durable-stream write my-stream "Hello, world!"
durable-stream read my-stream

Running conformance tests

# Against your server
npx @durable-streams/server-conformance-tests --run http://localhost:4437

# Watch mode for development
npx @durable-streams/server-conformance-tests --watch src http://localhost:4437

Programmatic dev server with stream creation

import { DurableStreamTestServer } from "@durable-streams/server"
import { DurableStream } from "@durable-streams/client"

const server = new DurableStreamTestServer({ port: 0 }) // Random port
await server.start()

// Streams must be created before clients can connect
await DurableStream.create({
  url: `${server.url}/v1/stream/my-app`,
  contentType: "application/json",
})

console.log(`Dev server running on ${server.url}`)

Programmatic dev server in tests

import { DurableStreamTestServer } from "@durable-streams/server"

const server = new DurableStreamTestServer({ port: 0 }) // Random port
await server.start()

// Run your tests against server.url

await server.stop()

Caddy configuration options

OptionDefaultDescription
data_dir(none — in-memory)Directory for file-backed persistence
max_file_handles100Max concurrent open file handles
long_poll_timeout60sHow long to hold long-poll connections

Common Mistakes

CRITICAL Using the Node.js dev server in production

Wrong:

// production deployment
import { DurableStreamTestServer } from "@durable-streams/server"
const server = new DurableStreamTestServer({ port: 4437 })

Correct:

# Use the Caddy plugin binary
./durable-streams-server run --config Caddyfile

DurableStreamTestServer is explicitly not for production. It uses in-memory storage, has no CDN integration, and is single-process only.

Source: packages/server/README.md

CRITICAL Not configuring data_dir for persistence

Wrong:

:8787 {
  route /v1/stream/* {
    durable_streams
  }
}

Correct:

:8787 {
  route /v1/stream/* {
    durable_streams {
      data_dir ./data
      max_file_handles 200
    }
  }
}

Without data_dir, the Caddy plugin uses in-memory storage. Server restarts lose all data.

Source: packages/caddy-plugin/README.md

MEDIUM Setting max_file_handles too low for production

Wrong:

durable_streams {
  data_dir ./data
  # default 100 handles — fine for dev, low for production
}

Correct:

durable_streams {
  data_dir ./data
  max_file_handles 500  # Tune based on active stream count
}

Default is 100 file handles. High-throughput deployments with many concurrent streams can exhaust the pool, causing latency spikes.

Source: packages/caddy-plugin/store/filepool.go

See also

Version

Targets durable-streams-server v0.2.1.