Dev CLI npx jamsocket dev

Use Jamsocket's Dev CLI for faster local development. The Dev CLI

  • automatically watches and rebuilds session backend docker images as you develop
  • runs a dev server that emulates Jamsocket's spawn and status APIs
  • streams statuses and logs from your session backend to the terminal

Running the Dev CLI

Running the Dev CLI is as easy as running npx jamsocket dev with the flag -d that specifies the Dockerfile that should be built. In most instances, you'll also want to supply the -w flag that watches a file or directory to automatically rebuild your code on save.

npx jamsocket dev -d ./Dockerfile -w .

Available flags:

  • -d, --dockerfile=VALUE Path to the session backend's Dockerfile
  • -p, --port=VALUE The port to run the dev server on. (Defaults to 8080)
  • -w, --watch=VALUE... A file or directory to watch for changes

Use npx jamsocket dev --help for more info.

Optional: Create a jamsocket.config.js file

Optionally use a jamsocket.config.js to configure your Dev CLI instead of passing flags.


If you supply configuration instructions via flags, it will override or take the place of the jamsocket.config.js.

Create a jamsocket.config.js file in the directory where you run the dev command. Provide the following parameters:

  • dockerfile - specify the path to the Dockerfile that buids your session backend code.
  • watch - specify array of paths to watch for changes and automatically build your session backend code. If a watch array isn't specified, the Dev CLI will not rebuild on changes.
  • port - specify port to run the dev server on (defaults to 8080)

For example:

module.exports = {
  dockerfile: './src/session-backend/Dockerfile',
  watch: ['./src/session-backend'], // optional
  port: 8888, // optional, defaults to 8080


Given a Dockerfile that looks like this:

FROM node:18
COPY . .
RUN npm install
CMD ["node", "main.js"]

And a config that looks like this:

module.exports = {
  dockerfile: './src/session-backend/Dockerfile',
  watch: ['./src/session-backend'],
  port: 8888,

Running npx jamsocket dev will start a Jamsocket dev server at localhost:8888. The Dockerfile (at src/session-backend/Dockerfile) will be built into a local Docker image.

Then, when you spawn a session backend with a request like so:

curl -X POST http://localhost:8888/user/my-account/service/my-service/spawn

You'll get back a URL that will look like http://localhost:9090/tYVHfS4PKgufdhwGCnn6LLfAaCo_iAHitbw4Bg8ETjA/. Requests sent to this URL will be routed to your session backend. (You can see an example Dockerfile and NodeJS server in the Quickstart.)

You can replace my-account and my-service in the spawn endpoint with any dummy value. They are ignored in development.
Jamsocket is built by Drifting in Space.