Skip to content
Python

Add Railway deployment support to the app-building skill

Rohit P99eccf81d3d4
diff --git a/.github/workflows/sdk-skills.yml b/.github/workflows/sdk-skills.yml
new file mode 100644
index 00000000..63270d63
--- /dev/null
+++ b/.github/workflows/sdk-skills.yml
@@ -0,0 +1,25 @@
+name: SDK skills
+
+on:
+ pull_request:
+ paths: ["skills/**", "harness/release/**", ".github/workflows/sdk-skills.yml"]
+ push:
+ branches: [main]
+ paths: ["skills/**", "harness/release/**", ".github/workflows/sdk-skills.yml"]
+ workflow_dispatch:
+
+permissions:
+ contents: read
+
+jobs:
+ package-and-install:
+ runs-on: ubuntu-24.04
+ timeout-minutes: 5
+ steps:
+ - uses: actions/checkout@v4
+ - uses: actions/setup-node@v4
+ with:
+ node-version: 24
+ # No Rust build, Docker daemon, cloud credentials or model calls required.
+ - name: Test SDK compatibility and standalone skill installation
+ run: node --test skills/install.test.mjs skills/package.test.mjs harness/release/contract.test.mjs
diff --git a/harness/release/README.md b/harness/release/README.md
index 5a679f7f..093cfa0d 100644
--- a/harness/release/README.md
+++ b/harness/release/README.md
@@ -25,7 +25,8 @@ The npm client is `@openworkerai/harness-sdk`; matching runtime packages are
`@openworkerai/harness-runtime-<platform>-<arch>`. The same candidate includes
`@openworkerai/build-with-sdk-skills`, which installs the shared Desktop/Web
skill into a Codex or Claude Code project. The skill package has no runtime or
-SDK dependency. To prepare just that archive without compiling Rust:
+SDK dependency. Its package version can advance independently;
+`openworkerSdkVersion` declares the compatible SDK release. To prepare just that archive without compiling Rust:
```sh
node skills/prepare.mjs /absolute/new-skills-candidate
diff --git a/harness/release/contract.test.mjs b/harness/release/contract.test.mjs
index 84483b8d..639ea874 100644
--- a/harness/release/contract.test.mjs
+++ b/harness/release/contract.test.mjs
@@ -17,7 +17,7 @@ test('release versions and publishable Rust dependency closure agree',()=>{
assert.ok(existsSync(join(root,pkg.directory,'LICENSE')));
}
for(const folder of ['typescript-sdk','desktop-starters'])assert.equal(JSON.parse(readFileSync(join(root,folder,'package.json'))).version,manifest.version);
- assert.equal(JSON.parse(readFileSync(join(root,'../skills/package.json'))).version,manifest.version);
+ assert.equal(JSON.parse(readFileSync(join(root,'../skills/package.json'))).openworkerSdkVersion,manifest.version);
assert.ok(readFileSync(join(root,'typescript-sdk/src/version.ts'),'utf8').includes(JSON.stringify(manifest.version)));
assert.equal(new Set(manifest.targets.map(t=>t.rust)).size,manifest.targets.length);
});
diff --git a/harness/release/prepare.mjs b/harness/release/prepare.mjs
index 91b3da51..34ee54fe 100644
--- a/harness/release/prepare.mjs
+++ b/harness/release/prepare.mjs
@@ -42,8 +42,9 @@ for(const [directory,files] of [['typescript-sdk',['dist','examples','README.md'
const archives=join(out,'archives');await mkdir(archives);
const npm=process.platform==='win32'?'npm.cmd':'npm';
for(const directory of ['native','typescript-sdk','desktop-starters'])execFileSync(npm,['pack','--ignore-scripts','--json','--pack-destination',archives],{cwd:join(out,directory),stdio:'inherit',shell:process.platform==='win32'});
+const skillVersion=JSON.parse(await readFile(join(root,'../skills/package.json'),'utf8')).version;
const skillArchives=await prepareSkills(join(out,'skills'));
-await cp(join(skillArchives,`openworkerai-build-with-sdk-skills-${manifest.version}.tgz`),join(archives,`openworkerai-build-with-sdk-skills-${manifest.version}.tgz`));
+await cp(join(skillArchives,`openworkerai-build-with-sdk-skills-${skillVersion}.tgz`),join(archives,`openworkerai-build-with-sdk-skills-${skillVersion}.tgz`));
// Portable GitHub archive, with the same executable and metadata as npm.
const archive=`openworker-harness-${manifest.version}-${target.rust}.tar.gz`;
// A Windows drive letter is parsed as a remote host by GNU tar. Keep both
diff --git a/skills/README.md b/skills/README.md
index 6d083a27..7cd0d273 100644
--- a/skills/README.md
+++ b/skills/README.md
@@ -5,7 +5,7 @@ applications with the OpenWorker Harness SDK. It includes version-matched SDK
snippets and separate Desktop/Web references. No OpenWorker checkout is required
for the packaged skill, and installing it does not install the SDK or a runtime.
-**Release candidate:** `@openworkerai/[email protected]` is prepared
+**Release candidate:** `@openworkerai/[email protected]` is prepared
locally. Registry commands below apply after publication; the version in this
repository does not mean it has been published.
@@ -14,13 +14,13 @@ repository does not mean it has been published.
After publication, from an existing app project:
```sh
-npx @openworkerai/[email protected] --agent codex --project .
+npx @openworkerai/[email protected] --agent codex --project .
```
For Claude Code:
```sh
-npx @openworkerai/[email protected] --agent claude --project .
+npx @openworkerai/[email protected] --agent claude --project .
```
The installer creates `.agents/skills/openworker-apps/` for Codex or
@@ -28,7 +28,8 @@ The installer creates `.agents/skills/openworker-apps/` for Codex or
on Windows and macOS, leaves global settings alone, and refuses to overwrite an
existing skill. Review/back up an existing installation before replacing it.
`references/installation.json` records the matching SDK version, without local
-checkout paths or credentials. Use the same version for the SDK and skill.
+checkout paths or credentials. Use `sdkVersion` from that file for the SDK. Skill and SDK package versions may
+differ; this skill candidate targets SDK `0.1.0-beta.1`.
The skill is discoverable in that project. Restart the coding-agent session if it
does not appear. Invoke `$openworker-apps` in Codex or `/openworker-apps` in Claude
@@ -40,8 +41,12 @@ For the Web track:
> Use the openworker-apps skill to build a web app where I can upload a PDF and ask questions with page references. Explain the agent and session code and test the application locally.
-The shared skill contains the app integration guidance. Detailed Railway/Vercel
-recipes and a cluster-operations skill will follow separately. This installer
+The shared skill includes a [Railway deployment track](openworker-apps/references/railway.md)
+and Docker assets. The default is one Node service serving the frontend and API,
+with the Rust harness running as a managed child process. The recipe has been tested locally and on Railway with the
+published SDK, including streamed Claude responses and conversation recovery
+after redeployment. Vercel recipes and a cluster-operations skill will
+follow separately. This installer
targets local Codex and Claude Code projects, not Claude web/Cowork uploads.
## Try the local candidate
@@ -61,7 +66,7 @@ node skills/prepare.mjs /absolute/new-skills-candidate
Install the resulting archive into a temporary project or use it through npm exec:
```sh
-npm exec --package /absolute/new-skills-candidate/archives/openworkerai-build-with-sdk-skills-0.1.0-beta.1.tgz -- build-with-sdk-skills --agent codex --project /path/to/your-app
+npm exec --package /absolute/new-skills-candidate/archives/openworkerai-build-with-sdk-skills-0.1.0-beta.2.tgz -- build-with-sdk-skills --agent codex --project /path/to/your-app
```
The preparer never publishes. Source package manifests remain private; staged
@@ -71,3 +76,33 @@ Installation locations follow the official [Codex skill documentation](https://l
and [Claude Code skill documentation](https://code.claude.com/docs/en/skills).
Validate source and packed installation with `node --test skills/install.test.mjs skills/package.test.mjs`.
+
+## Railway recipe checks
+
+The Railway reference and Docker assets are installed with the skill. To exercise
+the container contract locally using a verified SDK artifact manifest:
+
+```sh
+OW_RAILWAY_CONTAINER_TEST=1 \
+OW_SDK_PUBLICATION_MANIFEST=/absolute/path/to/publication-manifest.json \
+node --test skills/railway-container.test.mjs
+```
+
+This opt-in test builds a Linux Node image from the bundled Dockerfile, supplies
+the SDK/runtime archives without a source checkout dependency, and uses a local
+model fixture. It checks native discovery, the configured port, readiness,
+unauthorized requests, streamed text, clean shutdown and conversation recovery
+after replacing the container with the same named volume. It also checks that
+local secrets and host node_modules are excluded from the image. It cleans up
+its own containers, volume, network and image. Debian packages may be downloaded
+during image build; model traffic stays on an isolated Docker network.
+
+This does not qualify live Railway routing, credentials, billing or deployment
+replacement. Those checks require an authorized Railway target.
+
+A separate live Railway check used SDK `0.1.0-beta.1`, the bundled Dockerfile,
+one replica and a persistent `/data` volume. It verified HTTPS routing, rejected
+unauthenticated requests, streamed output before model completion, explicit
+cancellation, graceful shutdown, unchanged session references after redeployment,
+and real Anthropic recall of earlier conversation content. This qualifies the
+single-service recipe; it does not establish multi-replica or zero-downtime behavior.
diff --git a/skills/install.mjs b/skills/install.mjs
index cea00062..2cd651e9 100644
--- a/skills/install.mjs
+++ b/skills/install.mjs
@@ -4,7 +4,7 @@ import { mkdir, lstat, realpath, readFile, writeFile } from 'node:fs/promises';
import { dirname, join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
const source = dirname(fileURLToPath(import.meta.url));
-const files = ['SKILL.md','references/desktop.md','references/web.md','references/sdk.md','agents/openai.yaml'];
+const files = ['SKILL.md','references/desktop.md','references/web.md','references/sdk.md','references/railway.md','assets/railway/Dockerfile','assets/railway/.dockerignore','agents/openai.yaml'];
export async function install({agent, project}) {
if (!['codex','claude'].includes(agent) || !project) throw Error('Use --agent codex|claude --project /path/to/your-app');
const pkg = JSON.parse(await readFile(join(source,'package.json'),'utf8'));
@@ -26,7 +26,7 @@ export async function install({agent, project}) {
await writeFile(join(destination,name), content[index], {flag:'wx'});
}
await writeFile(join(destination,'references/installation.json'), JSON.stringify({
- package:pkg.name, version:pkg.version, sdkPackage:'@openworkerai/harness-sdk', sdkVersion:pkg.version,
+ package:pkg.name, version:pkg.version, sdkPackage:'@openworkerai/harness-sdk', sdkVersion:pkg.openworkerSdkVersion,
},null,2)+'\n');
return destination;
}
diff --git a/skills/install.test.mjs b/skills/install.test.mjs
index f134bcc4..36c58509 100644
--- a/skills/install.test.mjs
+++ b/skills/install.test.mjs
@@ -14,7 +14,7 @@ for (const agent of ['codex','claude']) test(`install complete ${agent} skill; p
const metadata=JSON.parse(await readFile(join(dest,'references/installation.json'),'utf8'));
const pkg=JSON.parse(await readFile(new URL('./package.json',import.meta.url),'utf8'));
assert.equal(metadata.sdkPackage,'@openworkerai/harness-sdk');
- assert.equal(metadata.sdkVersion,pkg.version);
+ assert.equal(metadata.sdkVersion,pkg.openworkerSdkVersion);
assert.equal(metadata.package,'@openworkerai/build-with-sdk-skills');
assert.equal(metadata.checkout,undefined);
await writeFile(join(dest,'SKILL.md'),'local customization');
diff --git a/skills/openworker-apps/SKILL.md b/skills/openworker-apps/SKILL.md
index 8afa7c97..66e5cd6e 100644
--- a/skills/openworker-apps/SKILL.md
+++ b/skills/openworker-apps/SKILL.md
@@ -1,6 +1,6 @@
---
name: openworker-apps
-description: Build or adapt desktop and web applications using the OpenWorker Harness SDK, including agent creation, streamed sessions, model configuration and application packaging. Use for OpenWorker integrations, not general website design or unrelated agent frameworks.
+description: Build or adapt desktop and web applications using the OpenWorker Harness SDK, including agent creation, streamed sessions, model configuration, application packaging and Railway deployment. Use for OpenWorker integrations, not general website design or unrelated agent frameworks.
---
# Build apps with OpenWorker
@@ -13,11 +13,14 @@ Preserve their chosen UI framework, model and deployment target.
- Read [SDK integration](references/sdk.md) for the shared lifecycle and package contract.
- For desktop apps, read [Desktop](references/desktop.md).
- For browser/server apps, read [Web](references/web.md).
+- For a Railway deployment, read [Railway](references/railway.md). Default to one
+ Node service serving the frontend and HTTP API with a managed Rust harness.
These references are bundled with the skill; an OpenWorker repository checkout
is not required. If `references/installation.json` exists, it records the exact
-SDK version this skill accompanies. Otherwise the skill package's version is the
-SDK version. Match the application's installed version before using these APIs;
+SDK version this skill supports. For a source checkout, use the skill package's
+`openworkerSdkVersion`. Skill releases can advance independently of the SDK.
+Match the application's installed version before using these APIs;
do not silently upgrade an existing application. Use the installed package's
TypeScript declarations for APIs outside the bundled examples. For Rust, consult
the matching SDK version's API documentation or source when needed.
diff --git a/skills/openworker-apps/assets/railway/.dockerignore b/skills/openworker-apps/assets/railway/.dockerignore
new file mode 100644
index 00000000..829747ca
--- /dev/null
+++ b/skills/openworker-apps/assets/railway/.dockerignore
@@ -0,0 +1,17 @@
+node_modules
+**/node_modules
+.git
+.railway
+.agents
+.claude
+.env
+.env.*
+!.env.example
+.npmrc
+*.log
+coverage
+dist
+.state
+state
+data
+uploads
diff --git a/skills/openworker-apps/assets/railway/Dockerfile b/skills/openworker-apps/assets/railway/Dockerfile
new file mode 100644
index 00000000..393aee0e
--- /dev/null
+++ b/skills/openworker-apps/assets/railway/Dockerfile
@@ -0,0 +1,22 @@
+# Adapt the build script and final server entrypoint to the application.
+# Install inside Linux: do not copy the developer machine's node_modules.
+FROM node:24-bookworm-slim AS build
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm ci --include=optional
+COPY . .
+RUN npm run build --if-present && npm prune --omit=dev --include=optional
+
+FROM node:24-bookworm-slim
+# The native Linux helper uses OpenSSL 3; slim images do not include it.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends libssl3 ca-certificates \
+ && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY --from=build --chown=node:node /app /app
+RUN mkdir -p /data && chown node:node /data
+USER node
+ENV NODE_ENV=production HOST=0.0.0.0 PORT=8080 OPENWORKER_STATE_DIR=/data/harness
+EXPOSE 8080
+# Direct exec allows Node to receive SIGTERM and shut down its Rust child.
+CMD ["node", "dist/server.js"]
diff --git a/skills/openworker-apps/references/railway.md b/skills/openworker-apps/references/railway.md
new file mode 100644
index 00000000..8627ed04
--- /dev/null
+++ b/skills/openworker-apps/references/railway.md
@@ -0,0 +1,163 @@
+# Deploy an SDK app on Railway
+
+Use this track for a long-running Node web service. By default, deploy the
+frontend and HTTP API together: one Node process serves the built UI and API
+routes, and manages the Rust harness as a child process in the same container.
+This gives the browser one origin for pages, authentication and streamed replies.
+Keep the user's framework and product; adapt the assets rather than replacing
+an existing application. Preserve an existing frontend/backend split, or use
+separate services when the user needs independent deployment or scaling.
+Read [Web](web.md) and [SDK integration](sdk.md) for authentication, session
+ownership and the SDK lifecycle.
+
+```text
+Browser ── HTTPS ──> Node UI + HTTP API ── private stdio ──> Rust harness
+ │ │
+ app records/uploads durable sessions
+ └──────── volume /data ─────────────┘
+```
+
+Start with one service and one replica. This is a managed harness process,
+not an OpenWorker service cluster. No OpenWorker checkout, Rust compiler or
+OpenShell installation is needed for this application-owned-input example.
+Enable coding tools or isolated execution only when the product requires them.
+
+## Prepare the application
+
+Pin the SDK version from `installation.json` and commit the app's lockfile.
+Keep the SDK in production dependencies. Start one harness per application
+process with an absolute `OPENWORKER_STATE_DIR`, for example `/data/harness`.
+Configure its provider from runtime secrets, create the agent, and await
+`agent.ready()` before accepting agent work. Re-supply memory-only provider
+credentials on every restart. Pass the state directory into `Harness.start`;
+setting an environment variable does not replace a hard-coded application path.
+A laptop's localhost model is not reachable from Railway: use an authorized
+cloud/proxy provider or a reachable model service. Network model endpoints must
+use HTTPS; the SDK accepts plain HTTP only on loopback.
+
+Implement these application behaviors before deploying:
+
+- Listen on `0.0.0.0` and `Number(process.env.PORT ?? 8080)`.
+- Provide `/health` without user authentication, returning no secrets. Return
+ success only after startup completes; return 503 while starting or draining.
+ If hostname filtering is enabled, permit Railway's healthcheck hostname.
+- Authenticate agent endpoints and authorize document/session lookup. A session
+ reference is not a login credential. A shared bearer token is only suitable
+ for a private single-user demo.
+- Stream responses through the application's API and check the final run status.
+ On browser disconnect, follow the product's cancellation policy explicitly.
+- On SIGTERM/SIGINT, mark readiness false, stop new work, cancel or finish active
+ runs within the configured shutdown window, then await `harness.shutdown()`.
+ Use a bounded shutdown deadline. Start Node directly, not behind a shell or
+ `npm start` wrapper that may swallow signals.
+
+Persist `session.reference()` with the application's owner/conversation record,
+then use `agent.resumeSession(reference)` after a restart. The harness persists
+history; it does not persist the application's in-memory document map, uploads,
+or ownership records. Put those in the mounted directory or an application DB.
+For PDF Notes, retaining only the harness database is insufficient to restore
+an uploaded document's context. Apply explicit retention to both stores.
+
+## Build the container
+
+Copy/adapt [Dockerfile](../assets/railway/Dockerfile) and
+[.dockerignore](../assets/railway/.dockerignore) into the app, preserving existing
+project files. The Dockerfile expects a committed package-lock.json, an optional
+`build` script, and `dist/server.js`; change the entrypoint to the real server.
+Do not ship a development server. Review the build context for application-specific
+secret/data paths and monorepo workspace dependencies. Also exclude secrets and
+local state from Git/source uploads; Docker ignore only controls the image context.
+
+Install optional dependencies inside the glibc Linux build stage. This selects
+the Linux native runtime automatically. The slim-image runtime stage installs
+`libssl3` and CA certificates, which the native helper needs; do not copy a macOS/Windows helper or
+host node_modules. The final image needs neither Rust nor Electron. Keep model
+keys out of Docker build arguments, layers and committed configuration.
+
+Use `docker build -t my-openworker-app .` and test with a disposable named volume,
+runtime-only variables and a loopback model fixture if no live key is available.
+A local Docker test establishes container behavior, not live Railway qualification.
+
+## Set up the Railway target
+
+Use the user's selected workspace, project, environment and service. Existing
+authorization to deploy there is sufficient; if the target or spending scope is
+missing, establish it before creating paid resources or exposing a service.
+Do not delete/recreate an existing service or volume to make a deployment succeed.
+
+Railway detects a root `Dockerfile`. Set the service root correctly for a monorepo.
+Configure the following on the chosen service before its first public deployment:
+
+| Setting | Value or decision |
+| --- | --- |
+| Build | Dockerfile in the app's service root |
+| Start command | Use the image's direct Node command, or the app's equivalent |
+| Healthcheck | `/health`; allow enough time for SDK initialization |
+| Volume | Mount at `/data`; create application state directories at startup |
+| Harness state | `OPENWORKER_STATE_DIR=/data/harness` |
+| Application state | e.g. `/data/app`; persist conversation ownership and uploads |
+| Provider | Exact model ID and provider secrets as runtime service variables |
+| Access | App authentication; a private demo may use `APP_ACCESS_TOKEN` |
+| Replicas | One for this SQLite/volume recipe |
+| Shutdown | Give the app a drain window longer than its own shutdown deadline (for example, 20 seconds for a 10-second app deadline) |
+
+Railway volumes are mounted as root. For the provided non-root image, Railway
+currently documents `RAILWAY_RUN_UID=0` as its compatibility setting. This runs
+the app as root inside the container. If the deployment requires a non-root
+process, use an approved volume-ownership initialization instead and test it;
+do not assume Dockerfile `chown` changes an already mounted Railway volume.
+
+Volumes are available at runtime, not during image build or pre-deploy commands.
+A volume-backed service can have downtime during replacement. This recipe does
+not promise zero-downtime failover or shared SQLite across replicas. Do not enable
+sleeping for background agent work without verifying the lifecycle behavior.
+Set explicit service CPU and memory limits suited to the app, and inspect workspace
+usage after deployment. For a temporary test, agree on whether to keep it running
+or remove it after qualification; do not delete a demo the user wants to try.
+For horizontal scaling, decide on external storage, session routing and workers
+or an OpenWorker service deployment as a separate architecture change.
+
+## Deploy and verify
+
+Use an existing Railway CLI, or follow its official installation instructions.
+For an authorized, existing target, the usual interactive flow is:
+
+```sh
+railway login
+railway link
+railway service
+railway status
+railway up
+railway logs
+```
+
+Check the selected project/environment/service from `status` before uploading.
+For a new target, create the approved project/service and volume first. Supply
+secrets through Railway's variable editor or approved secret workflow, not shell
+history or chat. Generate a public domain only after authentication is configured.
+For non-interactive commands, read the installed CLI's `--help` for explicit target
+flags rather than guessing them.
+
+Do not generate new legacy railway.json/railway.toml config-as-code templates.
+Current Railway docs deprecate those; for reproducible provisioning use the
+current `railway config`/IaC workflow and review its plan for the chosen target.
+The Docker assets here do not create a volume, set service variables or provision
+infrastructure by themselves.
+
+Check the deployed URL's readiness, rejected unauthorized requests, streamed
+response and terminal status. Exercise stop/disconnect behavior. Redeploy the
+same service with its volume retained, authenticate again and resume the same
+owned conversation. A healthcheck only gates deployment; add ongoing monitoring
+if the product requires it. Report the URL, exact release, checks performed and
+anything tested only locally. Do not claim a live deployment without checking it.
+
+## Platform references
+
+Consult these before changing platform-specific commands or settings:
+
+- [Docker builds](https://docs.railway.com/builds/dockerfiles)
+- [Volumes and permissions](https://docs.railway.com/volumes)
+- [Healthchecks](https://docs.railway.com/deployments/healthchecks)
+- [CLI](https://docs.railway.com/cli)
+- [Infrastructure as Code](https://docs.railway.com/infrastructure-as-code)
+- [Legacy config status](https://docs.railway.com/config-as-code/reference)
diff --git a/skills/openworker-apps/references/web.md b/skills/openworker-apps/references/web.md
index 9ca1df84..7237b5a5 100644
--- a/skills/openworker-apps/references/web.md
+++ b/skills/openworker-apps/references/web.md
@@ -34,9 +34,11 @@ HTTPS through the platform's ingress. A managed child process needs a host that
supports its lifecycle; do not assume a request-limited function is a persistent
agent worker.
-Detailed Railway/Vercel recipes and operation of a separate Kubernetes harness
-service are outside this skill version's qualified deployment examples. For an
-existing service, consult https://openworker.com/docs/sdk/deployment/ and the
+For Railway, default to one Node service serving the built frontend and HTTP API,
+with the Rust harness as its managed child. Preserve an existing split if the app
+already has one. Use [the deployment track](railway.md) and its bundled Docker assets.
+Vercel recipes and operation of a separate Kubernetes harness service remain
+separate work. For an existing service, consult https://openworker.com/docs/sdk/deployment/ and the
installed SDK's service API declarations before changing the application model.
## Reference source when useful
diff --git a/skills/package.json b/skills/package.json
index 9cf0adb4..af8fccd7 100644
--- a/skills/package.json
+++ b/skills/package.json
@@ -1,6 +1,6 @@
{
"name": "@openworkerai/build-with-sdk-skills",
- "version": "0.1.0-beta.1",
+ "version": "0.1.0-beta.2",
"description": "Install the OpenWorker app-building skill for Codex or Claude Code",
"type": "module",
"license": "MIT",
@@ -14,5 +14,6 @@
"directory": "skills"
},
"publishConfig": { "access": "public", "tag": "beta" },
- "private": true
+ "private": true,
+ "openworkerSdkVersion": "0.1.0-beta.1"
}
diff --git a/skills/package.test.mjs b/skills/package.test.mjs
index dcd3b649..2f2d5ff5 100644
--- a/skills/package.test.mjs
+++ b/skills/package.test.mjs
@@ -38,8 +38,9 @@ test('packed installer works outside the checkout without SDK or native dependen
assert.match(run(['--agent',agent,'--project',project]), /Installed:/);
const dest = join(project,agent==='codex'?'.agents':'.claude','skills/openworker-apps');
const metadata = JSON.parse(await readFile(join(dest,'references/installation.json'),'utf8'));
- assert.equal(metadata.sdkVersion,pkg.version);
+ assert.equal(metadata.sdkVersion,pkg.openworkerSdkVersion);
assert.equal(metadata.sdkPackage,'@openworkerai/harness-sdk');
+ assert.equal(metadata.version,pkg.version);
for (const folder of ['', 'references', 'agents']) {
for (const file of await readdir(join(dest,folder))) {
if (!/\.(md|json|yaml)$/.test(file)) continue;
diff --git a/skills/prepare.mjs b/skills/prepare.mjs
index e70b74f2..ed61ceea 100644
--- a/skills/prepare.mjs
+++ b/skills/prepare.mjs
@@ -10,7 +10,7 @@ export async function prepare(directory) {
const out = resolve(directory);
const pkg = JSON.parse(await readFile(join(source, 'package.json'), 'utf8'));
const release = JSON.parse(await readFile(join(source, '../harness/release/manifest.json'), 'utf8'));
- if (pkg.version !== release.version) throw Error('Skill and SDK release versions must match');
+ if (pkg.openworkerSdkVersion !== release.version) throw Error('Skill SDK compatibility must match the SDK release');
await mkdir(out); // An existing candidate must never be overwritten.
const staging = join(out, 'package');
await mkdir(staging);
diff --git a/skills/railway-container.test.mjs b/skills/railway-container.test.mjs
new file mode 100644
index 00000000..63143db9
--- /dev/null
+++ b/skills/railway-container.test.mjs
@@ -0,0 +1,273 @@
+// Opt-in local qualification. No Railway account or live model is contacted.
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+ mkdtemp,
+ mkdir,
+ readFile,
+ writeFile,
+ copyFile,
+ rm,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, dirname, basename } from "node:path";
+import { fileURLToPath } from "node:url";
+import { execFileSync, spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+const here = dirname(fileURLToPath(import.meta.url));
+test(
+ "Railway container contract: native discovery, auth, streaming, volume resume and shutdown",
+ {
+ skip: process.env.OW_RAILWAY_CONTAINER_TEST !== "1",
+ timeout: 300000,
+ },
+ async () => {
+ const manifest = JSON.parse(
+ await readFile(process.env.OW_SDK_PUBLICATION_MANIFEST, "utf8"),
+ );
+ const skill = JSON.parse(
+ await readFile(join(here, "package.json"), "utf8"),
+ );
+ const id = "ow-railway-" + randomUUID().slice(0, 8),
+ image = id + ":test",
+ network = id + "-net",
+ volume = id + "-data";
+ const first = id + "-first",
+ second = id + "-second",
+ model = id + "-model";
+ const root = await mkdtemp(join(tmpdir(), "ow-railway-")),
+ app = join(root, "app");
+ const docker = (...args) =>
+ execFileSync("docker", args, {
+ encoding: "utf8",
+ maxBuffer: 8 * 1024 * 1024,
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+ try {
+ await mkdir(join(app, "vendor"), { recursive: true });
+ const deps = {},
+ optional = {};
+ for (const p of manifest.packages.filter(
+ (p) =>
+ p.name === "@openworkerai/harness-sdk" ||
+ p.name.startsWith("@openworkerai/harness-runtime-"),
+ )) {
+ assert.equal(p.version, skill.openworkerSdkVersion);
+ await copyFile(p.file, join(app, "vendor", basename(p.file)));
+ (p.name === "@openworkerai/harness-sdk" ? deps : optional)[p.name] =
+ "file:vendor/" + basename(p.file);
+ }
+ assert.equal(Object.keys(deps).length, 1);
+ assert.equal(Object.keys(optional).length, 6);
+ await writeFile(
+ join(app, "package.json"),
+ JSON.stringify({
+ name: "railway-fixture",
+ private: true,
+ type: "module",
+ dependencies: deps,
+ optionalDependencies: optional,
+ scripts: { build: "node build.mjs" },
+ }),
+ );
+ await copyFile(
+ join(here, "test/railway-fixture/server.mjs"),
+ join(app, "server.mjs"),
+ );
+ await writeFile(
+ join(app, "build.mjs"),
+ "import{mkdir,copyFile}from'node:fs/promises';await mkdir('dist',{recursive:true});await copyFile('server.mjs','dist/server.js');\n",
+ );
+ execFileSync(
+ "npm",
+ [
+ "install",
+ "--package-lock-only",
+ "--offline",
+ "--ignore-scripts",
+ "--no-audit",
+ "--no-fund",
+ "--cache",
+ join(root, "cache"),
+ ],
+ { cwd: app, stdio: "pipe" },
+ );
+ await mkdir(join(app, "node_modules"), { recursive: true });
+ await writeFile(join(app, "node_modules/host-sentinel"), "must not copy");
+ await writeFile(join(app, ".env"), "DO_NOT_COPY=fixture");
+ // Supply immutable pre-publication tarballs without substituting the helper.
+ // The only Dockerfile adaptation is copying this offline dependency vendor dir.
+ const recipe = await readFile(
+ join(here, "openworker-apps/assets/railway/Dockerfile"),
+ "utf8",
+ );
+ await writeFile(
+ join(app, "Dockerfile"),
+ recipe.replace(
+ "COPY package.json package-lock.json ./",
+ "COPY package.json package-lock.json ./\nCOPY vendor ./vendor",
+ ),
+ );
+ await copyFile(
+ join(here, "openworker-apps/assets/railway/.dockerignore"),
+ join(app, ".dockerignore"),
+ );
+ docker("build", "--pull=false", "-t", image, app);
+ docker("network", "create", "--internal", network);
+ docker("volume", "create", volume);
+ docker(
+ "run",
+ "-d",
+ "--name",
+ model,
+ "--network",
+ network,
+ "--network-alias",
+ "model",
+ "--mount",
+ `type=bind,src=${join(here, "test/railway-fixture")},dst=/fixture,readonly`,
+ "node:24-bookworm-slim",
+ "node",
+ "/fixture/model.mjs",
+ );
+ const start = (name) => {
+ docker(
+ "run",
+ "-d",
+ "--name",
+ name,
+ "--network",
+ "container:" + model,
+ "--user",
+ "0:0",
+ "--mount",
+ `type=volume,src=${volume},dst=/data`,
+ "-e",
+ "PORT=9092",
+ "-e",
+ "NO_PROXY=model,localhost,127.0.0.1",
+ "-e",
+ "OPENAI_API_KEY=fixture-key-not-real",
+ "-e",
+ "APP_ACCESS_TOKEN=local-fixture-only",
+ image,
+ );
+ return "http://model:9092";
+ };
+ const request = (url, options = {}) =>
+ JSON.parse(
+ docker(
+ "exec",
+ model,
+ "node",
+ "/fixture/probe.mjs",
+ url,
+ JSON.stringify(options),
+ ),
+ );
+ const ready = async (url, name) => {
+ const until = Date.now() + 30000;
+ let error;
+ while (Date.now() < until) {
+ try {
+ const r = request(url + "/health", {
+ headers: { host: "healthcheck.railway.app" },
+ });
+ if (r.status === 200) return;
+ } catch (e) {
+ error = e;
+ }
+ if (
+ docker("inspect", "--format", "{{.State.Running}}", name).trim() !==
+ "true"
+ )
+ throw Error("Application exited before readiness");
+ await new Promise((r) => setTimeout(r, 200));
+ }
+ throw Error("Readiness failed: " + error);
+ };
+ const ask = async (url, message) => {
+ const r = request(url + "/turn", {
+ method: "POST",
+ headers: {
+ authorization: "Bearer local-fixture-only",
+ "content-type": "application/json",
+ },
+ body: JSON.stringify({ message }),
+ });
+ assert.equal(r.status, 200);
+ assert.equal(
+ r.modelCompletedAtFirstChunk,
+ false,
+ "A delta must arrive before the model finishes",
+ );
+ const events = r.text
+ .trim()
+ .split("\n")
+ .map((line) => JSON.parse(line));
+ assert.ok(events.some((e) => e.type === "delta"));
+ assert.equal(events.at(-1).status, "completed");
+ return events.at(-1).text;
+ };
+ let url = start(first);
+ await ready(url, first);
+ assert.equal(
+ request(url + "/turn", { method: "POST", body: "{}" }).status,
+ 401,
+ );
+ assert.equal(await ask(url, "FIRST_MESSAGE"), "first-done");
+ const reference = docker("exec", first, "cat", "/data/app/session.json");
+ assert.match(
+ docker(
+ "exec",
+ first,
+ "node",
+ "--input-type=module",
+ "-e",
+ "import{resolveRuntimeExecutable}from'@openworkerai/harness-sdk';console.log(resolveRuntimeExecutable())",
+ ),
+ /harness-runtime-linux-/,
+ );
+ docker(
+ "exec",
+ first,
+ "node",
+ "--input-type=module",
+ "-e",
+ "import{existsSync}from'node:fs';if(existsSync('/app/.env')||existsSync('/app/node_modules/host-sentinel'))process.exit(1)",
+ );
+ docker("stop", "--time", "15", first);
+ assert.equal(
+ docker("inspect", "--format", "{{.State.ExitCode}}", first).trim(),
+ "0",
+ );
+ assert.match(docker("logs", first), /shutdown complete/);
+ docker("rm", first);
+ url = start(second);
+ await ready(url, second);
+ assert.equal(
+ docker("exec", second, "cat", "/data/app/session.json"),
+ reference,
+ );
+ assert.equal(await ask(url, "SECOND_MESSAGE"), "history-restored");
+ docker("stop", "--time", "15", second);
+ assert.equal(
+ docker("inspect", "--format", "{{.State.ExitCode}}", second).trim(),
+ "0",
+ );
+ } catch (error) {
+ for (const name of [first, second, model]) {
+ const logs = spawnSync("docker", ["logs", name], { encoding: "utf8" });
+ if (logs.status === 0) console.error(name, logs.stdout, logs.stderr);
+ }
+ throw error;
+ } finally {
+ for (const name of [first, second, model])
+ spawnSync("docker", ["rm", "-f", name], { stdio: "ignore" });
+ spawnSync("docker", ["volume", "rm", volume], { stdio: "ignore" });
+ spawnSync("docker", ["network", "rm", network], { stdio: "ignore" });
+ spawnSync("docker", ["image", "rm", image], { stdio: "ignore" });
+ await rm(root, { recursive: true, force: true });
+ }
+ },
+);
diff --git a/skills/test/railway-fixture/model.mjs b/skills/test/railway-fixture/model.mjs
new file mode 100644
index 00000000..e6680e39
--- /dev/null
+++ b/skills/test/railway-fixture/model.mjs
@@ -0,0 +1,62 @@
+import { createServer } from "node:http";
+let completed = false;
+let requests = 0;
+let finish;
+createServer(async (req, res) => {
+ if (req.url === "/status") {
+ res.setHeader("content-type", "application/json");
+ res.end(JSON.stringify({ completed, requests }));
+ return;
+ }
+ if (req.url === "/release") {
+ finish?.();
+ finish = undefined;
+ res.end("released");
+ return;
+ }
+ let raw = "";
+ for await (const chunk of req) raw += chunk;
+ const body = JSON.parse(raw);
+ if (req.url !== "/v1/responses" || body.model !== "fixture") {
+ res.writeHead(400);
+ res.end();
+ return;
+ }
+ completed = false;
+ requests++;
+ const input = JSON.stringify(body.input);
+ const text = input.includes("SECOND_MESSAGE")
+ ? input.includes("FIRST_MESSAGE")
+ ? "history-restored"
+ : "history-missing"
+ : "first-done";
+ res.writeHead(200, { "content-type": "text/event-stream" });
+ res.write(
+ "data: " +
+ JSON.stringify({ type: "response.output_text.delta", delta: text }) +
+ "\n\n",
+ );
+ // The probe releases completion only after receiving a real streamed chunk.
+ // This avoids timing assumptions and fails if the application buffers output.
+ finish = () => {
+ completed = true;
+ res.end(
+ "data: " +
+ JSON.stringify({
+ type: "response.completed",
+ response: {
+ status: "completed",
+ output: [
+ {
+ type: "message",
+ role: "assistant",
+ content: [{ type: "output_text", text }],
+ },
+ ],
+ usage: { input_tokens: 20, output_tokens: 8 },
+ },
+ }) +
+ "\n\n",
+ );
+ };
+}).listen(8081, "0.0.0.0");
diff --git a/skills/test/railway-fixture/probe.mjs b/skills/test/railway-fixture/probe.mjs
new file mode 100644
index 00000000..559a3860
--- /dev/null
+++ b/skills/test/railway-fixture/probe.mjs
@@ -0,0 +1,18 @@
+const [url, serializedOptions] = process.argv.slice(2);
+const response = await fetch(url, {
+ ...JSON.parse(serializedOptions),
+ signal: AbortSignal.timeout(30000),
+});
+let text = "";
+let modelCompletedAtFirstChunk;
+for await (const chunk of response.body) {
+ if (modelCompletedAtFirstChunk === undefined) {
+ const state = await (await fetch("http://127.0.0.1:8081/status")).json();
+ modelCompletedAtFirstChunk = state.completed;
+ await fetch("http://127.0.0.1:8081/release");
+ }
+ text += Buffer.from(chunk).toString();
+}
+console.log(
+ JSON.stringify({ status: response.status, text, modelCompletedAtFirstChunk }),
+);
diff --git a/skills/test/railway-fixture/server.mjs b/skills/test/railway-fixture/server.mjs
new file mode 100644
index 00000000..c74ec4d1
--- /dev/null
+++ b/skills/test/railway-fixture/server.mjs
@@ -0,0 +1,134 @@
+// Local qualification fixture, not an application template or multi-user auth.
+import { createServer } from "node:http";
+import { mkdir, readFile, writeFile, rename } from "node:fs/promises";
+import { dirname } from "node:path";
+import { timingSafeEqual } from "node:crypto";
+import { Harness } from "@openworkerai/harness-sdk";
+const stateDir = process.env.OPENWORKER_STATE_DIR;
+const record = "/data/app/session.json";
+const harness = await Harness.start({ stateDir, sandbox: "off" });
+await harness.setModelProvider({
+ name: "Fixture",
+ api: "responses",
+ baseUrl: "http://127.0.0.1:8081/v1",
+ credentials: { apiKeyEnv: "OPENAI_API_KEY", storage: "memory" },
+});
+const agent = harness.createAgent({
+ name: "reader",
+ instructions: "Answer from the conversation.",
+ defaultModel: { provider: "Fixture", name: "fixture" },
+ tools: [],
+ planning: false,
+ memory: false,
+ scheduling: false,
+});
+await agent.ready();
+let session;
+try {
+ session = await agent.resumeSession(
+ JSON.parse(await readFile(record, "utf8")),
+ );
+} catch (error) {
+ if (error.code !== "ENOENT") throw error;
+ session = await agent.newSession();
+ await mkdir(dirname(record), { recursive: true });
+ await writeFile(record + ".tmp", JSON.stringify(session.reference()));
+ await rename(record + ".tmp", record);
+}
+let draining = false,
+ busy = false;
+const server = createServer(async (req, res) => {
+ if (req.url === "/health") {
+ res.writeHead(draining ? 503 : 200, { "content-type": "application/json" });
+ res.end(JSON.stringify({ ready: !draining }));
+ return;
+ }
+ const actual = Buffer.from(req.headers.authorization ?? ""),
+ expected = Buffer.from("Bearer " + process.env.APP_ACCESS_TOKEN);
+ if (actual.length !== expected.length || !timingSafeEqual(actual, expected)) {
+ res.writeHead(401);
+ res.end();
+ return;
+ }
+ if (draining || busy) {
+ res.writeHead(503);
+ res.end();
+ return;
+ }
+ if (req.url !== "/turn" || req.method !== "POST") {
+ res.writeHead(404);
+ res.end();
+ return;
+ }
+ let input = "";
+ for await (const chunk of req) {
+ input += chunk;
+ if (Buffer.byteLength(input) > 4096) {
+ res.writeHead(413);
+ res.end();
+ return;
+ }
+ }
+ let message;
+ try {
+ message = JSON.parse(input).message;
+ if (typeof message !== "string" || !message.trim()) throw Error("input");
+ } catch {
+ res.writeHead(400);
+ res.end();
+ return;
+ }
+ busy = true;
+ let finished = false;
+ res.writeHead(200, {
+ "content-type": "application/x-ndjson",
+ "cache-control": "no-store",
+ });
+ res.flushHeaders();
+ res.once("close", () => {
+ if (!finished) void session.cancel().catch(() => {});
+ });
+ try {
+ const run = await session.send(message);
+ for await (const item of run.events()) {
+ if (item.event.type === "assistant_delta")
+ res.write(
+ JSON.stringify({ type: "delta", text: item.event.data.text }) + "\n",
+ );
+ }
+ const result = await run.result();
+ res.write(
+ JSON.stringify({
+ type: "result",
+ status: result.status,
+ text: result.finalOutput,
+ }) + "\n",
+ );
+ } catch {
+ res.write(JSON.stringify({ type: "error" }) + "\n");
+ } finally {
+ finished = true;
+ busy = false;
+ res.end();
+ }
+});
+server.listen(Number(process.env.PORT), process.env.HOST ?? "0.0.0.0", () =>
+ console.log("ready"),
+);
+for (const signal of ["SIGTERM", "SIGINT"])
+ process.once(signal, () => {
+ if (draining) return;
+ draining = true;
+ const deadline = setTimeout(() => process.exit(1), 10000);
+ deadline.unref();
+ void (async () => {
+ const closed = new Promise((resolve) => server.close(resolve));
+ if (busy) await session.cancel();
+ await harness.shutdown();
+ server.closeAllConnections();
+ await closed;
+ clearTimeout(deadline);
+ console.log("shutdown complete");
+ process.exit(0);
+ })().catch(() => process.exit(1));
+ });